thats-me/AGENTS.md

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.