af-frontend — Prop-Build Analysis

Document Type: Critical Review & Analysis (companion to prop-build-template.md) Scope: Per-Repo Subject: af-frontend (aid-finder/af-frontend) Reviewer(s): Claude (automated code review) Date: 2026-04-09 Version: 0.1 Confidence Level: Medium What would raise confidence: running pnpm build + bundle analyzer locally, access to Vercel/CloudFront RUM, an interview with the frontend lead, and sight of the external CI/deploy pipeline config.

Inputs Reviewed:

• Prop-build doc: data/af-frontend.yaml
• Companion docs: data/af-frontend/{component-tree,data-flow,api-examples,runbook,deployment}.md
• Code commit SHA: 8b7acf98842a737bcf7d1c9dada0659e87cb2938 (develop)
• Dashboards / metrics: none available (no RUM/APM configured)
• ADRs / design docs: none found in repo
• Interviews: none

A.1 Executive Summary

• Overall health: Modern, well-structured Next.js 16 / React 19 SPA with a genuinely elegant server-driven dynamic-form core, but undermined by a total absence of automated tests, no error tracking, and a weak admin auth story.
• Top risk: Admin panel "auth" is a single shared passphrase read from localStorage and forwarded as an x-admin-passphrase header (src/features/admin/api/client/apollo.ts:9-18, src/features/admin/components/layout/login/index.tsx:34). Anyone who can inspect a browser gets every admin mutation — see A.4.1.
• Top win / thing worth preserving: The server-driven dynamic form (src/lib/components/dynamic-form/parts/render-field.tsx + application-form/index.tsx) lets the backend introduce new fields/sections/conditions without a frontend deploy. This pattern should be preserved and propagated.
• Single recommended next action: Replace admin passphrase auth with Firebase Auth + a backend isAdmin claim, and in parallel adopt Vitest + Playwright for the submit→finalize→processing happy path.
• Blocking unknowns: No CI/deploy pipeline exists in-repo (.github/workflows returns 404 per the YAML §16), no bundle size or Lighthouse numbers, no production error rates — impossible to score A.12/A.14 confidently.

A.2 Health Scorecard

Overall score: 3.0 — strong on architecture/docs (1, 7, 8, 13, 18), dangerously weak on testing, observability, and admin security (9, 12, 15, 16, 17).

A.3 What's Working Well

• Strength: Server-driven dynamic form renderer — entire form schema lives on the backend and a generic client renders it.

  • Location: src/lib/components/dynamic-form/parts/render-field.tsx:102-248; orchestrated by src/features/application/components/application-form/index.tsx:68-206.
  • Why it works: New field types, conditions, and repeated groups ship without a frontend deploy. Unknown components fall back sanely (render-field.tsx:241-247).
  • Propagate to: Admin CRUD forms in src/features/admin/... that currently reinvent their own.

• Strength: Centralized Apollo auth-link with single-flight token refresh.

  • Location: src/lib/api/graphql/links/auth-link.ts:28-116.
  • Why it works: isRefreshing flag + pendingRequests queue avoids thundering-herd token refreshes. Triggered off both ERR_UNAUTHORIZED in result extensions (:149-152) and 401/UNAUTHENTICATED network errors (:163-171).
  • Propagate to: Admin Apollo client (src/features/admin/api/client/apollo.ts) which does NOT get this benefit.

• Strength: Apollo cache type policy for union + custom keyFields.

  • Location: src/lib/api/graphql/apollo.ts:8-17 (FormField possibleTypes, Household.bqHouseholdId keyFields).
  • Why it works: Correct handling of GraphQL unions and non-id entities is a frequent bug source; solved deliberately here.

• Strength: Polling pauses when the VNC iframe is visible.

  • Location: src/features/application/components/form-submission-portal/index.tsx:34,40,66.
  • Why it works: Avoids fighting the user's login.gov session and saves backend QPS.

A.4 What to Improve

A.4.1 P0 — Admin panel protected only by shared localStorage passphrase

• Problem: Admin authentication is a single shared secret stored in localStorage and sent as x-admin-passphrase on every admin GraphQL request. No per-user identity, no rotation, no audit, no expiry, and localStorage is XSS-readable.
• Evidence: src/features/admin/api/client/apollo.ts:9-18; src/features/admin/components/layout/login/index.tsx:32-37. YAML §17 acknowledges but scores "low-sensitivity".
• Suggested change: Firebase Auth with an admin custom claim verified server-side; drop the passphrase. Stop-gap: move to HttpOnly cookie set by a backend login endpoint.
• Estimated effort: M.
• Risk if ignored: One XSS or screenshot → full disaster/program CRUD compromise once mutations are wired.

A.4.2 P0 — No automated tests of any kind

• Problem: package.json has no Vitest/Jest/Playwright. The submit → presigned S3 PUT → finalize → polling pipeline is the money path and entirely unverified.
• Evidence: src/features/application/components/application-form/index.tsx:96-193; src/lib/components/dynamic-form/parts/render-field.tsx:102-247.
• Suggested change: Vitest for helpers/ + dynamic-form unit tests; Playwright for one happy-path e2e against a mocked backend.
• Estimated effort: M.
• Risk if ignored: Any refactor can silently break submissions; regressions only caught by survivors failing to file.

A.4.3 P1 — No client-side error tracking or RUM

• Problem: No Sentry / Datadog RUM / Vercel Analytics SDK. If render-field.tsx:241 renders null in prod for an unknown field component, nobody hears it.
• Evidence: YAML §14 monitoring_alerts.applicable: false; no @sentry/* in package.json.
• Suggested change: Add Sentry (browser + source maps) and wire global-error.tsx + per-route error.tsx boundaries.
• Estimated effort: S.
• Risk if ignored: Production regressions only surface through support tickets.

A.4.4 P1 — Auth-link has no retry budget or backoff

• Problem: On repeated ERR_UNAUTHORIZED, handleTokenRefresh refreshes and re-forwards. No per-operation attempt counter.
• Evidence: src/lib/api/graphql/links/auth-link.ts:147-158.
• Suggested change: Per-operation retry counter capped at 1; on second failure, logout and surface an error.
• Estimated effort: S.
• Risk if ignored: Low-rate but real risk of retry-storm against Firebase + backend.

A.4.5 P2 — Legacy manual memoization left behind after enabling React Compiler

• Evidence: src/lib/components/dynamic-form/parts/render-field.tsx:52-74; YAML cites src/features/dashboard/pages/dashboard/parts/circular-progress/index.tsx and src/features/map/....
• Suggested change: Sweep and remove; add eslint-plugin-react-compiler rule.
• Estimated effort: S.

A.4.6 P2 — Polling should become a GraphQL subscription

• Evidence: src/features/application/components/form-submission-portal/index.tsx:26,40.
• Suggested change: Add a subscription on FormSubmission.aiAgentLatestState in af-backend-go-api and use useSubscription.
• Estimated effort: M (cross-repo).
• Risk if ignored: Continued poor UX during the AI processing stage; unnecessary backend QPS.

A.5 Things That Don't Make Sense

1. Observation: The admin Apollo client gets its own copy-pasted auth-link with no token-refresh logic, while the main client has a sophisticated single-flight refresh link.

   • Location: src/features/admin/api/client/apollo.ts:9-29 vs src/lib/api/graphql/links/auth-link.ts.
   • Question for author: Is the passphrase intended to go away soon, or should the admin client inherit the main auth-link machinery now?

2. Observation: resolveFormPath and resolveFileValue reconstruct RHF field paths by hand inline.

   • Location: src/features/application/components/application-form/index.tsx:26-57.
   • Question for author: Should these move into helpers/ so tests (when they exist) can target them directly?

3. Observation: cache.evict({ fieldName: 'formPrefill' }) is called unconditionally on all success branches after submit.

   • Location: application-form/index.tsx:165.
   • Question for author: Intentional? "May not be eligible" branch also evicts.

A.6 Anti-Patterns Detected

A.6.1 Code-level

• God object / god function
• Shotgun surgery
• Feature envy
• Primitive obsession (passphrase as raw string, field paths as dot-strings)
• Dead code
• Copy-paste / duplication (admin Apollo client re-implements a stripped-down auth-link)
• Magic numbers / unexplained constants (raw 'passphrase' localStorage key is not named)
• Deep nesting
• Long parameter lists
• Boolean-flag parameters

A.6.2 Architectural

• Big ball of mud
• Distributed monolith
• Chatty services
• Leaky abstraction (render-field.tsx uses 'options' in field / 'placeholder' in field runtime checks instead of an exhaustive discriminated union)
• Golden hammer
• Vendor lock-in
• Stovepipe
• Missing seams for testing (hardcoded fetch to presigned S3 URLs; no injectable HTTP client)

A.6.3 Data

• None observed in this client repo.

A.6.4 Async / Ops

• Poison messages
• Retry storms / no backoff (auth-link has no per-op cap)
• Missing idempotency keys
• Hidden coupling via shared state
• Work queues without visibility (polling has no metric)

A.6.5 Security

• Secrets in code / localStorage (passphrase in localStorage)
• Missing authn/z on internal endpoints (admin "auth" is a shared string)
• Overbroad IAM roles
• Unvalidated input crossing trust boundary
• PII/PHI in logs or error messages
• Missing CSRF / XSS / SQLi / SSRF — unable to confirm CSP headers without deploy config; flagged in A.9.2

A.6.6 Detected Instances

A.7 Open Questions

1. Q: Is the admin passphrase scheme a deliberate interim pending Firebase-admin-claim migration, or the intended end state?
2. Q: Where does CI actually live? .github/workflows is empty.
3. Q: What are the measured LCP/TTI/bundle size for /explore?
4. Q: Is a subscription on FormSubmission feasible in af-backend-go-api?

A.8 Difficulties Encountered

• Difficulty: No CI/deploy config in repo.
  • Impact: Cannot verify build steps, deploy gates, rollback timing, or whether lint/typecheck block merge.
  • Fix: Commit .github/workflows/ci.yml or link from README.
• Difficulty: No tests to read as executable spec.
  • Impact: Intent inferred from happy-path code alone.
• Difficulty: No runtime telemetry.
  • Impact: A.12, A.13, A.14 are qualitative only.
• Difficulty: Did not run pnpm codegen or pnpm build.

A.9 Risks & Unknowns

A.9.1 Known risks

A.9.2 Unknown unknowns

• Storybook visual regression coverage — not reviewed; risk Low.
• Mapbox feature (src/features/map/) — not reviewed in depth; risk Medium (landing surface).
• CSP / security headers (Next middleware, next.config.ts) — not opened; risk Medium.
• helpers/ internals (applyPrefill, processPayload, mapErrorCodesToMessage) — not reviewed; risk Medium.
• Accessibility of the dynamic form — no tooling signal; risk Medium.

A.10 Technical Debt Register

A.11 Security Posture (lightweight STRIDE)

A.12 Operational Readiness

A.13 Test & Quality Signals

• Coverage: 0 / 0 — no framework.
• Untested critical paths: submit → presigned S3 upload → finalize → processing polling; dynamic form rendering; auth-link token refresh; applyPrefill/processPayload.
• Missing test types: [x] unit [x] integration [x] e2e [x] contract [x] load [x] security/fuzz

A.14 Performance & Cost Smells

• Hot paths: /explore (Mapbox GL initial load), /application/.../form (RHF + large schema), /processing (5 s poll).
• Suspected bottlenecks: Mapbox GL + Apollo + styled-components bundle; RHF rerenders on repeated groups; polling.
• Wasteful queries: FormSubmission polled every 5 s unconditionally.
• Cache surprises: cache.evict({fieldName:'formPrefill'}) on every submit branch forces refetch.

A.15 Bus-Factor & Knowledge Risk

• Only-person: Cannot determine from code alone; YAML lists 4 authors. Dynamic-form architecture likely 1–2 of them.
• What breaks: Evolving the RenderField switch safely; understanding applyPrefill/buildFieldGroupInfo contract; unwritten React Compiler memo-sweep rule.
• Tribal knowledge: CI/deploy pipeline (literally not in repo); admin passphrase rotation procedure.
• Actions: Write docs/dynamic-form.md extension guide; commit CI config; ADR for admin auth interim decision.

A.16 Compliance Gaps

A.17 Recommendations Summary