# vedantkarne/aura-financial-intelligence architecture

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

- Interactive diagram: https://gitdiagram.com/vedantkarne/aura-financial-intelligence
- Repository: https://github.com/vedantkarne/aura-financial-intelligence

## Overview

AURA is an earnings-intelligence product for transcript Q&A, KPI lookup, and investment briefs. Users ask through the chat interface; the agent dispatches search, KPI, or report tools, which combine hybrid transcript retrieval and structured financial data before returning cited answers. Transcript ingestion and evaluation/monitoring are additional capabilities. The graph follows documented and indexed relationships; several unsampled modules are represented by their exact source paths, while uncertain internal calls are omitted.

Main entry points: [`src/generation/qa_chain.py`](https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/generation/qa_chain.py) (RAG answer chain), [`src/ingestion/pipeline.py`](https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/ingestion/pipeline.py) (Ingestion pipeline), [`src/agents/tools.py`](https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/agents/tools.py) (Agent tools), [`src/api/server.py`](https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/api/server.py) (FastAPI service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_web["Next.js interface<br/>[page.tsx]"]
  node_monitor_ui["Run monitor<br/>[page.tsx]"]
  node_api["FastAPI service<br/>[server.py]"]
  node_legacy_ui["Streamlit interface<br/>[app.py]"]
end

subgraph group_agent["Agent workflow"]
  node_agent_graph["Agent orchestrator<br/>[orchestrator.py]"]
  node_agent_tools["Agent tools<br/>[tools.py]"]
  node_agent_events["Agent events<br/>[events.py]"]
end

subgraph group_retrieval["Retrieval and generation"]
  node_qa["RAG answer chain<br/>[qa_chain.py]"]
  node_prompts["Answer prompts<br/>[prompts.py]"]
  node_router["Query router<br/>[router.py]"]
  node_transformer["Query transformer"]
  node_hybrid["Hybrid retrieval"]
  node_bm25["BM25 search<br/>[bm25_retriever.py]"]
  node_reranker["Cross-encoder reranker<br/>[reranker.py]"]
end

subgraph group_data["Earnings data"]
  node_vector[("Vector store<br/>[vector_store.py]")]
  node_kpi_schema["KPI schema<br/>[schema.py]"]
  node_kpi_extract["KPI extraction<br/>[kpi_extractor.py]"]
  node_transcript["Transcript corpus"]
  node_parser["Transcript parser<br/>[file_parser.py]"]
  node_chunker["Chunking<br/>[chunker.py]"]
  node_ingestion["Ingestion pipeline<br/>[pipeline.py]"]
  node_embedder["Embedding model<br/>[embedder.py]"]
end

subgraph group_observability["Quality and monitoring"]
  node_metrics["Evaluation metrics<br/>[compute_metrics.py]"]
  node_ragas["RAGAS evaluation<br/>[ragas_eval.py]"]
end

node_analyst(("Analyst"))

node_analyst -->|"asks questions"| node_web
node_web -.->|"sends requests"| node_api
node_api -->|"invokes agent"| node_agent_graph
node_api -->|"serves tools"| node_agent_tools
node_agent_graph -->|"dispatches tools"| node_agent_tools
node_agent_graph -->|"emits events"| node_agent_events
node_monitor_ui -.->|"displays events"| node_agent_events
node_agent_tools -->|"searches transcripts"| node_qa
node_agent_tools -->|"queries KPIs"| node_kpi_schema
node_agent_tools -->|"builds report evidence"| node_qa
node_qa -->|"routes queries"| node_router
node_qa -->|"rewrites queries"| node_transformer
node_qa -->|"retrieves candidates"| node_hybrid
node_hybrid -->|"searches vectors"| node_vector
node_hybrid -->|"searches keywords"| node_bm25
node_qa -->|"reranks candidates"| node_reranker
node_qa -->|"formats answers"| node_prompts
node_ingestion -->|"discovers files"| node_transcript
node_ingestion -->|"parses metadata"| node_parser
node_ingestion -->|"chunks text"| node_chunker
node_ingestion -->|"indexes chunks"| node_vector
node_vector -->|"embeds documents"| node_embedder
node_ingestion -->|"extracts metrics"| node_kpi_extract
node_kpi_extract -->|"creates records"| node_kpi_schema
node_analyst -.->|"uses chat"| node_legacy_ui
node_ragas -->|"evaluates answers"| node_qa
node_metrics -.->|"reports quality"| node_ragas

click node_web "https://github.com/vedantkarne/aura-financial-intelligence/blob/main/frontend/src/app/page.tsx"
click node_monitor_ui "https://github.com/vedantkarne/aura-financial-intelligence/blob/main/frontend/src/app/monitor/page.tsx"
click node_api "https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/api/server.py"
click node_agent_graph "https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/agents/orchestrator.py"
click node_agent_tools "https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/agents/tools.py"
click node_agent_events "https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/agents/events.py"
click node_qa "https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/generation/qa_chain.py"
click node_prompts "https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/generation/prompts.py"
click node_router "https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/retrieval/router.py"
click node_transformer "https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/retrieval/query_transformer.py"
click node_hybrid "https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/retrieval/hybrid_retriever.py"
click node_bm25 "https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/retrieval/bm25_retriever.py"
click node_reranker "https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/retrieval/reranker.py"
click node_vector "https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/retrieval/vector_store.py"
click node_kpi_schema "https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/extraction/schema.py"
click node_kpi_extract "https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/extraction/kpi_extractor.py"
click node_transcript "https://github.com/vedantkarne/aura-financial-intelligence/tree/main/raw_data/Earning_Call_Transcripts/cleaned_ECTs_dataset"
click node_parser "https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/ingestion/file_parser.py"
click node_chunker "https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/ingestion/chunker.py"
click node_ingestion "https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/ingestion/pipeline.py"
click node_embedder "https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/ingestion/embedder.py"
click node_metrics "https://github.com/vedantkarne/aura-financial-intelligence/blob/main/evaluation/compute_metrics.py"
click node_ragas "https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/evaluation/ragas_eval.py"
click node_legacy_ui "https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/ui/app.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_web,node_monitor_ui,node_api,node_legacy_ui toneBlue
class node_agent_graph,node_agent_tools,node_agent_events toneAmber
class node_qa,node_prompts,node_router,node_transformer,node_hybrid,node_bm25,node_reranker toneMint
class node_vector,node_kpi_schema,node_kpi_extract,node_transcript,node_parser,node_chunker,node_ingestion,node_embedder toneRose
class node_metrics,node_ragas,node_analyst toneIndigo
```

## Components

### User experience

- [Next.js interface](https://github.com/vedantkarne/aura-financial-intelligence/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Run monitor](https://github.com/vedantkarne/aura-financial-intelligence/blob/main/frontend/src/app/monitor/page.tsx): `frontend/src/app/monitor/page.tsx`
- [FastAPI service](https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/api/server.py): `src/api/server.py`
- [Streamlit interface](https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/ui/app.py): `src/ui/app.py`

### Agent workflow

- [Agent orchestrator](https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/agents/orchestrator.py): `src/agents/orchestrator.py`
- [Agent tools](https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/agents/tools.py): `src/agents/tools.py`
- [Agent events](https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/agents/events.py): `src/agents/events.py`

### Retrieval and generation

- [RAG answer chain](https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/generation/qa_chain.py): `src/generation/qa_chain.py`
- [Answer prompts](https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/generation/prompts.py): `src/generation/prompts.py`
- [Query router](https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/retrieval/router.py): `src/retrieval/router.py`
- [Query transformer](https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/retrieval/query_transformer.py): `src/retrieval/query_transformer.py`
- [Hybrid retrieval](https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/retrieval/hybrid_retriever.py): `src/retrieval/hybrid_retriever.py`
- [BM25 search](https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/retrieval/bm25_retriever.py): `src/retrieval/bm25_retriever.py`
- [Cross-encoder reranker](https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/retrieval/reranker.py): `src/retrieval/reranker.py`

### Earnings data

- [Vector store](https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/retrieval/vector_store.py): `src/retrieval/vector_store.py`
- [KPI schema](https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/extraction/schema.py): `src/extraction/schema.py`
- [KPI extraction](https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/extraction/kpi_extractor.py): `src/extraction/kpi_extractor.py`
- [Transcript corpus](https://github.com/vedantkarne/aura-financial-intelligence/tree/main/raw_data/Earning_Call_Transcripts/cleaned_ECTs_dataset): `raw_data/Earning_Call_Transcripts/cleaned_ECTs_dataset`
- [Transcript parser](https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/ingestion/file_parser.py): `src/ingestion/file_parser.py`
- [Chunking](https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/ingestion/chunker.py): `src/ingestion/chunker.py`
- [Ingestion pipeline](https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/ingestion/pipeline.py): `src/ingestion/pipeline.py`
- [Embedding model](https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/ingestion/embedder.py): `src/ingestion/embedder.py`

### Quality and monitoring

- [Evaluation metrics](https://github.com/vedantkarne/aura-financial-intelligence/blob/main/evaluation/compute_metrics.py): `evaluation/compute_metrics.py`
- [RAGAS evaluation](https://github.com/vedantkarne/aura-financial-intelligence/blob/main/src/evaluation/ragas_eval.py): `src/evaluation/ragas_eval.py`

### Other components

- **Analyst**

## Connections

- Analyst → Next.js interface: asks questions (evidence: `README.md`)
- Next.js interface → FastAPI service: sends requests
- FastAPI service → Agent orchestrator: invokes agent (evidence: `src/api/server.py`)
- FastAPI service → Agent tools: serves tools (evidence: `src/api/server.py`)
- Agent orchestrator → Agent tools: dispatches tools (evidence: `src/agents/orchestrator.py`)
- Agent orchestrator → Agent events: emits events (evidence: `src/agents/orchestrator.py`)
- Run monitor → Agent events: displays events
- Agent tools → RAG answer chain: searches transcripts (evidence: `src/agents/tools.py`)
- Agent tools → KPI schema: queries KPIs (evidence: `src/agents/tools.py`)
- Agent tools → RAG answer chain: builds report evidence (evidence: `src/agents/tools.py`)
- RAG answer chain → Query router: routes queries (evidence: `src/generation/qa_chain.py`)
- RAG answer chain → Query transformer: rewrites queries (evidence: `src/generation/qa_chain.py`)
- RAG answer chain → Hybrid retrieval: retrieves candidates (evidence: `src/generation/qa_chain.py`)
- Hybrid retrieval → Vector store: searches vectors (evidence: `src/retrieval/hybrid_retriever.py`)
- Hybrid retrieval → BM25 search: searches keywords (evidence: `src/retrieval/hybrid_retriever.py`)
- RAG answer chain → Cross-encoder reranker: reranks candidates (evidence: `src/generation/qa_chain.py`)
- RAG answer chain → Answer prompts: formats answers (evidence: `src/generation/qa_chain.py`)
- Ingestion pipeline → Transcript corpus: discovers files (evidence: `src/ingestion/pipeline.py`)
- Ingestion pipeline → Transcript parser: parses metadata (evidence: `src/ingestion/pipeline.py`)
- Ingestion pipeline → Chunking: chunks text (evidence: `src/ingestion/pipeline.py`)
- Ingestion pipeline → Vector store: indexes chunks (evidence: `src/ingestion/pipeline.py`)
- Vector store → Embedding model: embeds documents (evidence: `src/retrieval/vector_store.py`)
- Ingestion pipeline → KPI extraction: extracts metrics (evidence: `src/ingestion/pipeline.py`)
- KPI extraction → KPI schema: creates records (evidence: `src/extraction/kpi_extractor.py`)
- Analyst → Streamlit interface: uses chat
- RAGAS evaluation → RAG answer chain: evaluates answers (evidence: `src/evaluation/ragas_eval.py`)
- Evaluation metrics → RAGAS evaluation: reports quality
