# kotianprakash/term-sheet-reconciliation architecture

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

- Interactive diagram: https://gitdiagram.com/kotianprakash/term-sheet-reconciliation
- Repository: https://github.com/kotianprakash/term-sheet-reconciliation

## Overview

Term Sheet Reconciliation turns a term-sheet PDF and a booking-system JSON/CSV file into a traceable, field-by-field CSV reconciliation. The CLI delegates to report generation, which loads booking trades and extracts the shared PDF once. Extraction preserves page evidence and validates Claude’s structured response; comparison applies deterministic normalization before escalating unresolved fields to Claude for arbitration. Results include Match, False Alert, True Mismatch, or Parsing Error. The README documents both input formats and the report’s traceability fields. Source excerpts show the main call ownership; data-file relationships are documented in the README.

Main entry points: [`src/report.py`](https://github.com/kotianprakash/term-sheet-reconciliation/blob/main/src/report.py) (Report runner), [`src/extract.py`](https://github.com/kotianprakash/term-sheet-reconciliation/blob/main/src/extract.py) (Field extractor), [`src/compare.py`](https://github.com/kotianprakash/term-sheet-reconciliation/blob/main/src/compare.py) (Trade comparison), [`src/ingest.py`](https://github.com/kotianprakash/term-sheet-reconciliation/blob/main/src/ingest.py) (PDF page reader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Inputs"]
  node_term_pdf["Term sheet PDF"]
  node_booking_file["Booking file"]
  node_booking_loader["Booking loader<br/>[report.py]"]
end

subgraph group_extraction["Term extraction"]
  node_pdf_reader["PDF page reader<br/>[ingest.py]"]
  node_page_markers["Page markers<br/>[ingest.py]"]
  node_field_extractor["Field extractor<br/>[extract.py]"]
  node_extraction_schema["Extraction schema<br/>[schema.py]"]
  node_schema_validation["Response validation<br/>[extract.py]"]
end

subgraph group_reconciliation["Reconciliation"]
  node_trade_compare["Trade comparison<br/>[compare.py]"]
  node_normalization["Deterministic matching<br/>[normalize.py]"]
  node_mismatch_arbitration["Mismatch arbitration<br/>[compare.py]"]
end

subgraph group_reporting["Reporting"]
  node_pipeline_cli["Pipeline CLI<br/>[run_pipeline.py]"]
  node_report_runner["Report runner<br/>[report.py]"]
  node_csv_report["CSV report"]
end

node_operator(("Operator"))
node_claude{{"Claude API"}}

node_operator -->|"runs"| node_pipeline_cli
node_pipeline_cli -->|"generates report"| node_report_runner
node_term_pdf -->|"provides PDF"| node_pdf_reader
node_pdf_reader -->|"returns pages"| node_page_markers
node_page_markers -->|"supplies marked text"| node_field_extractor
node_field_extractor -->|"requests extraction"| node_claude
node_field_extractor -->|"validates response"| node_schema_validation
node_schema_validation -->|"validates against"| node_extraction_schema
node_booking_file -->|"provides JSON or CSV"| node_booking_loader
node_report_runner -->|"loads trades"| node_booking_loader
node_report_runner -->|"extracts once"| node_field_extractor
node_report_runner -->|"compares each trade"| node_trade_compare
node_trade_compare -->|"checks values"| node_normalization
node_trade_compare -->|"escalates unresolved fields"| node_mismatch_arbitration
node_mismatch_arbitration -->|"requests judgment"| node_claude
node_report_runner -->|"writes CSV"| node_csv_report

click node_pipeline_cli "https://github.com/kotianprakash/term-sheet-reconciliation/blob/main/src/run_pipeline.py"
click node_report_runner "https://github.com/kotianprakash/term-sheet-reconciliation/blob/main/src/report.py"
click node_booking_loader "https://github.com/kotianprakash/term-sheet-reconciliation/blob/main/src/report.py"
click node_pdf_reader "https://github.com/kotianprakash/term-sheet-reconciliation/blob/main/src/ingest.py"
click node_page_markers "https://github.com/kotianprakash/term-sheet-reconciliation/blob/main/src/ingest.py"
click node_field_extractor "https://github.com/kotianprakash/term-sheet-reconciliation/blob/main/src/extract.py"
click node_extraction_schema "https://github.com/kotianprakash/term-sheet-reconciliation/blob/main/src/schema.py"
click node_schema_validation "https://github.com/kotianprakash/term-sheet-reconciliation/blob/main/src/extract.py"
click node_trade_compare "https://github.com/kotianprakash/term-sheet-reconciliation/blob/main/src/compare.py"
click node_normalization "https://github.com/kotianprakash/term-sheet-reconciliation/blob/main/src/normalize.py"
click node_mismatch_arbitration "https://github.com/kotianprakash/term-sheet-reconciliation/blob/main/src/compare.py"

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_term_pdf,node_booking_file,node_booking_loader toneBlue
class node_pdf_reader,node_page_markers,node_field_extractor,node_extraction_schema,node_schema_validation toneAmber
class node_trade_compare,node_normalization,node_mismatch_arbitration,node_claude toneMint
class node_pipeline_cli,node_report_runner,node_csv_report toneRose
class node_operator toneIndigo
```

## Components

### Inputs

- **Term sheet PDF**
- **Booking file**
- [Booking loader](https://github.com/kotianprakash/term-sheet-reconciliation/blob/main/src/report.py): `src/report.py`

### Term extraction

- [PDF page reader](https://github.com/kotianprakash/term-sheet-reconciliation/blob/main/src/ingest.py): `src/ingest.py`
- [Page markers](https://github.com/kotianprakash/term-sheet-reconciliation/blob/main/src/ingest.py): `src/ingest.py`
- [Field extractor](https://github.com/kotianprakash/term-sheet-reconciliation/blob/main/src/extract.py): `src/extract.py`
- [Extraction schema](https://github.com/kotianprakash/term-sheet-reconciliation/blob/main/src/schema.py): `src/schema.py`
- [Response validation](https://github.com/kotianprakash/term-sheet-reconciliation/blob/main/src/extract.py): `src/extract.py`

### Reconciliation

- [Trade comparison](https://github.com/kotianprakash/term-sheet-reconciliation/blob/main/src/compare.py): `src/compare.py`
- [Deterministic matching](https://github.com/kotianprakash/term-sheet-reconciliation/blob/main/src/normalize.py): `src/normalize.py`
- [Mismatch arbitration](https://github.com/kotianprakash/term-sheet-reconciliation/blob/main/src/compare.py): `src/compare.py`

### Reporting

- [Pipeline CLI](https://github.com/kotianprakash/term-sheet-reconciliation/blob/main/src/run_pipeline.py): `src/run_pipeline.py`
- [Report runner](https://github.com/kotianprakash/term-sheet-reconciliation/blob/main/src/report.py): `src/report.py`
- **CSV report**

### Other components

- **Operator**
- **Claude API**

## Connections

- Operator → Pipeline CLI: runs (evidence: `README.md`)
- Pipeline CLI → Report runner: generates report (evidence: `src/run_pipeline.py`)
- Term sheet PDF → PDF page reader: provides PDF (evidence: `README.md`)
- PDF page reader → Page markers: returns pages (evidence: `src/ingest.py`)
- Page markers → Field extractor: supplies marked text (evidence: `src/extract.py`)
- Field extractor → Claude API: requests extraction (evidence: `src/extract.py`)
- Field extractor → Response validation: validates response (evidence: `src/extract.py`)
- Response validation → Extraction schema: validates against (evidence: `src/extract.py`)
- Booking file → Booking loader: provides JSON or CSV (evidence: `README.md`)
- Report runner → Booking loader: loads trades (evidence: `src/report.py`)
- Report runner → Field extractor: extracts once (evidence: `src/report.py`)
- Report runner → Trade comparison: compares each trade (evidence: `src/report.py`)
- Trade comparison → Deterministic matching: checks values (evidence: `src/compare.py`)
- Trade comparison → Mismatch arbitration: escalates unresolved fields (evidence: `src/compare.py`)
- Mismatch arbitration → Claude API: requests judgment (evidence: `src/compare.py`)
- Report runner → CSV report: writes CSV (evidence: `src/report.py`)
