# nikhilrana2076/ixbrl-qa-demo architecture

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

- Interactive diagram: https://gitdiagram.com/nikhilrana2076/ixbrl-qa-demo
- Repository: https://github.com/nikhilrana2076/ixbrl-qa-demo

## Overview

TagTrace is a web app for answering questions about UK company accounts using tagged iXBRL facts rather than unconstrained report reading. The main workflow is upload, parse and store a filing, retrieve relevant tagged facts for a question, then verify the model’s cited evidence before displaying an answer. The graph also preserves documented overview, ratios and fact-explorer capabilities. Relationships are limited to README statements and the supplied source excerpts or index; some unsampled internals are therefore not linked.

Main entry points: [`webapp/__init__.py`](https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/webapp/__init__.py) (Web routes), [`webapp/answering.py`](https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/webapp/answering.py) (Answer verification), [`src/ingestion/store.py`](https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/src/ingestion/store.py) (SQLite fact store), [`webapp/ingest.py`](https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/webapp/ingest.py) (Upload handling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["Web routes<br/>[__init__.py]"]
  node_sessions["Filing sessions<br/>[sessions.py]"]
end

subgraph group_ingestion["Filing ingestion"]
  node_upload["Upload handling<br/>[ingest.py]"]
  node_parser["iXBRL parser<br/>[parser.py]"]
  node_store_loader["Fact store loader<br/>[store.py]"]
  node_fact_store[("SQLite fact store<br/>[store.py]")]
end

subgraph group_evidence["Evidence and answers"]
  node_question["Question retrieval<br/>[adhoc_retrieval.py]"]
  node_retrieval["Fact retrieval<br/>[retrieval.py]"]
  node_answering["Answer verification<br/>[answering.py]"]
  node_llm_wrapper["Metered LLM client<br/>[llm.py]"]
  node_anthropic["Anthropic client<br/>[client.py]"]
  node_openai["OpenAI client<br/>[openai_client.py]"]
end

subgraph group_presentation["Filing insights"]
  node_overview["Filing overview<br/>[overview.py]"]
  node_ratios["Key ratios<br/>[ratios.py]"]
  node_formatting["Fact formatting<br/>[formatting.py]"]
  node_fact_explorer["Fact explorer<br/>[__init__.py]"]
end

node_visitor(("Visitor"))
node_external_model(("LLM providers"))

node_visitor -->|"uses"| node_webapp
node_webapp -->|"routes upload"| node_upload
node_upload -->|"parses filing"| node_parser
node_upload -->|"loads facts"| node_store_loader
node_store_loader -->|"writes facts"| node_fact_store
node_webapp -->|"manages sessions"| node_sessions
node_webapp -->|"builds overview"| node_overview
node_overview -->|"reads facts"| node_fact_store
node_webapp -->|"shows ratios"| node_ratios
node_ratios -->|"formats figures"| node_formatting
node_webapp -->|"serves fact search"| node_fact_explorer
node_visitor -->|"asks question"| node_answering
node_webapp -->|"routes question"| node_answering
node_answering -->|"retrieves evidence"| node_question
node_question -->|"uses search"| node_retrieval
node_question -->|"queries facts"| node_fact_store
node_answering -->|"requests answer"| node_llm_wrapper
node_llm_wrapper -->|"selects provider"| node_anthropic
node_llm_wrapper -->|"selects provider"| node_openai
node_anthropic -->|"calls API"| node_external_model
node_openai -->|"calls API"| node_external_model
node_answering -->|"hydrates citations"| node_fact_store
node_answering -->|"formats answer"| node_formatting
node_answering -->|"returns verified card"| node_visitor

click node_webapp "https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/webapp/__init__.py"
click node_sessions "https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/webapp/sessions.py"
click node_upload "https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/webapp/ingest.py"
click node_parser "https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/src/ingestion/parser.py"
click node_store_loader "https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/src/ingestion/store.py"
click node_fact_store "https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/src/ingestion/store.py"
click node_question "https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/src/generation/adhoc_retrieval.py"
click node_retrieval "https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/src/generation/retrieval.py"
click node_answering "https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/webapp/answering.py"
click node_llm_wrapper "https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/webapp/llm.py"
click node_anthropic "https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/src/generation/client.py"
click node_openai "https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/src/generation/openai_client.py"
click node_overview "https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/webapp/overview.py"
click node_ratios "https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/webapp/ratios.py"
click node_formatting "https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/webapp/formatting.py"
click node_fact_explorer "https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/webapp/__init__.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_webapp,node_sessions toneBlue
class node_upload,node_parser,node_store_loader,node_fact_store toneAmber
class node_question,node_retrieval,node_answering,node_llm_wrapper,node_anthropic,node_openai toneMint
class node_overview,node_ratios,node_formatting,node_fact_explorer toneRose
class node_visitor,node_external_model toneIndigo
```

## Components

### Web experience

- [Web routes](https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/webapp/__init__.py): `webapp/__init__.py`
- [Filing sessions](https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/webapp/sessions.py): `webapp/sessions.py`

### Filing ingestion

- [Upload handling](https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/webapp/ingest.py): `webapp/ingest.py`
- [iXBRL parser](https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/src/ingestion/parser.py): `src/ingestion/parser.py`
- [Fact store loader](https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/src/ingestion/store.py): `src/ingestion/store.py`
- [SQLite fact store](https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/src/ingestion/store.py): `src/ingestion/store.py`

### Evidence and answers

- [Question retrieval](https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/src/generation/adhoc_retrieval.py): `src/generation/adhoc_retrieval.py`
- [Fact retrieval](https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/src/generation/retrieval.py): `src/generation/retrieval.py`
- [Answer verification](https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/webapp/answering.py): `webapp/answering.py`
- [Metered LLM client](https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/webapp/llm.py): `webapp/llm.py`
- [Anthropic client](https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/src/generation/client.py): `src/generation/client.py`
- [OpenAI client](https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/src/generation/openai_client.py): `src/generation/openai_client.py`

### Filing insights

- [Filing overview](https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/webapp/overview.py): `webapp/overview.py`
- [Key ratios](https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/webapp/ratios.py): `webapp/ratios.py`
- [Fact formatting](https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/webapp/formatting.py): `webapp/formatting.py`
- [Fact explorer](https://github.com/nikhilrana2076/ixbrl-qa-demo/blob/main/webapp/__init__.py): `webapp/__init__.py`

### Other components

- **Visitor**
- **LLM providers**

## Connections

- Visitor → Web routes: uses (evidence: `README.md`)
- Web routes → Upload handling: routes upload (evidence: `webapp/__init__.py`)
- Upload handling → iXBRL parser: parses filing (evidence: `webapp/ingest.py`)
- Upload handling → Fact store loader: loads facts (evidence: `webapp/ingest.py`)
- Fact store loader → SQLite fact store: writes facts (evidence: `README.md`)
- Web routes → Filing sessions: manages sessions (evidence: `webapp/__init__.py`)
- Web routes → Filing overview: builds overview (evidence: `webapp/__init__.py`)
- Filing overview → SQLite fact store: reads facts (evidence: `README.md`)
- Web routes → Key ratios: shows ratios (evidence: `README.md`)
- Key ratios → Fact formatting: formats figures (evidence: `webapp/ratios.py`)
- Web routes → Fact explorer: serves fact search (evidence: `webapp/__init__.py`)
- Visitor → Answer verification: asks question (evidence: `README.md`)
- Web routes → Answer verification: routes question (evidence: `webapp/__init__.py`)
- Answer verification → Question retrieval: retrieves evidence (evidence: `webapp/answering.py`)
- Question retrieval → Fact retrieval: uses search (evidence: `src/generation/adhoc_retrieval.py`)
- Question retrieval → SQLite fact store: queries facts (evidence: `README.md`)
- Answer verification → Metered LLM client: requests answer (evidence: `README.md`)
- Metered LLM client → Anthropic client: selects provider (evidence: `webapp/llm.py`)
- Metered LLM client → OpenAI client: selects provider (evidence: `webapp/llm.py`)
- Anthropic client → LLM providers: calls API (evidence: `src/generation/client.py`)
- OpenAI client → LLM providers: calls API (evidence: `src/generation/openai_client.py`)
- Answer verification → SQLite fact store: hydrates citations (evidence: `webapp/answering.py`)
- Answer verification → Fact formatting: formats answer (evidence: `webapp/answering.py`)
- Answer verification → Visitor: returns verified card (evidence: `README.md`)
