JSM DocsMarkdown aus /home/ag/codex

storymaster/README.md

storymaster/README

JSM Portal

Storymaster

Storymaster ist eine modulare Admin-Anwendung auf Basis von Laravel 12 und Backpack. Das Projekt laeuft eigenstaendig (ohne externe Host-Anwendung) und buendelt mehrere Fachmodule unter einer zentralen Admin-Oberflaeche.

Tech-Stack

  • PHP 8.2+
  • Laravel 12
  • Backpack CRUD / Backpack Pro / Theme Tabler
  • MySQL 8
  • Vite + TailwindCSS
  • nwidart/laravel-modules fuer modulare Struktur

Features auf einen Blick

  • Zentrale Admin-Oberflaeche unter /admin
  • Rollen- und Berechtigungsmodell (Spatie Permission)
  • Mehrere aktivierte Fachmodule (u. a. Storymaster, Note, Tag, Document, Contact, ActivityLog, Facility, Meter, OneClickTask, Tenant)
  • Standard-Seed-Daten fuer schnellen Einstieg in Entwicklungsumgebungen

Voraussetzungen

Lokale Entwicklung

  • PHP 8.2+
  • Composer
  • Node.js + npm
  • MySQL

Docker-Entwicklung (optional)

  • Docker + Docker Compose

Schnellstart (lokal)

git clone <repository-url>
cd storymaster
composer install
cp .env.example .env
php artisan key:generate

Danach .env pruefen, insbesondere:

APP_URL=http://localhost:8000
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=storymaster_v1
DB_USERNAME=root
DB_PASSWORD=

Datenbank vorbereiten und Assets bauen:

php artisan migrate
php artisan db:seed
php artisan storage:link
npm install
npm run build

Anwendung starten:

php artisan serve

App aufrufen: http://127.0.0.1:8000

Schnellstart mit Docker

Im Repository ist ein docker-compose.yml enthalten.

docker compose up --build

Danach laeuft die Anwendung standardmaessig auf:

Hinweis: Die Compose-Konfiguration setzt FRESH_DB_ON_START=true.

Nuetzliche Composer-Skripte

  • composer setup
    Installiert Abhaengigkeiten, legt .env an (falls nicht vorhanden), erzeugt App-Key, fuehrt Migrationen aus und baut Frontend-Assets.

  • composer dev
    Startet lokale Entwicklungsprozesse parallel:

    • Laravel Server
    • Queue Listener
    • Vite Dev Server

  • composer test
    Leert Config-Cache und fuehrt die Test-Suite aus.

Standard-Logins nach Seeding (Development)

Nach php artisan db:seed werden u. a. diese Benutzer angelegt:

  • Power User: power@power.com / power
  • Test User: test@test.com / test

Bitte Passwoerter in nicht-lokalen Umgebungen sofort aendern.

Projektstruktur (Kurzueberblick)

  • app/ - Laravel Core-Anwendung
  • Modules/ - Fachmodule (Laravel Modules)
  • resources/ - Views, Frontend-Ressourcen
  • routes/ - Routing (Root leitet auf /admin weiter)
  • database/seeders/ - Seeder fuer Rollen, Rechte und Testnutzer
  • docker/ + docker-compose.yml - Container-Setup

Tests

composer test

Die Tests laufen gegen SQLite In-Memory (siehe phpunit.xml).

Troubleshooting

500-Fehler / veraltete Caches

php artisan optimize:clear

Frontend-Assets fehlen

npm install
npm run build

Dateirechte (Linux)

chmod -R 775 storage bootstrap/cache

Datenbank komplett neu aufsetzen

php artisan migrate:fresh --seed

Achtung: Dieser Befehl loescht alle Tabellen.

Sicherheitshinweis

Die in den Seedern enthaltenen Standard-Accounts sind nur fuer lokale Entwicklung gedacht. In Staging/Produktion sollten keine Default-Credentials verwendet werden.

Storymaster Standalone

Storymaster is a standalone Laravel 12 + Backpack application for managing product documentation and internal planning.

This repository runs independently and does not require Cosmos.

Docker Start (recommended)

1. Start everything

chmod +x start.sh docker/app/start.sh
./start.sh

This starts:

On every app container start, docker/app/start.sh runs:

  • php artisan migrate:fresh --seed --force (default)
  • php artisan storage:link (if needed)

If you want non-destructive startup migrations, set in docker-compose.yml:

FRESH_DB_ON_START: "false"

Then startup will run:

  • php artisan migrate --force
  • php artisan db:seed --force

2. Stop containers

docker compose down

3. Stop + remove database volume

docker compose down -v

Requirements

  • PHP 8.2+
  • Composer
  • MySQL
  • Web server (Apache, Nginx, or php artisan serve)

Installation (Step-by-Step)

1. Clone Repository

git clone <repository-url>
cd storymaster

2. Install Dependencies

composer install

3. Setup Environment

cp .env.example .env
php artisan key:generate

Update database credentials in .env:

DB_DATABASE=storymaster
DB_USERNAME=root
DB_PASSWORD=

4. Create Database

Create a database named:

storymaster

Then run:

php artisan migrate

php artisan db:seed

5. Link Storage

php artisan storage:link

6. Run Application

php artisan serve

Open:

http://127.0.0.1:8000

Standalone Usage

After installation:

  1. Register an account
  2. Access /admin
  3. Use modules (Ideas, User Stories, CRM, etc.)
  4. Create, edit, and manage records

The system operates independently with its own:

  • Authentication
  • Database migrations
  • Admin panel
  • Project-based data filtering

Typical Usage Example

Creating a Record

  1. Login to /admin
  2. Select a module
  3. Click “Create”
  4. Fill in required fields
  5. Save

Troubleshooting

500 Error

php artisan config:clear
php artisan cache:clear
php artisan route:clear
php artisan view:clear

Permission Issues (Linux)

chmod -R 775 storage bootstrap/cache

Migration Issues

php artisan migrate:fresh

⚠ This deletes all tables.

Summary

Storymaster standalone can run on any environment that supports:

  • PHP 8.2+
  • MySQL
  • Composer

No external application dependency required.