# riyadhami13/vaultdocs-ai architecture

> Architecture diagram of the GitHub repository riyadhami13/vaultdocs-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/riyadhami13/vaultdocs-ai
- Repository: https://github.com/riyadhami13/vaultdocs-ai

## Overview

VaultDocs AI is a local-first contract risk screening app. A user uploads a PDF, the app extracts page text and splits it into chunks, retrieves clauses for a chosen audit focus, and uses a local Ollama model to produce structured findings. Citations are checked against extracted text; the UI presents results and offers a downloadable Markdown report. The sampled code shows PDF ingestion and retrieval calls; some UI-to-validation and report wiring is supported only by the README, so unsampled links are omitted or marked unverified.

Main entry points: [`app.py`](https://github.com/riyadhami13/vaultdocs-ai/blob/main/app.py) (Audit Orchestrator), [`reports/report_generator.py`](https://github.com/riyadhami13/vaultdocs-ai/blob/main/reports/report_generator.py) (Markdown Report Generator), [`models/schemas.py`](https://github.com/riyadhami13/vaultdocs-ai/blob/main/models/schemas.py) (Audit Report Schema), [`services/citation_validator.py`](https://github.com/riyadhami13/vaultdocs-ai/blob/main/services/citation_validator.py) (Citation Validator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interface"]
  node_dashboard["Audit Dashboard<br/>[app.py]"]
  node_document_view["Document Viewer<br/>[app.py]"]
  node_results_view["Results Screen<br/>[app.py]"]
end

subgraph group_ingestion["Document Ingestion"]
  node_pdf_parser["PDF Text Extractor<br/>[pdf_parser.py]"]
  node_clause_splitter["Clause Chunker<br/>[clause_splitter.py]"]
end

subgraph group_screening["Risk Screening"]
  node_retrieval["Clause Retrieval<br/>[retriever.py]"]
  node_audit_runner["Audit Orchestrator<br/>[app.py]"]
  node_local_model["Local Ollama Model"]
end

subgraph group_results["Validation and Reports"]
  node_report_schema["Audit Report Schema<br/>[schemas.py]"]
  node_citation_check["Citation Validator"]
  node_markdown_report["Markdown Report Generator"]
end

node_user(("Contract Reviewer"))

node_user -->|"uploads PDF"| node_dashboard
node_dashboard -->|"extracts pages"| node_pdf_parser
node_dashboard -->|"chunks text"| node_clause_splitter
node_dashboard -->|"renders pages"| node_document_view
node_user -->|"starts audit"| node_audit_runner
node_audit_runner -->|"ranks chunks"| node_retrieval
node_audit_runner -.->|"requests analysis"| node_local_model
node_audit_runner -.->|"validates findings"| node_report_schema
node_audit_runner -->|"checks citations"| node_citation_check
node_audit_runner -->|"shows results"| node_results_view
node_results_view -->|"navigates excerpts"| node_document_view
node_results_view -.->|"offers download"| node_markdown_report
node_markdown_report -->|"formats findings"| node_report_schema
node_markdown_report -->|"formats status"| node_citation_check

click node_dashboard "https://github.com/riyadhami13/vaultdocs-ai/blob/main/app.py"
click node_document_view "https://github.com/riyadhami13/vaultdocs-ai/blob/main/app.py"
click node_results_view "https://github.com/riyadhami13/vaultdocs-ai/blob/main/app.py"
click node_pdf_parser "https://github.com/riyadhami13/vaultdocs-ai/blob/main/services/pdf_parser.py"
click node_clause_splitter "https://github.com/riyadhami13/vaultdocs-ai/blob/main/services/clause_splitter.py"
click node_retrieval "https://github.com/riyadhami13/vaultdocs-ai/blob/main/services/retriever.py"
click node_audit_runner "https://github.com/riyadhami13/vaultdocs-ai/blob/main/app.py"
click node_report_schema "https://github.com/riyadhami13/vaultdocs-ai/blob/main/models/schemas.py"
click node_citation_check "https://github.com/riyadhami13/vaultdocs-ai/blob/main/services/citation_validator.py"
click node_markdown_report "https://github.com/riyadhami13/vaultdocs-ai/blob/main/reports/report_generator.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_dashboard,node_document_view,node_results_view,node_user toneBlue
class node_pdf_parser,node_clause_splitter toneAmber
class node_retrieval,node_audit_runner,node_local_model toneMint
class node_report_schema,node_citation_check,node_markdown_report toneRose
```

## Components

### User Interface

- [Audit Dashboard](https://github.com/riyadhami13/vaultdocs-ai/blob/main/app.py): `app.py`
- [Document Viewer](https://github.com/riyadhami13/vaultdocs-ai/blob/main/app.py): `app.py`
- [Results Screen](https://github.com/riyadhami13/vaultdocs-ai/blob/main/app.py): `app.py`

### Document Ingestion

- [PDF Text Extractor](https://github.com/riyadhami13/vaultdocs-ai/blob/main/services/pdf_parser.py): `services/pdf_parser.py`
- [Clause Chunker](https://github.com/riyadhami13/vaultdocs-ai/blob/main/services/clause_splitter.py): `services/clause_splitter.py`

### Risk Screening

- [Clause Retrieval](https://github.com/riyadhami13/vaultdocs-ai/blob/main/services/retriever.py): `services/retriever.py`
- [Audit Orchestrator](https://github.com/riyadhami13/vaultdocs-ai/blob/main/app.py): `app.py`
- **Local Ollama Model**

### Validation and Reports

- [Audit Report Schema](https://github.com/riyadhami13/vaultdocs-ai/blob/main/models/schemas.py): `models/schemas.py`
- [Citation Validator](https://github.com/riyadhami13/vaultdocs-ai/blob/main/services/citation_validator.py): `services/citation_validator.py`
- [Markdown Report Generator](https://github.com/riyadhami13/vaultdocs-ai/blob/main/reports/report_generator.py): `reports/report_generator.py`

### Other components

- **Contract Reviewer**

## Connections

- Contract Reviewer → Audit Dashboard: uploads PDF (evidence: `README.md`)
- Audit Dashboard → PDF Text Extractor: extracts pages (evidence: `app.py`)
- Audit Dashboard → Clause Chunker: chunks text (evidence: `app.py`)
- Audit Dashboard → Document Viewer: renders pages (evidence: `app.py`)
- Contract Reviewer → Audit Orchestrator: starts audit (evidence: `app.py`)
- Audit Orchestrator → Clause Retrieval: ranks chunks (evidence: `app.py`)
- Audit Orchestrator → Local Ollama Model: requests analysis (evidence: `README.md`)
- Audit Orchestrator → Audit Report Schema: validates findings (evidence: `README.md`)
- Audit Orchestrator → Citation Validator: checks citations (evidence: `README.md`)
- Audit Orchestrator → Results Screen: shows results (evidence: `app.py`)
- Results Screen → Document Viewer: navigates excerpts (evidence: `app.py`)
- Results Screen → Markdown Report Generator: offers download (evidence: `README.md`)
- Markdown Report Generator → Audit Report Schema: formats findings (evidence: `reports/report_generator.py`)
- Markdown Report Generator → Citation Validator: formats status (evidence: `reports/report_generator.py`)
