# etienne-landryb/docviz-document-intelligence-tool architecture

> Architecture diagram of the GitHub repository etienne-landryb/docviz-document-intelligence-tool, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/etienne-landryb/docviz-document-intelligence-tool
- Repository: https://github.com/etienne-landryb/docviz-document-intelligence-tool

## Overview

DocViz is a Streamlit financial-document intelligence tool. Its main workflow takes an uploaded digital PDF through coordinate-aware parsing, metric extraction and normalization, validation, and charts that represent missing figures as undisclosed. A separate ingestion and Q&A workflow embeds prose and metric facts, stores them for similarity retrieval, and abstains when retrieved context is weak. Comparison templates support FXAIX/VFIAX demos, while the vector-store layer provides document management. The README and excerpts support these capabilities; some app orchestration details and unsampled modules are documented rather than directly shown.

Main entry points: [`app.py`](https://github.com/etienne-landryb/docviz-document-intelligence-tool/blob/main/app.py) (Streamlit app), [`docviz/ingest.py`](https://github.com/etienne-landryb/docviz-document-intelligence-tool/blob/main/docviz/ingest.py) (Chunk ingestion), [`docviz/rag.py`](https://github.com/etienne-landryb/docviz-document-intelligence-tool/blob/main/docviz/rag.py) (Grounded Q&A), [`docviz/store.py`](https://github.com/etienne-landryb/docviz-document-intelligence-tool/blob/main/docviz/store.py) (Vector store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User workflow"]
  node_app["Streamlit app<br/>[app.py]"]
end

subgraph group_figures["Metric intelligence"]
  node_parser["PDF parser<br/>[parse.py]"]
  node_extractor["Metric extraction<br/>[extract.py]"]
  node_normalizer["Number normalization<br/>[normalize.py]"]
  node_schema["Metric contract<br/>[schema.py]"]
  node_validator["Sanity gate<br/>[validate.py]"]
  node_arranger["Chart arrangement<br/>[arrange.py]"]
  node_renderer["Chart renderer<br/>[viz.py]"]
end

subgraph group_retrieval["Retrieval and Q&amp;A"]
  node_ingest["Chunk ingestion<br/>[ingest.py]"]
  node_embedder["Local embeddings<br/>[embed.py]"]
  node_store[("Vector store<br/>[store.py]")]
  node_rag["Grounded Q&amp;A<br/>[rag.py]"]
end

subgraph group_comparison["Comparison"]
  node_funds["Fund templates<br/>[funds.py]"]
  node_compare["Fund comparison"]
end

node_user(("User"))
node_pdf["Digital PDF"]
node_groq{{"Groq API"}}
node_supabase[("Supabase pgvector")]

node_user -->|"uploads and asks"| node_app
node_app -->|"parses PDF"| node_parser
node_pdf -->|"provides pages"| node_parser
node_app -->|"extracts metrics"| node_extractor
node_extractor -->|"requests extraction"| node_groq
node_extractor -.->|"parses values"| node_normalizer
node_app -->|"normalizes values"| node_normalizer
node_app -->|"validates metrics"| node_validator
node_validator -->|"checks metrics"| node_schema
node_app -->|"requests charts"| node_renderer
node_renderer -->|"arranges panels"| node_arranger
node_app -.->|"ingests document"| node_ingest
node_ingest -->|"reads PDF rows"| node_parser
node_ingest -->|"extracts metric facts"| node_funds
node_ingest -->|"embeds chunks"| node_embedder
node_ingest -->|"writes chunks"| node_store
node_user -->|"asks question"| node_rag
node_rag -->|"embeds question"| node_embedder
node_rag -->|"searches chunks"| node_store
node_store -->|"reads and writes"| node_supabase
node_rag -->|"grounds answer"| node_groq
node_compare -->|"extracts funds"| node_funds
node_compare -->|"renders comparison"| node_renderer
node_user -.->|"manages documents"| node_store

click node_app "https://github.com/etienne-landryb/docviz-document-intelligence-tool/blob/main/app.py"
click node_parser "https://github.com/etienne-landryb/docviz-document-intelligence-tool/blob/main/docviz/parse.py"
click node_extractor "https://github.com/etienne-landryb/docviz-document-intelligence-tool/blob/main/docviz/extract.py"
click node_normalizer "https://github.com/etienne-landryb/docviz-document-intelligence-tool/blob/main/docviz/normalize.py"
click node_schema "https://github.com/etienne-landryb/docviz-document-intelligence-tool/blob/main/docviz/schema.py"
click node_validator "https://github.com/etienne-landryb/docviz-document-intelligence-tool/blob/main/docviz/validate.py"
click node_arranger "https://github.com/etienne-landryb/docviz-document-intelligence-tool/blob/main/docviz/arrange.py"
click node_renderer "https://github.com/etienne-landryb/docviz-document-intelligence-tool/blob/main/docviz/viz.py"
click node_ingest "https://github.com/etienne-landryb/docviz-document-intelligence-tool/blob/main/docviz/ingest.py"
click node_embedder "https://github.com/etienne-landryb/docviz-document-intelligence-tool/blob/main/docviz/embed.py"
click node_store "https://github.com/etienne-landryb/docviz-document-intelligence-tool/blob/main/docviz/store.py"
click node_rag "https://github.com/etienne-landryb/docviz-document-intelligence-tool/blob/main/docviz/rag.py"
click node_funds "https://github.com/etienne-landryb/docviz-document-intelligence-tool/blob/main/docviz/funds.py"
click node_compare "https://github.com/etienne-landryb/docviz-document-intelligence-tool/blob/main/run_phase1_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_app,node_user toneBlue
class node_parser,node_extractor,node_normalizer,node_schema,node_validator,node_arranger,node_renderer,node_supabase toneAmber
class node_ingest,node_embedder,node_store,node_rag,node_groq toneMint
class node_funds,node_compare toneRose
class node_pdf toneIndigo
```

## Components

### User workflow

- [Streamlit app](https://github.com/etienne-landryb/docviz-document-intelligence-tool/blob/main/app.py): `app.py`

### Metric intelligence

- [PDF parser](https://github.com/etienne-landryb/docviz-document-intelligence-tool/blob/main/docviz/parse.py): `docviz/parse.py`
- [Metric extraction](https://github.com/etienne-landryb/docviz-document-intelligence-tool/blob/main/docviz/extract.py): `docviz/extract.py`
- [Number normalization](https://github.com/etienne-landryb/docviz-document-intelligence-tool/blob/main/docviz/normalize.py): `docviz/normalize.py`
- [Metric contract](https://github.com/etienne-landryb/docviz-document-intelligence-tool/blob/main/docviz/schema.py): `docviz/schema.py`
- [Sanity gate](https://github.com/etienne-landryb/docviz-document-intelligence-tool/blob/main/docviz/validate.py): `docviz/validate.py`
- [Chart arrangement](https://github.com/etienne-landryb/docviz-document-intelligence-tool/blob/main/docviz/arrange.py): `docviz/arrange.py`
- [Chart renderer](https://github.com/etienne-landryb/docviz-document-intelligence-tool/blob/main/docviz/viz.py): `docviz/viz.py`

### Retrieval and Q&A

- [Chunk ingestion](https://github.com/etienne-landryb/docviz-document-intelligence-tool/blob/main/docviz/ingest.py): `docviz/ingest.py`
- [Local embeddings](https://github.com/etienne-landryb/docviz-document-intelligence-tool/blob/main/docviz/embed.py): `docviz/embed.py`
- [Vector store](https://github.com/etienne-landryb/docviz-document-intelligence-tool/blob/main/docviz/store.py): `docviz/store.py`
- [Grounded Q&A](https://github.com/etienne-landryb/docviz-document-intelligence-tool/blob/main/docviz/rag.py): `docviz/rag.py`

### Comparison

- [Fund templates](https://github.com/etienne-landryb/docviz-document-intelligence-tool/blob/main/docviz/funds.py): `docviz/funds.py`
- [Fund comparison](https://github.com/etienne-landryb/docviz-document-intelligence-tool/blob/main/run_phase1_compare.py): `run_phase1_compare.py`

### Other components

- **User**
- **Digital PDF**
- **Groq API**
- **Supabase pgvector**

## Connections

- User → Streamlit app: uploads and asks (evidence: `README.md`)
- Streamlit app → PDF parser: parses PDF (evidence: `app.py`)
- Digital PDF → PDF parser: provides pages (evidence: `docviz/parse.py`)
- Streamlit app → Metric extraction: extracts metrics (evidence: `README.md`)
- Metric extraction → Groq API: requests extraction (evidence: `README.md`)
- Metric extraction → Number normalization: parses values
- Streamlit app → Number normalization: normalizes values (evidence: `app.py`)
- Streamlit app → Sanity gate: validates metrics (evidence: `README.md`)
- Sanity gate → Metric contract: checks metrics (evidence: `docviz/validate.py`)
- Streamlit app → Chart renderer: requests charts (evidence: `app.py`)
- Chart renderer → Chart arrangement: arranges panels (evidence: `docviz/viz.py`)
- Streamlit app → Chunk ingestion: ingests document
- Chunk ingestion → PDF parser: reads PDF rows (evidence: `docviz/ingest.py`)
- Chunk ingestion → Fund templates: extracts metric facts (evidence: `docviz/ingest.py`)
- Chunk ingestion → Local embeddings: embeds chunks (evidence: `docviz/ingest.py`)
- Chunk ingestion → Vector store: writes chunks (evidence: `docviz/ingest.py`)
- User → Grounded Q&A: asks question (evidence: `README.md`)
- Grounded Q&A → Local embeddings: embeds question (evidence: `docviz/rag.py`)
- Grounded Q&A → Vector store: searches chunks (evidence: `docviz/rag.py`)
- Vector store → Supabase pgvector: reads and writes (evidence: `docviz/store.py`)
- Grounded Q&A → Groq API: grounds answer (evidence: `docviz/rag.py`)
- Fund comparison → Fund templates: extracts funds (evidence: `run_phase1_compare.py`)
- Fund comparison → Chart renderer: renders comparison (evidence: `run_phase1_compare.py`)
- User → Vector store: manages documents
