where_woof/openspec/changes/laravel-admin/design.md

Context

Phase 1–3 built the GOAT frontend + shared Postgres (users, tags, scans, products, orders on .13:5434). Phase 4 adds the Laravel admin: a management UI for users, tags (with the product/order linkage built in Phase 2.5), products/orders, and a dashboard. It reuses the same DB — no sync layer.

Goals / Non-Goals

Goals:

• A working Laravel + Filament admin on .27 via Docker (no PHP installed natively).
• Reads/writes the shared Postgres on .13:5434 (single source of truth).
• Admin login gated by users.is_admin; full CRUD for users/tags/products/orders; dashboard stats.

Non-Goals:

• Billing/payments (Phase 5).
• Photo uploads in admin (frontend has it; admin can reuse photo_url display).
• Public-facing Laravel pages (this is admin-only for now).
• Laravel owning migrations yet — db/schema.sql stays canonical; Eloquent reads the existing tables.

Decisions

1. Docker dev on .27 — admin/docker-compose.yml with php:8.3-fpm + a composer bootstrap; php artisan serve --host=0.0.0.0 --port=3030. No PHP/Composer installed natively (keeps .27 clean). Docker volume mounts admin/ so edits are live.
2. Filament v3 for the admin panel (CRUD resources: User, Tag, Product, Order + dashboard stats). Rationale: the 2014 system needed forms-heavy admin; Filament is the Laravel-idiomatic generator and the best skills-update vehicle for Laravel conventions.
3. Shared DB via Eloquent — models map to the existing tables (users, tags, scans, products, orders). No migrations in Phase 4; db/schema.sql remains the source of truth (Laravel takes over migrations at deploy, generating from it). users.is_admin added via the existing idempotent ALTER in schema.sql.
4. Auth — Laravel's session auth + a middleware/policy: Filament::auth()->user()->is_admin gate. Seed one admin user (env-configured email, password from env).
5. Connection — admin/.env DB_CONNECTION=pgsql, DB_HOST=192.168.20.13, DB_PORT=5434, DB_DATABASE=wherewoof, DB_USERNAME=wherewoof, password via env (gitignored .env).

Risks / Trade-offs

• [Docker image pulls + composer install are slow first-time] → one-time cost; cached after.
• [Laravel writing to a schema it doesn't own] → read-only via Eloquent where possible; writes (tag product/order assignment, order status) are simple column updates already exercised by the GOAT app; migrations reconciled at deploy.
• [Shared users table across both apps] → is_admin flag only; no schema conflict.
• [NixOS Docker networking to .13] → plain TCP to 192.168.20.13:5434, already proven by the Go app.

Migration Plan

1. make db-up (adds users.is_admin).
2. admin/docker-compose.yml up → composer create-project laravel/laravel admin → filament install → models/resources.
3. Seed admin user; verify login + CRUD against the shared DB.

Open Questions

• Whether the admin gets public-facing pages later (likely not — the GOAT frontend serves the public).