# Project State Audit - Fiddy

Snapshot date: 2026-02-16

## 1) Confirmed stack and structure
- Backend: Express API in `backend/` with `routes/`, `controllers/`, `models/`, `middleware/`, `utils/`.
- Frontend: React + Vite in `frontend/` with API wrappers in `frontend/src/api`, auth/state in `frontend/src/context`, pages in `frontend/src/pages`.
- DB migrations: canonical folder is `packages/db/migrations`.

## 2) Governance and agentic setup status
- Present and aligned:
  - `PROJECT_INSTRUCTIONS.md`
  - `AGENTS.md`
  - `DEBUGGING_INSTRUCTIONS.md`
  - `docs/DB_MIGRATION_WORKFLOW.md`
  - `docs/AGENTIC_CONTRACT_MAP.md`
- Commit discipline added in `PROJECT_INSTRUCTIONS.md` section 12 and being followed with small conventional commits.

## 3) Current implementation status vs vertical-slice goals
1. DB migrate command + schema:
   - Implemented: root scripts `db:migrate`, `db:migrate:status`, `db:migrate:verify`.
   - Implemented: migration tracking + runbook.
2. Register/Login/Logout (custom sessions):
   - Implemented: DB sessions table migration (`create_sessions_table.sql`).
   - Implemented: session model, HttpOnly cookie set/clear, `/auth/logout`, auth middleware fallback to DB session cookie.
   - Implemented: frontend credentialed API (`withCredentials`), logout route call.
3. Protected dashboard page:
   - Partially implemented via existing `PrivateRoute` token gate.
4. Group create/join + switcher:
   - Existing household create/join/switch flow exists but does not yet match all group-policy requirements.
5. Entries CRUD:
   - Existing list CRUD exists in legacy and multi-household paths.
6. Receipt upload/download endpoints:
   - Not implemented as dedicated receipt domain/endpoints.
7. Settings + Reports:
   - Settings page exists; reporting is not fully formalized.

## 4) Contract gaps and risks
- `DATABASE_URL` is now supported in runtime pool config, but local operator environment still needs this variable configured.
- No automated test suite currently exercises the new auth/session behavior; API behavior is mostly validated by static/lint checks.
- Group policy requirements (owner role, join policy states, invite lifecycle constraints, revive semantics) are not fully implemented.
- No explicit audit log persistence layer verified for invite events/request IDs.
- Encoding cleanliness needs ongoing watch; historical mojibake appears in some UI text/log strings.

## 5) Recommended next implementation order
1. Finalize auth session contract:
   - Add authenticated session introspection endpoint (`/users/me` already exists) to support cookie-only bootstrapping if token absent.
   - Update frontend auth bootstrap so protected routes work with DB session cookie as canonical auth.
2. Add explicit API tests (auth + households/list negative cases):
   - unauthorized
   - not-a-member
   - invalid input
3. Implement group-policy requirements incrementally:
   - owner role migration + policy enums
   - invite policy and immutable settings
   - approval-required flow + revive/single-use semantics
4. Add dedicated receipt domain endpoints (metadata list vs byte retrieval split) if the product scope requires the receipt contract verbatim.