roaauto/CLAUDE.md

CLAUDE.md

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

Project Overview

ROA AUTO is a multi-tenant auto service management PWA. The architecture is offline-first: the Vue 3 frontend uses wa-sqlite (WebAssembly SQLite) running entirely in the browser as :memory:, with a sync engine that pulls from and pushes to the FastAPI backend. All business data lives locally in the browser's in-memory SQLite DB and is periodically synced.

Development Commands

Backend (FastAPI)

cd backend
source .venv/bin/activate
uvicorn app.main:app --port 8000 --reload   # start dev server
pytest tests/ -v                             # run all tests
pytest tests/test_orders.py -v              # run single test file
pytest tests/test_orders.py::test_name -v  # run single test

Frontend (Vue 3 + Vite)

cd frontend
npm run dev      # start dev server (port 5173)
npm run build    # production build

Docker (preferred for full stack)

make dev         # start all services (docker-compose.dev.yml)
make test        # run backend tests in container
make migrate     # run alembic migrations
make seed        # seed demo data

Architecture

Sync Model (critical to understand)

• Frontend writes locally first, then queues changes in _sync_queue (SQLite table)
• SyncEngine (frontend/src/db/sync.js) handles three operations:
  • fullSync() — downloads all tenant data from /api/sync/full on login
  • incrementalSync() — downloads changes since last_sync_at
  • pushQueue() — uploads queued local changes to /api/sync/push
• The backend sync service (backend/app/sync/service.py) defines SYNCABLE_TABLES — only these tables are synced
• IDs are crypto.randomUUID() generated client-side; backend uses INSERT OR REPLACE

Frontend (frontend/src/)

• db/database.js — singleton wa-sqlite instance. Uses :memory: only (no IndexedDB persistence). execSQL(sql, params) is the only query interface. Parameterized queries must use sqlite3.statements() async generator — exec() does not support ? params. Do NOT use prepare_v2 (doesn't exist in this library).
• db/schema.js — full SQLite schema as a string constant, applied on init
• db/sync.js — SyncEngine class, exported as singleton syncEngine
• stores/ — Pinia stores (auth.js, orders.js, vehicles.js) wrapping execSQL calls
• views/ — one file per route; data loaded via execSQL directly or through stores
• Reactivity — notifyTableChanged(table) / onTableChange(table, cb) in database.js provide a pub/sub for cross-component updates. Call notifyTableChanged after any write.

Backend (backend/app/)

• Multi-tenant: every model has tenant_id. All queries filter by tenant_id from the JWT.
• Auth: JWT in Authorization: Bearer header. get_tenant_id dep extracts tenant from token.
• deps.py — get_current_user and get_tenant_id FastAPI dependencies used across all routers
• sync/ — The most complex module. apply_push does INSERT OR REPLACE for all ops.
• pdf/ — WeasyPrint + Jinja2 HTML templates to generate PDF deviz/factura
• client_portal/ — Public routes (no auth) for client-facing deviz view via token_client
• DB: SQLite via SQLAlchemy async (aiosqlite). Alembic for migrations (files in alembic/versions/).

Key Data Flow: Order Lifecycle

DRAFT → VALIDAT → FACTURAT

• Order lines (manopera/material) added only in DRAFT
• PDF deviz available after VALIDAT
• Invoice created locally in handleFactureaza() then queued for sync

Critical wa-sqlite Notes

• Import: wa-sqlite.mjs (sync WASM build), NOT wa-sqlite-async.mjs
• All API methods (open_v2, exec, step, finalize) return Promises — always await
• For parameterized queries: for await (const stmt of sqlite3.statements(db, sql)) then sqlite3.bind_collection(stmt, params)
• vite.config.js excludes @journeyapps/wa-sqlite from optimizeDeps
• COOP/COEP headers (Cross-Origin-Opener-Policy: same-origin + Cross-Origin-Embedder-Policy: require-corp) are required for SharedArrayBuffer used by wa-sqlite — set in vite dev server and nginx

WSL2 Note

Running on WSL2 with code on Windows NTFS (/mnt/e/): Vite is configured with server.watch.usePolling: true, interval: 1000 to work around inotify not firing on NTFS mounts.

Testing

• Backend tests use an in-memory SQLite DB (overrides get_db via app.dependency_overrides)
• asyncio_mode = auto set in pytest.ini — no need to mark tests with @pytest.mark.asyncio
• auth_headers fixture registers a user and returns Authorization header for authenticated tests
• Demo credentials (after make seed): demo@roaauto.ro / demo123

Execution Preferences

• Executia task-urilor se face cu team agents (nu cu skill superpowers subagents)
• Playwright testing obligatoriu: orice implementare majora trebuie testata E2E cu Playwright
  • Desktop: 1280x720, Mobile: 375x812
  • Verificari: responsive, elemente nu se suprapun, nu ies din ecran, butoane cu gap suficient
  • Raportul Playwright se salveaza in docs/playwright-report-YYYY-MM-DD.md

Data Model: Clients

• Tabel clients - nomenclator clienti cu date eFactura ANAF, separat de vehicule
• Un client poate avea mai multe vehicule (1:N prin client_id pe vehicles)
• tip_persoana: PF (persoana fizica) / PJ (persoana juridica)
• Campuri eFactura: cod_fiscal, reg_com, adresa, judet, oras, cod_postal, cont_iban, banca

Data Model: Invoices

• tip_document: FACTURA (B2B, eFactura ANAF) sau BON_FISCAL (B2C, casa de marcat)
• Factura: necesita date client complete (CUI, adresa)
• Bon fiscal: format simplificat

Order Lifecycle

• DRAFT → VALIDAT → FACTURAT (cu devalidare VALIDAT → DRAFT)
• Stergere: orice nefacturat; FACTURAT = sterge factura intai
• Edit header doar in DRAFT