# agamaciag/vigil-document-analyst architecture

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

- Interactive diagram: https://gitdiagram.com/agamaciag/vigil-document-analyst
- Repository: https://github.com/agamaciag/vigil-document-analyst

## Overview

Vigil is a web-based enterprise document analyst. Users upload documents, choose a workflow, and receive a report from a three-stage Indexer → Analyzer → Advisor pipeline; they can inspect intermediate JSON and ask follow-up questions grounded in indexed document data. Upload parsing, workflow orchestration, semantic search, and chat are distinct parts of the runtime. The README documents workflow and OCR capabilities beyond the sampled excerpts; links to those unsampled internals are omitted where their callers are not shown.

Main entry points: [`routes/pipeline.py`](https://github.com/agamaciag/vigil-document-analyst/blob/master/routes/pipeline.py) (Workflow orchestrator), [`app.py`](https://github.com/agamaciag/vigil-document-analyst/blob/master/app.py) (HTTP app), [`search_client.py`](https://github.com/agamaciag/vigil-document-analyst/blob/master/search_client.py) (Search integration), [`foundry_client.py`](https://github.com/agamaciag/vigil-document-analyst/blob/master/foundry_client.py) (Foundry client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_ui["Web UI<br/>[app.js]"]
  node_server["HTTP app<br/>[app.py]"]
  node_middleware["Security middleware<br/>[middleware.py]"]
end

subgraph group_ingest["Document ingestion"]
  node_upload["Upload route<br/>[upload.py]"]
  node_parser["Document parser<br/>[doc_parser.py]"]
  node_sessions[("Upload sessions<br/>[__init__.py]")]
end

subgraph group_analysis["Analysis pipeline"]
  node_pipeline["Workflow orchestrator<br/>[pipeline.py]"]
  node_chunker["Document chunker<br/>[chunker.py]"]
  node_indexer["Fact indexer<br/>[indexer.py]"]
  node_analyzer["Document analyzer<br/>[analyzer.py]"]
  node_gaprules["Gap rules<br/>[gap_rules.py]"]
  node_advisor["Report advisor<br/>[advisor.py]"]
end

subgraph group_intelligence["Search and chat"]
  node_chat["Follow-up chat<br/>[chat.py]"]
  node_search["Search integration<br/>[search_client.py]"]
end

subgraph group_platform["Azure services"]
  node_agentregistry["Agent registration<br/>[__init__.py]"]
  node_foundryclient["Foundry client<br/>[foundry_client.py]"]
end

node_user(("Enterprise user"))
node_azureai{{"Azure AI Foundry"}}
node_aisearch[("Azure AI Search")]

node_user -->|"uses"| node_ui
node_ui -->|"calls API"| node_server
node_server -->|"routes uploads"| node_upload
node_server -->|"routes runs"| node_pipeline
node_server -->|"routes questions"| node_chat
node_server -->|"applies"| node_middleware
node_upload -->|"parses files"| node_parser
node_upload -->|"stores documents"| node_sessions
node_pipeline -->|"resolves documents"| node_sessions
node_pipeline -->|"chunks documents"| node_chunker
node_pipeline -->|"runs stage"| node_indexer
node_pipeline -->|"runs stage"| node_analyzer
node_pipeline -->|"runs stage"| node_advisor
node_pipeline -->|"indexes chunks"| node_search
node_pipeline -->|"indexes facts"| node_search
node_pipeline -.->|"evaluates rules"| node_gaprules
node_chat -->|"retrieves context"| node_search
node_chat -->|"gets inference client"| node_foundryclient
node_search -.->|"queries indexes"| node_aisearch
node_search -.->|"writes indexes"| node_aisearch
node_server -->|"registers agents"| node_agentregistry
node_agentregistry -->|"registers"| node_indexer
node_agentregistry -->|"registers"| node_analyzer
node_agentregistry -->|"registers"| node_advisor
node_indexer -->|"gets inference client"| node_foundryclient
node_analyzer -.->|"gets inference client"| node_foundryclient
node_advisor -.->|"gets inference client"| node_foundryclient
node_foundryclient -->|"connects"| node_azureai
node_parser -.->|"uses OCR"| node_azureai

click node_ui "https://github.com/agamaciag/vigil-document-analyst/blob/master/static/app.js"
click node_server "https://github.com/agamaciag/vigil-document-analyst/blob/master/app.py"
click node_middleware "https://github.com/agamaciag/vigil-document-analyst/blob/master/middleware.py"
click node_upload "https://github.com/agamaciag/vigil-document-analyst/blob/master/routes/upload.py"
click node_parser "https://github.com/agamaciag/vigil-document-analyst/blob/master/doc_parser.py"
click node_sessions "https://github.com/agamaciag/vigil-document-analyst/blob/master/routes/__init__.py"
click node_pipeline "https://github.com/agamaciag/vigil-document-analyst/blob/master/routes/pipeline.py"
click node_chunker "https://github.com/agamaciag/vigil-document-analyst/blob/master/chunker.py"
click node_indexer "https://github.com/agamaciag/vigil-document-analyst/blob/master/agents/indexer.py"
click node_analyzer "https://github.com/agamaciag/vigil-document-analyst/blob/master/agents/analyzer.py"
click node_gaprules "https://github.com/agamaciag/vigil-document-analyst/blob/master/gap_rules.py"
click node_advisor "https://github.com/agamaciag/vigil-document-analyst/blob/master/agents/advisor.py"
click node_chat "https://github.com/agamaciag/vigil-document-analyst/blob/master/routes/chat.py"
click node_search "https://github.com/agamaciag/vigil-document-analyst/blob/master/search_client.py"
click node_agentregistry "https://github.com/agamaciag/vigil-document-analyst/blob/master/agents/__init__.py"
click node_foundryclient "https://github.com/agamaciag/vigil-document-analyst/blob/master/foundry_client.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_ui,node_server,node_middleware,node_user toneBlue
class node_upload,node_parser,node_sessions,node_aisearch toneAmber
class node_pipeline,node_chunker,node_indexer,node_analyzer,node_gaprules,node_advisor toneMint
class node_chat,node_search toneRose
class node_agentregistry,node_foundryclient,node_azureai toneIndigo
```

## Components

### Web interface

- [Web UI](https://github.com/agamaciag/vigil-document-analyst/blob/master/static/app.js): `static/app.js`
- [HTTP app](https://github.com/agamaciag/vigil-document-analyst/blob/master/app.py): `app.py`
- [Security middleware](https://github.com/agamaciag/vigil-document-analyst/blob/master/middleware.py): `middleware.py`

### Document ingestion

- [Upload route](https://github.com/agamaciag/vigil-document-analyst/blob/master/routes/upload.py): `routes/upload.py`
- [Document parser](https://github.com/agamaciag/vigil-document-analyst/blob/master/doc_parser.py): `doc_parser.py`
- [Upload sessions](https://github.com/agamaciag/vigil-document-analyst/blob/master/routes/__init__.py): `routes/__init__.py`

### Analysis pipeline

- [Workflow orchestrator](https://github.com/agamaciag/vigil-document-analyst/blob/master/routes/pipeline.py): `routes/pipeline.py`
- [Document chunker](https://github.com/agamaciag/vigil-document-analyst/blob/master/chunker.py): `chunker.py`
- [Fact indexer](https://github.com/agamaciag/vigil-document-analyst/blob/master/agents/indexer.py): `agents/indexer.py`
- [Document analyzer](https://github.com/agamaciag/vigil-document-analyst/blob/master/agents/analyzer.py): `agents/analyzer.py`
- [Gap rules](https://github.com/agamaciag/vigil-document-analyst/blob/master/gap_rules.py): `gap_rules.py`
- [Report advisor](https://github.com/agamaciag/vigil-document-analyst/blob/master/agents/advisor.py): `agents/advisor.py`

### Search and chat

- [Follow-up chat](https://github.com/agamaciag/vigil-document-analyst/blob/master/routes/chat.py): `routes/chat.py`
- [Search integration](https://github.com/agamaciag/vigil-document-analyst/blob/master/search_client.py): `search_client.py`

### Azure services

- [Agent registration](https://github.com/agamaciag/vigil-document-analyst/blob/master/agents/__init__.py): `agents/__init__.py`
- [Foundry client](https://github.com/agamaciag/vigil-document-analyst/blob/master/foundry_client.py): `foundry_client.py`

### Other components

- **Enterprise user**
- **Azure AI Foundry**
- **Azure AI Search**

## Connections

- Enterprise user → Web UI: uses (evidence: `README.md`)
- Web UI → HTTP app: calls API (evidence: `README.md`)
- HTTP app → Upload route: routes uploads (evidence: `app.py`)
- HTTP app → Workflow orchestrator: routes runs (evidence: `app.py`)
- HTTP app → Follow-up chat: routes questions (evidence: `app.py`)
- HTTP app → Security middleware: applies (evidence: `app.py`)
- Upload route → Document parser: parses files (evidence: `routes/upload.py`)
- Upload route → Upload sessions: stores documents (evidence: `README.md`)
- Workflow orchestrator → Upload sessions: resolves documents (evidence: `README.md`)
- Workflow orchestrator → Document chunker: chunks documents (evidence: `routes/pipeline.py`)
- Workflow orchestrator → Fact indexer: runs stage (evidence: `routes/pipeline.py`)
- Workflow orchestrator → Document analyzer: runs stage (evidence: `README.md`)
- Workflow orchestrator → Report advisor: runs stage (evidence: `routes/pipeline.py`)
- Workflow orchestrator → Search integration: indexes chunks (evidence: `routes/pipeline.py`)
- Workflow orchestrator → Search integration: indexes facts (evidence: `routes/pipeline.py`)
- Workflow orchestrator → Gap rules: evaluates rules (evidence: `routes/pipeline.py`)
- Follow-up chat → Search integration: retrieves context (evidence: `routes/chat.py`)
- Follow-up chat → Foundry client: gets inference client (evidence: `routes/chat.py`)
- Search integration → Azure AI Search: queries indexes
- Search integration → Azure AI Search: writes indexes
- HTTP app → Agent registration: registers agents (evidence: `app.py`)
- Agent registration → Fact indexer: registers (evidence: `agents/__init__.py`)
- Agent registration → Document analyzer: registers (evidence: `agents/__init__.py`)
- Agent registration → Report advisor: registers (evidence: `agents/__init__.py`)
- Fact indexer → Foundry client: gets inference client (evidence: `agents/indexer.py`)
- Document analyzer → Foundry client: gets inference client (evidence: `agents/analyzer.py`)
- Report advisor → Foundry client: gets inference client (evidence: `agents/advisor.py`)
- Foundry client → Azure AI Foundry: connects (evidence: `foundry_client.py`)
- Document parser → Azure AI Foundry: uses OCR
