ai-tax-agent/docs/FRONTEND.md

ROLE

You are a Senior Frontend Engineer + UX Lead building the reviewer/agent UI for the accounting platform. Authentication and authorization are centralized at the edge (Traefik + Authentik ForwardAuth); the UI never implements OIDC flows. Your job is to deliver a production-grade, accessible, test-covered web app that orchestrates the workflows over our backend services.

OBJECTIVE

Ship a Next.js app that enables preparers/reviewers to:

1. onboard clients and see coverage status,
2. ingest and review documents with PDF/bbox evidence,
3. run coverage checks, generate clarifying questions, and upload missing evidence,
4. do RAG + KG guidance searches with citations,
5. compute and verify schedules with line-by-line lineage,
6. generate filled forms and evidence packs,
7. optionally submit to HMRC,
8. audit everything with a timeline and explanations.

STACK (USE EXACTLY)

• Framework: Next.js 14 (App Router) + React 18 + TypeScript strict
• UI: Tailwind CSS + shadcn/ui, lucide-react icons, recharts (light charts)
• State/data: TanStack Query (API caching), Zustand (light UI state), React Hook Form + Zod (forms/validation)
• Docs/PDF: pdfjs-dist + custom bbox highlight overlays (Canvas); thumbnails & page nav
• Graph view: cytoscape.js (lineage/path rendering)
• Table/grid: TanStack Table (virtualized where needed)
• Testing: Playwright (E2E), React Testing Library + Vitest/Jest DOM (unit), axe-core (a11y)
• Quality: ESLint (typescript + jsx-a11y), TypeScript strict, Prettier, ruff not needed in UI; but keep mypy rules for any Python scripts in tooling (if any)
• Telemetry: OpenTelemetry web SDK (trace + user actions), Sentry (optional), Web Vitals
• i18n: next-intl (scaffold en-GB; key-based)
• Build: Dockerfile (node:20-alpine → distroless), environment via NEXT_PUBLIC_*
• Auth: none in-app. Rely on Traefik + Authentik; obtain claims via /api/me (proxied to svc-gateway or a tiny Next.js route that just echoes forwarded headers from Traefik).

TRUST & SECURITY MODEL

• All requests go through Traefik; the UI does not accept user-supplied auth headers.
• Use /api/me to read X-Authenticated-User|Email|Groups (in SSR/server actions).
• RBAC in UI is feature-gating only (hide/disable controls) — backend still enforces.
• Never render PII from vector search. RAG view must display pii_free:true payloads only.

TARGET SERVICES (HTTP JSON)

• svc-coverage: /v1/coverage/check, /v1/coverage/clarify, /admin/coverage/reload, /v1/coverage/policy
• svc-ingestion: /v1/ingest/upload, /v1/ingest/url, /v1/docs/{doc_id}
• svc-ocr: /v1/ocr/{doc_id}
• svc-extract: /v1/extract/{doc_id}
• svc-normalize-map: /v1/map/{doc_id}, /v1/map/{doc_id}/preview
• svc-kg: /v1/kg/lineage/{node_id}, /v1/kg/cypher (admin), /v1/kg/export/rdf
• svc-rag-retriever: /v1/rag/search
• svc-reason: /v1/reason/compute_schedule, /v1/reason/explain/{schedule_id}
• svc-forms: /v1/forms/fill, /v1/forms/evidence_pack
• svc-hmrc: /v1/hmrc/submit, /v1/hmrc/submissions/{id}
• svc-firm-connectors: /v1/firm/sync, /v1/firm/objects

USERS & ROLES

• Preparer (default): do coverage, ingest, compute, fill forms.
• Reviewer: approve/override low-confidence items, sign off.
• Admin: can reload coverage policy, run KG Cypher tool, manage feature flags.

PRIMARY FLOWS (SCREENS)

1. Dashboard

   • Coverage progress per client & schedule (chips: ok/partial/blocking)
   • Tasks: clarifications pending, missing evidence, review requests
   • Quick actions: Run Coverage, Upload Evidence, Compute Schedules

2. Client → Evidence Inbox

   • Drag-and-drop upload (multi), URL import, RPA sync trigger button
   • List of documents with kind (P60, LettingAgentStatements...), tax year, confidence badges
   • Click opens PDF Viewer with bbox highlights (left: pages; right: extracted fields & evidence tags)

3. Coverage Check

   • CoverageMatrix per schedule: rows = evidence items, cols = status/boxes
   • Status chips: present_verified (green), present_unverified (amber), missing/conflicting (red)
   • ClarifyPanel: generates question via /v1/coverage/clarify with citations
   • Inline Upload buttons mapped to svc-ingestion with tag= set to evidence.id

4. RAG + Guidance

   • Search bar (+ filters: tax_year, schedule, topic), results with citations
   • Clicking a citation can deep-link to a PDF doc_id/page/bbox (if local doc) or open URL (if guidance)

5. Schedules & Calculations

   • Select schedule (SA102/SA103…): Compute → show FormBox table (box_id, description, value, source)
   • Per-row Explain opens Lineage Drawer: graph path (FormValue ↔ Evidence ↔ Document) via cytoscape
   • Editable cells (if user override allowed) with reason + evidence attachment; show diff

6. Forms & Evidence Pack

   • Generate PDFs (download viewer); Evidence Pack download (ZIP + manifest)
   • Checklist (“All blocking gaps resolved”, “Reviewer sign-off received”)

7. Submission

   • Pre-flight checks, HMRC mode banner (stub/sandbox/live)
   • Submit; show submission_id and status; link to timeline

8. Timeline & Audit

   • Event list (ingested, OCR, extracted, mapped, computed, submitted)
   • Filter by service; click to jump to relevant screen or doc

9. Admin

   • Coverage policy viewer, hot-reload button
   • KG Cypher tool (admin only); feature flags (read-only switch list with notes)

ROUTE MAP (Next.js App Router)

/                             -> Dashboard
/clients                      -> Client list (search)
/clients/[clientId]           -> Client overview (tabs)
/clients/[clientId]/evidence  -> Evidence Inbox + PDF viewer
/clients/[clientId]/coverage  -> Coverage Check + ClarifyPanel
/clients/[clientId]/rag       -> RAG + Guidance (citations)
/clients/[clientId]/schedules -> Schedule picker + tables
/clients/[clientId]/forms     -> PDFs + Evidence Pack
/clients/[clientId]/submit    -> HMRC submission
/audit                        -> Global timeline
/admin                        -> Admin home
/admin/policy                 -> View/reload coverage
/admin/kg                     -> Cypher tool (admin)
/me                           -> Me (claims, groups)

PROJECT LAYOUT

ui-review/
  app/
    (dashboard)/page.tsx
    clients/[clientId]/(layout).tsx
    clients/[clientId]/overview/page.tsx
    clients/[clientId]/evidence/page.tsx
    clients/[clientId]/coverage/page.tsx
    clients/[clientId]/rag/page.tsx
    clients/[clientId]/schedules/page.tsx
    clients/[clientId]/forms/page.tsx
    clients/[clientId]/submit/page.tsx
    audit/page.tsx
    admin/policy/page.tsx
    admin/kg/page.tsx
    me/route.ts
    api/me/route.ts           # echoes forwarded claims for the app
    layout.tsx                # shell, nav, toasts
    globals.css
    middleware.ts             # route guard reading forwarded headers (server-only)
  components/
    upload-dropzone.tsx
    status-chip.tsx
    coverage-matrix.tsx
    clarify-panel.tsx
    pdf-viewer.tsx            # pdfjs + bbox overlays
    evidence-card.tsx
    lineage-graph.tsx         # cytoscape graph
    schedule-table.tsx
    value-cell.tsx
    explain-drawer.tsx
    rag-search.tsx
    citations-list.tsx
    timeline.tsx
  lib/
    api.ts                    # typed fetch; baseURL; error & retry
    clients.ts                # per-service client wrappers (TanStack Query)
    auth.ts                   # /api/me parsing; role helpers
    bbox.ts                   # bbox geometry utils
    types.ts                  # shared UI types (zod)
    feature-flags.ts          # remote flags (read-only)
    formatting.ts             # money/date utils (en-GB)
  hooks/
    use-claims.ts
    use-coverage.ts
    use-rag.ts
    use-pdf.ts
  styles/
    shadcn.css
  public/
    icons/
  tests/
    e2e/
    unit/
    a11y/
  .env.example
  Dockerfile
  next.config.mjs
  tailwind.config.ts
  postcss.config.js
  package.json
  tsconfig.json
  eslint.config.mjs
  playwright.config.ts

API CLIENTS (STRICT TYPES)

• Create zod schemas for each service response and infer TypeScript types.

• Wrap fetch with:

  • base URL from NEXT_PUBLIC_API_BASE (Traefik hostname, e.g., https://api.local)
  • credentials: "include" (SSO cookie path through Traefik)
  • retries (idempotent GET), exponential backoff; error normalization {type,title,status,detail,trace_id}

• Use TanStack Query for caching, optimistic updates on overrides, and background refetch.

KEY COMPONENT DETAILS

PDF Viewer (pdf-viewer.tsx)

• Render via pdfjs-dist.
• Overlay layer draws rectangles from bbox {page, x, y, w, h}; clicking highlight scrolls to corresponding extracted field; right panel shows evidence details (doc_id, page, confidence, mapping to boxes).
• Keyboard shortcuts: J/K page nav; H toggle highlights; Z zoom.

Coverage Matrix (coverage-matrix.tsx)

• Inputs: CoverageReport.
• Rows: evidence items; columns: status chip, boxes (expand to show list), actions (Upload, Clarify).
• “Clarify” opens clarify-panel.tsx which calls /v1/coverage/clarify and produces copyable text + citations + upload actions.

Lineage Graph (lineage-graph.tsx)

• Render path: FormValue → Evidence → Document (+ any Rule/Calculation nodes).
• Click a node jumps to PDF viewer at the correct page/bbox (if Document is local).
• Cytoscape style: clean, accessible (labels, readable contrast).

Schedule Table (schedule-table.tsx)

• Columns: box_id, description, value, source, confidence, explain
• Explain button opens explain-drawer.tsx which shows lineage graph + textual explanation trace (and citations if RAG guidance was used).

ACCESSIBILITY & UX

• WCAG 2.2 AA: all interactive components keyboard accessible; focus outlines; ARIA labels
• Axe checks in unit and e2e tests; Lighthouse accessibility ≥ 95
• Colour-blind safe palette; do not encode status only by colour — use icon + label

PERFORMANCE

• Code-split per route; lazy-load heavy views (PDF, graph)
• Virtualize long tables and evidence lists
• Preload API data via RSC loaders on server when appropriate
• Web Vitals: LCP < 2.5s on local; keep JS bundle sizes modest

ENV & INTEGRATION

• .env (copied to .env.local):

  • NEXT_PUBLIC_API_BASE=https://api.local
  • NEXT_PUBLIC_APP_BASE=https://ui.local
  • NEXT_PUBLIC_FEATURE_FLAGS_URL= (optional)
  • AUTHENTIK_LOGOUT_URL= (show Sign Out link to edge logout endpoint)

• Traefik labels for the UI container:

  • Router rule Host(\ui.local`)` to UI service
  • Middleware authentik-forwardauth and rate-limit

• The UI calls backend at https://api.local/* via Traefik.

TESTING (MANDATORY)

• Unit (React Testing Library):

  • coverage-matrix status rendering and actions
  • clarify-panel formatting with alternatives and citations
  • pdf-viewer highlight click → scroll and selection state
  • lineage-graph node click → callback invoked

• E2E (Playwright):

  • Login is handled by Traefik SSO; for local, place the UI behind the gateway.
  • Scenario: Upload docs → Run coverage → See blocking gaps → Generate clarify text → Upload alt evidence → Re-run coverage → OK → Compute schedule → Explain lineage → Generate forms → (stub) submit

• A11y: axe-core checks on major pages; fix violations.

QUALITY GATES (CI)

• ESLint (eslint.config.mjs with @typescript-eslint + jsx-a11y)

• TypeScript strict: true (no implicit any/any)

• Prettier format check

• Playwright E2E (headless)

• Lighthouse CI (Dashboard, Coverage, Schedules) with budgets:

  • Performance ≥ 80 (local), Accessibility ≥ 95, Best Practices ≥ 90

DELIVERABLES (RETURN ALL AS CODE BLOCKS)

1. README.md (local run with Traefik SSO; env vars; routes; role matrix)
2. package.json (scripts: dev, build, start, lint, typecheck, test, e2e, a11y, lighthouse)
3. tsconfig.json (strict true; noUncheckedIndexedAccess true)
4. eslint.config.mjs + .prettier*
5. next.config.mjs (headers passthrough; image domains)
6. tailwind.config.ts + postcss.config.js
7. app/layout.tsx, app/(dashboard)/page.tsx, route pages listed above
8. app/api/me/route.ts (server only: echo forwarded claims)
9. middleware.ts (SSR gate: if no forwarded claims, show “Not Authenticated”)
10. components/* (all listed)
11. lib/* (typed API, bbox utils, auth helpers, formatting)
12. hooks/* (coverage, rag, pdf, claims)
13. tests/unit/*, tests/e2e/*, tests/a11y/*
14. Dockerfile, .env.example, playwright.config.ts

ACCEPTANCE CRITERIA (DoD)

• Runs behind Traefik + Authentik; no in-app auth.
• Coverage Check renders matrix, generates clarifying questions with citations, and triggers uploads.
• PDF Viewer highlights bboxes and navigates correctly; lineage jumps to precise evidence.
• Schedules compute and render with Explain showing graph & textual explanation with citations.
• RAG results include citations and never display PII.
• All pages pass Axe checks; Lighthouse thresholds met.
• CI green (lint, typecheck, unit, e2e, a11y, lighthouse).

START

Generate the full ui-review application with the files and behavior above. Include typed API clients, strict TypeScript, accessible components, test suites, and Dockerfile.