# moh-a-abde/financial-spreading-pipeline architecture

> Architecture diagram of the GitHub repository moh-a-abde/financial-spreading-pipeline, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/moh-a-abde/financial-spreading-pipeline
- Repository: https://github.com/moh-a-abde/financial-spreading-pipeline

## Overview

This repository implements an in-memory financial spreading workflow for reconciling two pre-extracted income-statement datasets, mapping the resolved lines to accounts, checking mathematical rules, and preserving source-level provenance. Its optional local visualizer lets an analyst inspect source evidence, mappings, rule results, and audit chains while adjusting run policy. The README documents the domain workflow; the sampled pipeline and server excerpts support the stage and integration links shown here. The frontend’s full request wiring was not sampled, so uncertain interactions are omitted.

Main entry points: [`viz/serve.py`](https://github.com/moh-a-abde/financial-spreading-pipeline/blob/main/viz/serve.py) (Local API Server), [`viz/app.js`](https://github.com/moh-a-abde/financial-spreading-pipeline/blob/main/viz/app.js) (Analyst Interface), [`viz/index.html`](https://github.com/moh-a-abde/financial-spreading-pipeline/blob/main/viz/index.html) (Visualizer Page), [`data/source_a_llm.json`](https://github.com/moh-a-abde/financial-spreading-pipeline/blob/main/data/source_a_llm.json) (LLM Extraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Spreading Inputs"]
  node_source_a["LLM Extraction<br/>[source_a_llm.json]"]
  node_source_b["OCR Extraction<br/>[source_b_ocr.json]"]
  node_taxonomy["Account Taxonomy<br/>[taxonomy.json]"]
  node_rules["Validation Rules"]
end

subgraph group_core["Spreading Pipeline"]
  node_reconcile["Reconcile Lines<br/>[pipeline.py]"]
  node_map_accounts["Map Accounts<br/>[pipeline.py]"]
  node_validate["Validate Totals<br/>[pipeline.py]"]
end

subgraph group_audit["Review and Audit"]
  node_audit_trail["Build Provenance<br/>[pipeline.py]"]
  node_unbooked["Identify Unbooked<br/>[pipeline.py]"]
end

subgraph group_viz["Local Visualizer"]
  node_serve["Local API Server<br/>[serve.py]"]
  node_web_ui["Analyst Interface<br/>[app.js]"]
  node_web_page["Visualizer Page<br/>[index.html]"]
end

node_llm_extract(("LLM Extractor"))
node_ocr_extract(("OCR Pipeline"))
node_analyst(("Financial Analyst"))

node_llm_extract -.->|"writes extractions"| node_source_a
node_ocr_extract -.->|"writes extractions"| node_source_b
node_analyst -->|"requests runs"| node_serve
node_serve -->|"loads"| node_source_a
node_serve -->|"loads"| node_source_b
node_serve -->|"loads"| node_taxonomy
node_serve -->|"loads"| node_rules
node_serve -->|"invokes"| node_reconcile
node_serve -->|"invokes"| node_map_accounts
node_serve -->|"invokes"| node_validate
node_serve -->|"invokes"| node_unbooked
node_serve -->|"invokes"| node_audit_trail
node_analyst -->|"uses"| node_web_ui
node_web_page -->|"loads script"| node_web_ui
node_serve -->|"serves"| node_web_page
node_web_ui -->|"calls API"| node_serve

click node_source_a "https://github.com/moh-a-abde/financial-spreading-pipeline/blob/main/data/source_a_llm.json"
click node_source_b "https://github.com/moh-a-abde/financial-spreading-pipeline/blob/main/data/source_b_ocr.json"
click node_taxonomy "https://github.com/moh-a-abde/financial-spreading-pipeline/blob/main/data/taxonomy.json"
click node_rules "https://github.com/moh-a-abde/financial-spreading-pipeline/blob/main/data/validation_rules.json"
click node_reconcile "https://github.com/moh-a-abde/financial-spreading-pipeline/blob/main/pipeline.py"
click node_map_accounts "https://github.com/moh-a-abde/financial-spreading-pipeline/blob/main/pipeline.py"
click node_validate "https://github.com/moh-a-abde/financial-spreading-pipeline/blob/main/pipeline.py"
click node_audit_trail "https://github.com/moh-a-abde/financial-spreading-pipeline/blob/main/pipeline.py"
click node_unbooked "https://github.com/moh-a-abde/financial-spreading-pipeline/blob/main/pipeline.py"
click node_serve "https://github.com/moh-a-abde/financial-spreading-pipeline/blob/main/viz/serve.py"
click node_web_ui "https://github.com/moh-a-abde/financial-spreading-pipeline/blob/main/viz/app.js"
click node_web_page "https://github.com/moh-a-abde/financial-spreading-pipeline/blob/main/viz/index.html"

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_source_a,node_source_b,node_taxonomy,node_rules toneBlue
class node_reconcile,node_map_accounts,node_validate toneAmber
class node_audit_trail,node_unbooked toneMint
class node_serve,node_web_ui,node_web_page toneRose
class node_llm_extract,node_ocr_extract,node_analyst toneIndigo
```

## Components

### Spreading Inputs

- [LLM Extraction](https://github.com/moh-a-abde/financial-spreading-pipeline/blob/main/data/source_a_llm.json): `data/source_a_llm.json`
- [OCR Extraction](https://github.com/moh-a-abde/financial-spreading-pipeline/blob/main/data/source_b_ocr.json): `data/source_b_ocr.json`
- [Account Taxonomy](https://github.com/moh-a-abde/financial-spreading-pipeline/blob/main/data/taxonomy.json): `data/taxonomy.json`
- [Validation Rules](https://github.com/moh-a-abde/financial-spreading-pipeline/blob/main/data/validation_rules.json): `data/validation_rules.json`

### Spreading Pipeline

- [Reconcile Lines](https://github.com/moh-a-abde/financial-spreading-pipeline/blob/main/pipeline.py): `pipeline.py`
- [Map Accounts](https://github.com/moh-a-abde/financial-spreading-pipeline/blob/main/pipeline.py): `pipeline.py`
- [Validate Totals](https://github.com/moh-a-abde/financial-spreading-pipeline/blob/main/pipeline.py): `pipeline.py`

### Review and Audit

- [Build Provenance](https://github.com/moh-a-abde/financial-spreading-pipeline/blob/main/pipeline.py): `pipeline.py`
- [Identify Unbooked](https://github.com/moh-a-abde/financial-spreading-pipeline/blob/main/pipeline.py): `pipeline.py`

### Local Visualizer

- [Local API Server](https://github.com/moh-a-abde/financial-spreading-pipeline/blob/main/viz/serve.py): `viz/serve.py`
- [Analyst Interface](https://github.com/moh-a-abde/financial-spreading-pipeline/blob/main/viz/app.js): `viz/app.js`
- [Visualizer Page](https://github.com/moh-a-abde/financial-spreading-pipeline/blob/main/viz/index.html): `viz/index.html`

### Other components

- **LLM Extractor**
- **OCR Pipeline**
- **Financial Analyst**

## Connections

- LLM Extractor → LLM Extraction: writes extractions
- OCR Pipeline → OCR Extraction: writes extractions
- Financial Analyst → Local API Server: requests runs
- Local API Server → LLM Extraction: loads
- Local API Server → OCR Extraction: loads
- Local API Server → Account Taxonomy: loads
- Local API Server → Validation Rules: loads
- Local API Server → Reconcile Lines: invokes
- Local API Server → Map Accounts: invokes
- Local API Server → Validate Totals: invokes
- Local API Server → Identify Unbooked: invokes
- Local API Server → Build Provenance: invokes
- Financial Analyst → Analyst Interface: uses
- Visualizer Page → Analyst Interface: loads script
- Local API Server → Visualizer Page: serves
- Analyst Interface → Local API Server: calls API