Kevin Adametz
10251e4f41
- dev/: Ticketliste, Audit und Vorschläge vom 17.09., Logo-SVGs, Lifeline-Bildwerkzeuge. - AGENTS.md auf den aktuellen Stand (syncQueue statt syncService, kein legacy-Ordner mehr). - .codex/ und __pycache__/ ignoriert; Playwright-MCP in .mcp.json. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
85 lines
4.9 KiB
Markdown
85 lines
4.9 KiB
Markdown
# Repository guidance
|
|
|
|
## Scope and sources
|
|
|
|
This file applies to the repository. Follow `backend/AGENTS.md` for additional
|
|
Laravel-specific instructions when working under `backend/`.
|
|
Check neighboring code before changing conventions. Prefer current source,
|
|
package manifests, and `docker-compose.yml` over older setup examples; some
|
|
README and architecture documents contain placeholders or describe planned work.
|
|
|
|
## Project map
|
|
|
|
- `frontend/`: Quasar 2 SPA using Vue 3, Pinia, Vue Router, Vite, and Dexie.
|
|
The active experience uses `src/pages/LifeWavePage.vue`,
|
|
`src/layouts/LifeWaveLayout.vue`, and components such as `TimelineView.vue`,
|
|
`FloatingLines.vue`, and `EventPanel.vue`.
|
|
- `frontend/src/stores/`: authentication, settings, and event state.
|
|
`src/services/apiClient.js` centralizes API requests and bearer tokens;
|
|
`src/services/syncQueue.js` holds the offline write queue every remote
|
|
write goes through (see `test/vitest/events-offline.spec.js`);
|
|
`src/db/index.js` defines versioned IndexedDB schemas.
|
|
- `backend/`: Laravel 12 API and website, with Passport authentication,
|
|
Livewire/Volt, Flux UI, and Tailwind CSS 4. API routes are in `routes/api.php`;
|
|
application code is in `app/`, Blade views in `resources/views/`, and
|
|
migrations in `database/migrations/`.
|
|
- `dot-line-system/`: separate Vite/TypeScript visualization experiment.
|
|
Root `test/` contains HTML animation experiments, not an automated test suite.
|
|
- `frontend/dev/db-api-connect/`: API migration plans and implementation log.
|
|
Read the relevant documents for changes to persistence or API contracts,
|
|
distinguishing planned features from implemented behavior.
|
|
|
|
## Commands and validation
|
|
|
|
There is no root package manifest. Run commands from the relevant application.
|
|
|
|
| Directory | Command | Purpose |
|
|
| --- | --- | --- |
|
|
| `frontend/` | `npm ci` | Install locked dependencies |
|
|
| `frontend/` | `npm run dev` | Start Quasar; this script also runs `npm install` |
|
|
| `frontend/` | `npm run lint` | Check JavaScript and Vue source with ESLint |
|
|
| `frontend/` | `npm run build` | Build the production SPA |
|
|
| `backend/` | `composer install` | Install PHP dependencies |
|
|
| `backend/` | `npm ci` | Install backend asset dependencies |
|
|
| `backend/` | `composer dev` | Run server, queue listener, logs, and Vite |
|
|
| `backend/` | `npm run build` | Build backend assets |
|
|
| `backend/` | `php artisan test --compact --filter=TestName` | Run targeted Pest tests |
|
|
| `backend/` | `php artisan test --compact` | Run the backend suite |
|
|
| `backend/` | `vendor/bin/pint --dirty --format agent` | Format changed PHP per backend guidance |
|
|
|
|
For frontend code changes, run lint and the production build as appropriate.
|
|
`npm test` in `frontend/` is a placeholder that exits successfully without
|
|
running tests; do not report it as test coverage. Manually check affected UI
|
|
behavior when possible. Backend tests live in `backend/tests/`; API feature
|
|
tests cover authentication, events, settings, and media. The PHPUnit config
|
|
forces an in-memory SQLite database, while the application uses MySQL.
|
|
Report any checks that could not run and the reason.
|
|
|
|
The root Compose file defines `laravel.test` (PHP 8.4) and `quasar.app` (Node 20).
|
|
It relies on an external `proxy` network and shared `global-mysql`,
|
|
`global-mailpit`, and `global-redis` services. It does not provision those
|
|
services or Traefik. With that infrastructure available, use
|
|
`docker compose up -d`; application commands can run through
|
|
`docker compose exec laravel.test ...` or `docker compose exec quasar.app ...`.
|
|
|
|
## Implementation conventions
|
|
|
|
- Use existing Quasar components and Vue/Pinia patterns. Frontend formatting is
|
|
two spaces, single quotes, no semicolons, and a 100-character print width.
|
|
Format changed files rather than running a repository-wide formatting pass.
|
|
- Router definitions live in `frontend/src/router/routes.js`; Quasar currently
|
|
uses hash routing. Keep network access in the existing API client and stores.
|
|
The API base can be configured with `VITE_API_BASE`.
|
|
- Laravel/MySQL is the intended authoritative store; IndexedDB and localStorage
|
|
support caching and offline behavior during the migration. Inspect the current
|
|
stores before assuming all writes use the sync queue. Preserve user scoping,
|
|
existing cached data, and stable event/client IDs when changing persistence.
|
|
- Enforce ownership on the backend for user settings, events, and media.
|
|
Preserve authorized media delivery and test cross-user access restrictions.
|
|
- Follow backend guidance for typed PHP, Eloquent, Form Requests, Artisan
|
|
generators, Pest tests, and Pint. Keep environment lookups in config files.
|
|
- Keep `frontend/src/config/appVersion.js`, `frontend/package.json`, and version
|
|
documentation consistent. Document data-model and API-contract changes in
|
|
the existing DB/API migration documents.
|
|
- Keep credentials out of source and logs. Avoid editing dependency directories
|
|
or generated build output; retain lockfiles when changing dependencies.
|