# kyotofin/tax-doc-classifier architecture

> Architecture diagram of the GitHub repository kyotofin/tax-doc-classifier, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kyotofin/tax-doc-classifier
- Repository: https://github.com/kyotofin/tax-doc-classifier

## Overview

tax-doc-classifier is a TypeScript library that classifies tax-document pages into IRS forms and page kinds, returning probabilities and confidence gating. Its main workflow extracts one PDF page to text, sends text-derived state and form/kind criteria to Jev, optionally asks a second question for selected form families, then returns the result. It also exposes form-ID utilities and strict evaluation scoring. The criteria JSON is generated from IRS materials; the generator and evaluation runners are omitted as tooling. Runtime links are grounded in README usage or the cited source; unsampled integrations are not inferred.

Main entry points: [`src/classify.ts`](https://github.com/kyotofin/tax-doc-classifier/blob/main/src/classify.ts) (Page classifier), [`src/state.ts`](https://github.com/kyotofin/tax-doc-classifier/blob/main/src/state.ts) (PDF page text), [`src/backend.ts`](https://github.com/kyotofin/tax-doc-classifier/blob/main/src/backend.ts) (Jev backend), [`data/criteria.json`](https://github.com/kyotofin/tax-doc-classifier/blob/main/data/criteria.json) (Form criteria)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Page input"]
  node_pdf_text["PDF page text<br/>[state.ts]"]
  node_page_state["Page state<br/>[state.ts]"]
end

subgraph group_runtime["Classification runtime"]
  node_classifier["Page classifier<br/>[classify.ts]"]
  node_jev_backend["Jev backend<br/>[backend.ts]"]
  node_jev_service["TypeSafe Jev"]
end

subgraph group_taxonomy["Forms and criteria"]
  node_criteria["Form criteria<br/>[criteria.json]"]
  node_form_ids["Form ID utilities<br/>[ids.ts]"]
end

subgraph group_results["Results and utilities"]
  node_confidence_result["Classification result<br/>[classify.ts]"]
  node_scoring["Strict scoring<br/>[score.ts]"]
end

node_caller(("Library caller"))

node_caller -->|"extracts page"| node_pdf_text
node_pdf_text -->|"builds state"| node_page_state
node_caller -->|"classifies text"| node_classifier
node_caller -->|"supplies criteria"| node_criteria
node_classifier -->|"builds state"| node_page_state
node_classifier -->|"selects options"| node_criteria
node_classifier -->|"asks questions"| node_jev_backend
node_jev_backend -->|"posts request"| node_jev_service
node_classifier -->|"returns result"| node_confidence_result
node_confidence_result -->|"returns result"| node_caller
node_caller -->|"uses ID utilities"| node_form_ids
node_caller -->|"scores result"| node_scoring

click node_pdf_text "https://github.com/kyotofin/tax-doc-classifier/blob/main/src/state.ts"
click node_page_state "https://github.com/kyotofin/tax-doc-classifier/blob/main/src/state.ts"
click node_classifier "https://github.com/kyotofin/tax-doc-classifier/blob/main/src/classify.ts"
click node_jev_backend "https://github.com/kyotofin/tax-doc-classifier/blob/main/src/backend.ts"
click node_criteria "https://github.com/kyotofin/tax-doc-classifier/blob/main/data/criteria.json"
click node_form_ids "https://github.com/kyotofin/tax-doc-classifier/blob/main/src/ids.ts"
click node_confidence_result "https://github.com/kyotofin/tax-doc-classifier/blob/main/src/classify.ts"
click node_scoring "https://github.com/kyotofin/tax-doc-classifier/blob/main/src/score.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_pdf_text,node_page_state toneBlue
class node_classifier,node_jev_backend,node_jev_service toneAmber
class node_criteria,node_form_ids toneMint
class node_confidence_result,node_scoring toneRose
class node_caller toneIndigo
```

## Components

### Page input

- [PDF page text](https://github.com/kyotofin/tax-doc-classifier/blob/main/src/state.ts): `src/state.ts`
- [Page state](https://github.com/kyotofin/tax-doc-classifier/blob/main/src/state.ts): `src/state.ts`

### Classification runtime

- [Page classifier](https://github.com/kyotofin/tax-doc-classifier/blob/main/src/classify.ts): `src/classify.ts`
- [Jev backend](https://github.com/kyotofin/tax-doc-classifier/blob/main/src/backend.ts): `src/backend.ts`
- **TypeSafe Jev**

### Forms and criteria

- [Form criteria](https://github.com/kyotofin/tax-doc-classifier/blob/main/data/criteria.json): `data/criteria.json`
- [Form ID utilities](https://github.com/kyotofin/tax-doc-classifier/blob/main/src/ids.ts): `src/ids.ts`

### Results and utilities

- [Classification result](https://github.com/kyotofin/tax-doc-classifier/blob/main/src/classify.ts): `src/classify.ts`
- [Strict scoring](https://github.com/kyotofin/tax-doc-classifier/blob/main/src/score.ts): `src/score.ts`

### Other components

- **Library caller**

## Connections

- Library caller → PDF page text: extracts page (evidence: `README.md`)
- PDF page text → Page state: builds state (evidence: `src/state.ts`)
- Library caller → Page classifier: classifies text (evidence: `README.md`)
- Library caller → Form criteria: supplies criteria (evidence: `README.md`)
- Page classifier → Page state: builds state (evidence: `src/classify.ts`)
- Page classifier → Form criteria: selects options (evidence: `src/classify.ts`)
- Page classifier → Jev backend: asks questions (evidence: `src/classify.ts`)
- Jev backend → TypeSafe Jev: posts request (evidence: `src/backend.ts`)
- Page classifier → Classification result: returns result (evidence: `src/classify.ts`)
- Classification result → Library caller: returns result (evidence: `README.md`)
- Library caller → Form ID utilities: uses ID utilities (evidence: `README.md`)
- Library caller → Strict scoring: scores result (evidence: `README.md`)
