# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

"That's Me" is a full-stack offline-first web application with a Quasar/Vue.js 3 frontend and a Laravel 12 backend, orchestrated via Docker Compose with Traefik reverse proxy.

## Architecture

The project is a monorepo with two independent applications:

- **`frontend/`** — Quasar v2 SPA (Vue.js 3, Pinia, Vite). Serves the user-facing app at `app.thats-me.test`. Designed as offline-first with IndexedDB (via Dexie.js) for local storage and sync queue.
- **`backend/`** — Laravel 12 (PHP 8.4). Serves multiple roles via separate domains:
  - `thats-me.test` — Public landing page (Blade + Tailwind + Flux UI)
  - `portal.thats-me.test` — Admin panel (Livewire/Volt + Tailwind + Flux UI)
  - `api.thats-me.test` — REST API for the Quasar frontend (OAuth2 via Laravel Passport)
  - `assets.thats-me.test` — Vite dev server (HMR)

Data flow: User interaction → Vue component → Pinia store → IndexedDB → Sync queue → Laravel REST API → MySQL / Synology C2 Object Storage (for multimedia).

## Development Environment (Docker)

Requires Docker Desktop and a Traefik proxy network (`docker network create proxy`). Add domains to `/etc/hosts` pointing to `127.0.0.1`.

```bash
# Start all services
docker-compose up -d

# Access containers
docker-compose exec laravel.test bash    # Laravel (PHP)
docker-compose exec quasar.app sh        # Quasar (Node)
docker-compose exec mysql mysql -u sail -p  # MySQL (password: password)
```

### Services & Ports

| Service        | Port  | Purpose                    |
|----------------|-------|----------------------------|
| quasar.app     | 9000  | Quasar frontend dev server |
| mysql           | 33070 | MySQL database             |
| mailpit         | 8028  | Email testing dashboard    |
| redis           | 6383  | Cache & queue              |
| laravel.test   | 5180  | Vite dev server (HMR)     |

## Common Commands

### Backend (run inside `laravel.test` container or prefix with `docker-compose exec laravel.test`)

```bash
composer dev                                    # Full dev environment (server + queue + pail + npm dev)
php artisan serve                               # Laravel server only
php artisan test --compact                      # Run all tests (Pest v3)
php artisan test --compact --filter=testName    # Run specific test
vendor/bin/pint --dirty --format agent          # Format code (Laravel Pint)
php artisan migrate                             # Run database migrations
php artisan db:seed                             # Seed database
npm run build                                   # Build backend assets with Vite
```

### Frontend (run inside `quasar.app` container or from `frontend/` directory)

```bash
npm run dev       # Quasar dev server with HMR
npm run build     # Production build
npm run lint      # ESLint check
npm run format    # Prettier formatting
```

## Backend Conventions

The `backend/CLAUDE.md` file contains comprehensive Laravel Boost guidelines that must be followed. Key points:

- **PHP 8.4** with constructor property promotion, explicit return types, curly braces for all control structures
- **Testing**: Every change must be tested with Pest v3. Run `php artisan test --compact` with filter for targeted runs. Create tests with `php artisan make:test --pest {name}`.
- **Code formatting**: Always run `vendor/bin/pint --dirty --format agent` before finalizing changes.
- **Artisan generators**: Use `php artisan make:*` commands with `--no-interaction` to create files (controllers, models, migrations, etc.)
- **Database**: Prefer Eloquent over raw queries. Use `Model::query()` instead of `DB::`. Use eager loading to prevent N+1.
- **Config**: Never use `env()` outside config files; use `config()` instead.
- **Admin Panel UI**: Livewire + Volt (single-file components) styled with Tailwind CSS v4 + Flux UI (`<flux:*>` components)
- **Laravel Boost MCP**: Use `search-docs`, `tinker`, `database-query`, `database-schema`, and `list-artisan-commands` tools when available.

## Frontend Conventions

- **State management**: Pinia stores in `frontend/src/stores/`
- **Routing**: Vue Router with hash mode, config in `frontend/src/router/`
- **UI framework**: Quasar components (preferred over custom HTML). Tailwind CSS only for specific customizations.
- **Animation**: Anime.js for the "LifeWave" SVG visualization
- **Build target**: ES2022, Firefox 115+, Chrome 115+, Safari 14+
- **Dev server host**: `app.thats-me.test` on port 9000