# const-ahmed/vat-liability-checker architecture

> Architecture diagram of the GitHub repository const-ahmed/vat-liability-checker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/const-ahmed/vat-liability-checker
- Repository: https://github.com/const-ahmed/vat-liability-checker

## Overview

FindVAT is a UK VAT liability research app. A user submits a supply, the app streams a multi-stage evidence pipeline, and the user receives a VAT conclusion with HMRC paragraph citations or a clarifying question before another round. The graph preserves the documented classification, notice selection, retrieval, analysis and answer stages. The README documents the pipeline; sampled source confirms the client’s stream request, routing references and GOV.UK helper relationships, but not every internal model call or prompt detail.

Main entry points: [`app/api/flow/route.ts`](https://github.com/const-ahmed/vat-liability-checker/blob/main/app/api/flow/route.ts) (Flow endpoint), [`app/page.tsx`](https://github.com/const-ahmed/vat-liability-checker/blob/main/app/page.tsx) (Flow controller), [`lib/govuk/resolve.ts`](https://github.com/const-ahmed/vat-liability-checker/blob/main/lib/govuk/resolve.ts) (Notice retrieval), [`components/vat/LoadingScreen.tsx`](https://github.com/const-ahmed/vat-liability-checker/blob/main/components/vat/LoadingScreen.tsx) (Progress stream UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_app["Flow controller<br/>[page.tsx]"]
  node_screens["VAT screens"]
  node_loading["Progress stream UI<br/>[LoadingScreen.tsx]"]
  node_answer["Answer and citations<br/>[AnswerScreen.tsx]"]
end

subgraph group_pipeline["VAT analysis pipeline"]
  node_flowapi["Flow endpoint<br/>[route.ts]"]
  node_classify["Supply classification<br/>[route.ts]"]
  node_select["Notice selection<br/>[route.ts]"]
  node_analyse["Evidence analysis<br/>[route.ts]"]
  node_clarify["Clarifier generation<br/>[route.ts]"]
  node_schemas["Flow data schemas<br/>[flow.ts]"]
end

subgraph group_sources["Evidence sources"]
  node_resolve["Notice retrieval<br/>[resolve.ts]"]
  node_noticeindex["Notice index<br/>[vatNoticesIndex.ts]"]
  node_contentapi["GOV.UK client<br/>[contentApi.ts]"]
end

subgraph group_identity["Identity and history"]
  node_authui["Sign-in interface<br/>[sign-in-modal.tsx]"]
  node_authclient["Auth client<br/>[auth-client.ts]"]
  node_authapi["Auth endpoint<br/>[route.ts]"]
  node_auth["Auth service<br/>[auth.ts]"]
  node_database[("PostgreSQL")]
  node_historyui["History drawer<br/>[history-drawer.tsx]"]
  node_historyapi["History endpoint<br/>[route.ts]"]
end

node_user(("User"))
node_govuk(("GOV.UK Content API"))
node_model(("GPT-4o-mini"))

node_user -->|"submits supply"| node_app
node_app -->|"renders"| node_screens
node_app -->|"renders"| node_loading
node_loading -->|"streams request"| node_flowapi
node_flowapi -->|"classifies supply"| node_classify
node_flowapi -->|"selects notices"| node_select
node_flowapi -->|"resolves notices"| node_resolve
node_resolve -->|"uses index"| node_noticeindex
node_resolve -->|"fetches content"| node_contentapi
node_noticeindex -->|"loads index data"| node_contentapi
node_contentapi -->|"requests content"| node_govuk
node_flowapi -->|"analyses evidence"| node_analyse
node_flowapi -->|"prompts model"| node_model
node_flowapi -->|"may generate question"| node_clarify
node_flowapi -->|"uses contracts"| node_schemas
node_flowapi -->|"streams stages"| node_loading
node_app -->|"renders conclusion"| node_answer
node_app -->|"opens sign-in"| node_authui
node_authui -->|"authenticates"| node_authclient
node_authclient -.->|"uses auth service"| node_authapi
node_authapi -->|"dispatches to"| node_auth
node_auth -->|"stores identity"| node_database
node_app -->|"renders"| node_historyui
node_historyui -->|"loads entries"| node_historyapi
node_historyapi -->|"checks session"| node_auth

click node_app "https://github.com/const-ahmed/vat-liability-checker/blob/main/app/page.tsx"
click node_screens "https://github.com/const-ahmed/vat-liability-checker/tree/main/components/vat"
click node_loading "https://github.com/const-ahmed/vat-liability-checker/blob/main/components/vat/LoadingScreen.tsx"
click node_answer "https://github.com/const-ahmed/vat-liability-checker/blob/main/components/vat/AnswerScreen.tsx"
click node_flowapi "https://github.com/const-ahmed/vat-liability-checker/blob/main/app/api/flow/route.ts"
click node_classify "https://github.com/const-ahmed/vat-liability-checker/blob/main/app/api/flow/route.ts"
click node_select "https://github.com/const-ahmed/vat-liability-checker/blob/main/app/api/flow/route.ts"
click node_analyse "https://github.com/const-ahmed/vat-liability-checker/blob/main/app/api/flow/route.ts"
click node_clarify "https://github.com/const-ahmed/vat-liability-checker/blob/main/app/api/flow/route.ts"
click node_resolve "https://github.com/const-ahmed/vat-liability-checker/blob/main/lib/govuk/resolve.ts"
click node_noticeindex "https://github.com/const-ahmed/vat-liability-checker/blob/main/lib/govuk/vatNoticesIndex.ts"
click node_contentapi "https://github.com/const-ahmed/vat-liability-checker/blob/main/lib/govuk/contentApi.ts"
click node_schemas "https://github.com/const-ahmed/vat-liability-checker/blob/main/lib/schemas/flow.ts"
click node_authui "https://github.com/const-ahmed/vat-liability-checker/blob/main/components/ui/sign-in-modal.tsx"
click node_authclient "https://github.com/const-ahmed/vat-liability-checker/blob/main/lib/auth-client.ts"
click node_authapi "https://github.com/const-ahmed/vat-liability-checker/blob/main/app/api/auth/%5B...all%5D/route.ts"
click node_auth "https://github.com/const-ahmed/vat-liability-checker/blob/main/lib/auth.ts"
click node_historyui "https://github.com/const-ahmed/vat-liability-checker/blob/main/components/ui/history-drawer.tsx"
click node_historyapi "https://github.com/const-ahmed/vat-liability-checker/blob/main/app/api/history/route.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_screens,node_loading,node_answer,node_user toneBlue
class node_flowapi,node_classify,node_select,node_analyse,node_clarify,node_schemas toneAmber
class node_resolve,node_noticeindex,node_contentapi,node_govuk toneMint
class node_authui,node_authclient,node_authapi,node_auth,node_database,node_historyui,node_historyapi toneRose
class node_model toneIndigo
```

## Components

### User experience

- [Flow controller](https://github.com/const-ahmed/vat-liability-checker/blob/main/app/page.tsx): `app/page.tsx`
- [VAT screens](https://github.com/const-ahmed/vat-liability-checker/tree/main/components/vat): `components/vat`
- [Progress stream UI](https://github.com/const-ahmed/vat-liability-checker/blob/main/components/vat/LoadingScreen.tsx): `components/vat/LoadingScreen.tsx`
- [Answer and citations](https://github.com/const-ahmed/vat-liability-checker/blob/main/components/vat/AnswerScreen.tsx): `components/vat/AnswerScreen.tsx`

### VAT analysis pipeline

- [Flow endpoint](https://github.com/const-ahmed/vat-liability-checker/blob/main/app/api/flow/route.ts): `app/api/flow/route.ts`
- [Supply classification](https://github.com/const-ahmed/vat-liability-checker/blob/main/app/api/flow/route.ts): `app/api/flow/route.ts`
- [Notice selection](https://github.com/const-ahmed/vat-liability-checker/blob/main/app/api/flow/route.ts): `app/api/flow/route.ts`
- [Evidence analysis](https://github.com/const-ahmed/vat-liability-checker/blob/main/app/api/flow/route.ts): `app/api/flow/route.ts`
- [Clarifier generation](https://github.com/const-ahmed/vat-liability-checker/blob/main/app/api/flow/route.ts): `app/api/flow/route.ts`
- [Flow data schemas](https://github.com/const-ahmed/vat-liability-checker/blob/main/lib/schemas/flow.ts): `lib/schemas/flow.ts`

### Evidence sources

- [Notice retrieval](https://github.com/const-ahmed/vat-liability-checker/blob/main/lib/govuk/resolve.ts): `lib/govuk/resolve.ts`
- [Notice index](https://github.com/const-ahmed/vat-liability-checker/blob/main/lib/govuk/vatNoticesIndex.ts): `lib/govuk/vatNoticesIndex.ts`
- [GOV.UK client](https://github.com/const-ahmed/vat-liability-checker/blob/main/lib/govuk/contentApi.ts): `lib/govuk/contentApi.ts`

### Identity and history

- [Sign-in interface](https://github.com/const-ahmed/vat-liability-checker/blob/main/components/ui/sign-in-modal.tsx): `components/ui/sign-in-modal.tsx`
- [Auth client](https://github.com/const-ahmed/vat-liability-checker/blob/main/lib/auth-client.ts): `lib/auth-client.ts`
- [Auth endpoint](https://github.com/const-ahmed/vat-liability-checker/blob/main/app/api/auth/%5B...all%5D/route.ts): `app/api/auth/[...all]/route.ts`
- [Auth service](https://github.com/const-ahmed/vat-liability-checker/blob/main/lib/auth.ts): `lib/auth.ts`
- **PostgreSQL**
- [History drawer](https://github.com/const-ahmed/vat-liability-checker/blob/main/components/ui/history-drawer.tsx): `components/ui/history-drawer.tsx`
- [History endpoint](https://github.com/const-ahmed/vat-liability-checker/blob/main/app/api/history/route.ts): `app/api/history/route.ts`

### Other components

- **User**
- **GOV.UK Content API**
- **GPT-4o-mini**

## Connections

- User → Flow controller: submits supply
- Flow controller → VAT screens: renders (evidence: `app/page.tsx`)
- Flow controller → Progress stream UI: renders (evidence: `app/page.tsx`)
- Progress stream UI → Flow endpoint: streams request (evidence: `components/vat/LoadingScreen.tsx`)
- Flow endpoint → Supply classification: classifies supply (evidence: `app/api/flow/route.ts`)
- Flow endpoint → Notice selection: selects notices (evidence: `app/api/flow/route.ts`)
- Flow endpoint → Notice retrieval: resolves notices (evidence: `app/api/flow/route.ts`)
- Notice retrieval → Notice index: uses index (evidence: `lib/govuk/resolve.ts`)
- Notice retrieval → GOV.UK client: fetches content (evidence: `lib/govuk/resolve.ts`)
- Notice index → GOV.UK client: loads index data (evidence: `lib/govuk/vatNoticesIndex.ts`)
- GOV.UK client → GOV.UK Content API: requests content
- Flow endpoint → Evidence analysis: analyses evidence (evidence: `app/api/flow/route.ts`)
- Flow endpoint → GPT-4o-mini: prompts model
- Flow endpoint → Clarifier generation: may generate question (evidence: `app/api/flow/route.ts`)
- Flow endpoint → Flow data schemas: uses contracts (evidence: `app/api/flow/route.ts`)
- Flow endpoint → Progress stream UI: streams stages
- Flow controller → Answer and citations: renders conclusion (evidence: `app/page.tsx`)
- Flow controller → Sign-in interface: opens sign-in (evidence: `app/page.tsx`)
- Sign-in interface → Auth client: authenticates (evidence: `components/ui/sign-in-modal.tsx`)
- Auth client → Auth endpoint: uses auth service
- Auth endpoint → Auth service: dispatches to (evidence: `app/api/auth/[...all]/route.ts`)
- Auth service → PostgreSQL: stores identity (evidence: `lib/auth.ts`)
- Flow controller → History drawer: renders (evidence: `app/page.tsx`)
- History drawer → History endpoint: loads entries (evidence: `components/ui/history-drawer.tsx`)
- History endpoint → Auth service: checks session (evidence: `app/api/history/route.ts`)