From 3469284e985e2783bd50ee87fffaa793a0fe998d Mon Sep 17 00:00:00 2001 From: Nico Date: Mon, 16 Feb 2026 01:49:44 -0800 Subject: [PATCH] docs: add project state audit and execution plan --- docs/PROJECT_STATE_AUDIT.md | 57 +++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 docs/PROJECT_STATE_AUDIT.md diff --git a/docs/PROJECT_STATE_AUDIT.md b/docs/PROJECT_STATE_AUDIT.md new file mode 100644 index 0000000..b1ef654 --- /dev/null +++ b/docs/PROJECT_STATE_AUDIT.md @@ -0,0 +1,57 @@ +# 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.