fiddy/PROJECT_INSTRUCTIONS.md

Project Instructions — Fiddy (External DB)

Core expectation

This project connects to an external Postgres instance (on-prem server). Dev and Prod must share the same schema through migrations.

Decisions / constraints (Group Settings)

• Add GROUP_OWNER role to group roles; migrate existing groups so the first admin becomes owner.
• Join policy default is NOT_ACCEPTING. Policies: NOT_ACCEPTING, AUTO_ACCEPT, APPROVAL_REQUIRED.
• Both owner and admins can approve join requests and manage invite links.
• Invite links:
  • TTL limited to 1–7 days.
  • Settings are immutable after creation (policy, single-use, etc.).
  • Single-use does not override approval-required.
  • Expired links are retained and can be revived.
  • Single-use links are deleted after successful use.
  • Revive resets used_at and revoked_at, refreshes expires_at, and creates a new audit event.
• No cron/worker jobs for now (auto ownership transfer and invite rotation are paused).
• API must generate request_id and return it in responses; audit logs must include it.
• Audit logs must never store full invite codes (store last4 only).

Do first (vertical slice)

1. DB migrate command + schema
2. Register/Login/Logout (custom sessions)
3. Protected dashboard page
4. Group create/join + group switcher (approval-based joins + optional join disable)
5. Entries CRUD (no receipt bytes in list)
6. Receipt upload/download endpoints
7. Settings + Reports

Definition of done

• Works via docker-compose.dev.yml with external DB
• Migrations applied via npm run db:migrate
• Tests + lint pass
• RBAC enforced server-side
• No large files
• No TypeScript warnings or lint errors in touched files
• No new cron/worker dependencies unless explicitly approved

Desktop + mobile UX checklist (required)

• Touch: long-press affordance for item-level actions when no visible button.
• Mouse: hover affordance on interactive rows/cards.
• Tap targets remain >= 40px on mobile.
• Modal overlays must close on outside click/tap.
• Use bubble notifications for main actions (create/update/delete/join).
• Add Playwright UI tests for new UI features and critical flows.
• Group role icons must be consistent: 👑 owner, 🛡️ admin, 👤 member.

PR review checklist

• Desktop + mobile UX checklist satisfied (hover + long-press where applicable).
• No TypeScript warnings or lint errors introduced.