# 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.