fiddy/.github/copilot-instructions.md

Copilot Instructions — Fiddy (External DB)

Source of truth

• Always consult PROJECT_INSTRUCTIONS.md at the repo root.
• If any guidance conflicts, PROJECT_INSTRUCTIONS.md takes precedence.
• Keep this file focused on architecture/stack; keep checklists and project workflow rules in PROJECT_INSTRUCTIONS.md.
• When asked to fix bugs, follow DEBUGGING_INSTRUCTIONS.md at the repo root.

Stack

• Monorepo (npm workspaces)
• Next.js (App Router) + TypeScript + Tailwind
• External Postgres (on-prem server) via node-postgres (pg). No ORM.
• Docker Compose dev/prod
• Gitea + act-runner CI/CD

Environment

• Dev and Prod must use the same schema/migrations (packages/db/migrations).
• DATABASE_URL points to the external DB server (NOT a container).

Auth

• Custom email/password auth.
• Use HttpOnly session cookies backed by DB table sessions.
• NEVER trust client-side RBAC checks.

Receipts

• Store receipt images in Postgres bytea table receipts.
• Entries list endpoints must not return image bytes.
• Image bytes only fetched by separate endpoint when inspecting a single item.

UI

• Dark mode, minimal, mobile-first.
• Dodger Blue accent (#1E90FF).
• Top navbar: left nav dropdown, middle group selector, right user menu.

Code Rules

• Small files, minimal comments.
• Prefer single-line if without braces when only one line follows.
• Heavy logic lives in components/hooks/services, not page files.
• Prefer API calls via exported hooks/services for reusability and cleanliness (avoid raw fetch in components when possible).
• Add/update unit tests with changes (TDD).
• Heavy focus on code readability and maintainability; prioritize clean code over clever code.
  • ie. Separating different concerns into different files, and adding helper functions to avoid nested logic and improve readability, is preferred over clever one-liners or consolidating logic into fewer files.
  • ie. Separate groups of related codes by adding 3 line breaks between them

Data Model

• Users (system_role USER|SYS_ADMIN)
• Groups + membership (group_role MEMBER|GROUP_ADMIN)
• Entries (group-scoped) + optional receipt_id
• User settings (jsonb)
• Reports for system admins

Architecture Contract (Backend ↔ Client ↔ Hooks ↔ UI)

No-Assumptions Rule (Required)

• Before making structural changes, first scan the repo and identify:
  • the web app root (where app/, components/, hooks/, lib/ live)
  • existing API routes and helpers
  • existing patterns already in use
• Do not invent files, endpoints, or conventions. If something is missing, add it minimally and consistently.

Layering (Hard Boundaries)

For every domain (auth, groups, entries, receipts, etc.), keep a consistent 4-layer flow:

1. API Route Handlers (app/api/.../route.ts)

• Thin: parse input, call a server service, return JSON.
• No direct DB queries inside route files unless there is no existing server service.
• Must enforce auth & membership checks on server.

2. Server Services (DB + authorization) (lib/server/*)

• Own all DB access and authorization helpers (sessions, requireGroupMember, etc.).
• Server-only modules must include import "server-only";
• Prefer small domain modules: lib/server/auth.ts, lib/server/groups.ts, lib/server/entries.ts, lib/server/session.ts.

3. Client API Wrappers (lib/client/*)

• Typed fetch helpers only (no React state).
• Centralize fetchJson() / error normalization.
• Always send credentials (cookies) and never trust client-side RBAC.

4. Hooks (UI-facing API layer) (hooks/use-*.ts)

• Hooks are the primary interface for components/pages to call APIs.
• Components should not call fetch() directly unless there’s a strong reason.

Domain Blueprint (Consistency Rule)

For any new feature/domain, prefer:

• app/api/<domain>/...
• lib/server/<domain>.ts
• lib/client/<domain>.ts
• hooks/use-<domain>.ts
• components/<domain>/*
• __tests__/<domain>.test.ts

API Conventions

• Prefer consistent JSON response shape for errors:
  • { error: { code: string, message: string } }
• Validate inputs at the route boundary (basic shape/type), and validate authorization in server services.
• When adding endpoints, mirror existing REST style used in the project.

Non-Regression Contracts (Do Not Break)

• Entries list endpoints must never include receipt image bytes; image bytes are fetched via a separate endpoint only.
• Auth is DB-backed HttpOnly sessions; all auth checks are server-side.
• Groups require server-side membership checks; active group persists per user.
• Group invite codes:
  • shown once immediately after group creation
  • modal renders outside navbar/header so it overlays the viewport correctly
  • avoid re-exposing invite code elsewhere without explicit “group settings” work

UI Structure

• Page files stay thin; heavy logic stays in hooks/services/components.
• Dark mode, minimal, mobile-first.
• Dodger Blue accent (#1E90FF).
• Navbar: left nav dropdown, middle group selector, right user menu.

Environment

• Dev and Prod must use the same schema/migrations (packages/db/migrations).
• DATABASE_URL points to external Postgres (NOT a container).
• DATABASE_URL format must be a full connection string; URL-encode special chars in passwords.

Tests (Required)

• Add/update tests for API behavior changes:
  • auth
  • groups
  • entries (group scoping)
• Tests must include negative cases: unauthorized, not-a-member, invalid inputs.