Architecture, scope, and honesty notes

Stack

TanStack Start (React 19, Vite) with TypeScript, Tailwind CSS v4 design tokens, and shadcn primitives on the front end. The backend is Lovable Cloud: PostgreSQL with row-level security, hosted auth, private object storage, and server functions for anything that touches a credential.

Multi-tenancy and security

• Every business table carries organization_id and is protected by RLS.
• Membership and role live in organization_memberships — never on the user profile — and are read through security-definer helpers so policies cannot recurse.
• Seven roles: platform super admin, agency admin, executive approver, project manager, contributor, analyst/reviewer, and board viewer (read-only).
• Uploads land in a private bucket where storage policies require the object path to begin with the caller's organization UUID.
• Sensitive actions write to audit_logs with actor, entity, and metadata.

Module workflow

Every module runs the same ten stages — scope, source selection, upload/import, validation, analysis, drafting, citation review, quality/compliance review, approval, export — recorded per project in module_runs, with sections, tasks, approvals, and report versions hanging off the project.

Citation ledger

Citations reference a source snapshot with vintage, retrieval date, and locator (page, sheet cell, or dataset row). Drafts carry bracketed markers that resolve against the ledger, and unverified citations are surfaced on the project workspace before export.

AI adapters

Generation runs through one server function with provider adapters for Lovable AI, OpenAI, Anthropic, and Google Gemini, plus ordered fallback. Credentials are read inside the server handler from environment variables. With no key configured, generation returns an explicit “provider unavailable” result rather than fabricating text. Every attempt is logged in ai_runs.

Exports

Word export builds a branded document with cover, contents, sections, and a citation table. Excel export produces the multi-tab wage workbook, and CSV export covers extracted tables. PDF currently uses the browser print pipeline; a long, paginated production PDF should move to a server-side renderer.

What is demo versus production

• Production-oriented: auth, tenant isolation, roles, onboarding, projects and stages, sections, citations, uploads to private storage, tasks, approvals, audit logging, and the export pipeline.
• Scaffolded: live data-source connectors (Census, BLS, HUD and others) and AI providers — wired end to end but inert until credentials are supplied.
• Demonstration content: the seeded seven-county agency, its programs, surveys, focus groups, wage roster, benchmarks, scenarios, and narrative drafts. All of it is synthetic and labelled in the UI. No real agency, client, or employee data is present.

Accessibility

Semantic landmarks, a skip link, labelled form controls, visible focus rings, keyboard- reachable stage controls, live regions on loading states, and reduced-motion support are built in. This is a good-faith WCAG 2.1 AA effort, not a certified audit.