pfm-ocr/backend/SKILLS.md

Skills & Roles (backend)

Backend-scoped copy of the root SKILLS.md — same five roles, applied to backend/ surfaces (Next.js API gateway, OCR pipeline, Postgres, Docker/deploy) during n/next execution (see AGENTS.md Part B, this dir). One agent can play all of them in sequence; a multi-agent harness may spawn each as a separate subagent for a fresh-context pass. Order matters: Architect → Backend/Frontend → QA → Hardware/Compatibility.

1. Software Architect

Responsibilities

• Decide where new backend code lives; keep module boundaries clean (API routes vs. utils/ business logic vs. db/ layer vs. the Python pipeline in config/).
• Prefer deep modules (few, well-bounded files with simple interfaces) over shallow ones — this is what keeps the codebase navigable for an agent.
• Own the 256-LOC split rule (AGENTS.md Part B §B3): when a file crosses the threshold, decide the split boundary before anyone patches around it.
• Keep plans/next-enhancements.md (this dir) structured by real backend module boundaries, not arbitrary groupings.
• Owns the existing-project audit (AGENTS.md Part B §B0) for backend specifically.

When invoked: start of every e/enhance run; start of every n/next task, before implementation begins.

Handoff: hands the Backend/Frontend roles a target file layout and interface contract, not just a task description.

2. Backend Engineer

Responsibilities

• Implement Next.js API route logic, DB access (src/db/), and the Python OCR pipeline (config/classify_ocr_server.py, pipeline API) as the task requires.
• Wire the mock-vs-live routing required by the Demo/Live switch (AGENTS.md Part B §B5) and the Cloud/Local endpoint switch (§B6) if/when built — both must resolve through the same contract so swapping either setting never changes calling code.
• Keep business logic out of route handlers (src/app/api/**/route.ts); route handlers stay thin, matching the existing utils/parser.ts-style separation.
• Use withTransaction (src/db/index.ts) for any multi-statement write that must be atomic — see task 7.1 in the pre-kit history for why this matters here.

When invoked: any task touching API routes, the DB layer, or the OCR pipeline.

Handoff: gives Frontend a stable contract (types/response shape) to build against; gives QA the list of new/changed endpoints and their expected error modes.

3. Frontend Engineer

Responsibilities

• Implement UI for the task inside pfm-web-app/src/app/, including Demo/Live and Cloud/Local switcher controls where relevant.
• Follow this repo's existing page pattern: consolidated single-page flows (root page.tsx) vs. standalone-purpose route folders (manual-label/page.tsx, scan-pfm/page.tsx) — see backend CLAUDE.md for which pattern a given feature should follow.
• Consume the Backend Engineer's contract rather than reaching around it.
• Keep components small and composable, respecting the 256-LOC rule.

When invoked: any task with a user-facing surface inside pfm-web-app/.

Handoff: gives QA the golden-path user flow and the edge cases it's aware of.

4. QA / Test Engineer

Responsibilities

• During clarification (AGENTS.md Part B §B2a), turn resolved answers into concrete acceptance criteria — what "done" verifiably means.
• Write/extend automated tests (parser.test.ts pattern) for the change.
• For anything touching parser.ts or the OCR pipeline, run the accuracy regression harness (node pfm-web-app/scripts/accuracy-check.mts or accuracy-check-scan.mts) and check for regressions against the current baseline (see sources/accuracy_history.jsonl and sources/product_accuracy_history.jsonl for latest metrics), not just "it compiles."
• Run the verify build integrity pass: golden path + edge cases + regression check on adjacent features.
• Reject work back to the relevant role if acceptance criteria aren't met — don't patch around a failing check.

When invoked: acceptance-criteria drafting during §B2a; final verification pass before a task is marked [DONE].

Handoff: reports pass/fail with specifics (what broke, under what input) back to whichever role owns that surface.

5. Hardware & Performance Compatibility Reviewer

Responsibilities

• Check the change against this stack's real constraints: single vs. dual-GPU dev mode (docker-compose.yml runs npm run dev, a known throughput ceiling), VRAM budget for vLLM (gpu-memory-utilization in config/vllm_config.yaml), and behavior under the Local/on-prem deployment mode from AGENTS.md Part B §B6.
• Flag newly introduced heavy Python/Node dependencies, GPU-specific assumptions, or anything that would break the isolated vLLM-server-only environment (no paddlepaddle-gpu in this venv — see AGENTS.md Part A / docs/vllm-service.md).
• Flag anything that would degrade badly on lower-spec hardware or slower networks (e.g. the mobile app's 2s polling loop against a slow backend response), and suggest a lighter-weight alternative when one exists.

When invoked: final verification pass, alongside QA, before a task is marked [DONE]; also whenever a task adds a new dependency or changes the deployment/ runtime surface.

Handoff: blocks [DONE] status until concerns are resolved or explicitly accepted as a documented trade-off in docs/feature-list.md (this dir).