# tirthraj1605/ai-powered-investor-intelligence-platform architecture

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

- Interactive diagram: https://gitdiagram.com/tirthraj1605/ai-powered-investor-intelligence-platform
- Repository: https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform

## Overview

The product is an investor-intelligence backend that turns uploaded annual-report PDFs into searchable report content and stored financial KPIs, then serves KPI dashboards and report-grounded chat. Its main workflow runs from upload through conversion, chunking, Azure AI Search indexing, RAG extraction, and PostgreSQL persistence. Azure OpenAI provides embeddings and structured or conversational completions. The tree also contains a second FastAPI entry point for dashboard and health routes; the sampled excerpts do not establish how that entry point is deployed. Relationships below are limited to shown calls and documented capabilities.

Main entry points: [`app.py`](https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/app.py) (FastAPI app), [`ingestion/ingest_documents.py`](https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/ingestion/ingest_documents.py) (Ingestion orchestrator), [`database/postgres_sql.py`](https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/database/postgres_sql.py) (PostgreSQL connection), [`routes/chat.py`](https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/routes/chat.py) (Chat endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and dashboard"]
  node_app["FastAPI app<br/>[app.py]"]
  node_main_app["Alternate API app<br/>[main.py]"]
  node_upload_route["Upload endpoint<br/>[ingestion.py]"]
  node_chat_route["Chat endpoint<br/>[chat.py]"]
  node_dashboard["Dashboard view<br/>[dashboard.html]"]
  node_dashboard_route["Dashboard route<br/>[dashboard.py]"]
  node_health["Health route<br/>[health.py]"]
end

subgraph group_ingest["Report ingestion"]
  node_ingest["Ingestion orchestrator"]
  node_pdf_convert["PDF conversion<br/>[pdf_to_markdown.py]"]
  node_chunking["Semantic chunking"]
end

subgraph group_ai["Search and AI"]
  node_search_store["Search store and retriever<br/>[azure_ai_search.py]"]
  node_index_setup["Search index setup<br/>[create_index.py]"]
  node_kpi_rag["KPI RAG extraction"]
  node_llm["OpenAI client<br/>[azure_openai.py]"]
end

subgraph group_metrics["KPI persistence"]
  node_metric_save["KPI persistence<br/>[save_metrics.py]"]
  node_metric_read["KPI reader<br/>[metrics.py]"]
  node_db_setup["Database setup<br/>[create_table.py]"]
  node_sql["PostgreSQL connection<br/>[postgres_sql.py]"]
end

node_user(("Investor / uploader"))
node_azure_search[("Azure AI Search")]
node_azure_openai(("Azure OpenAI"))
node_postgres[("PostgreSQL")]

node_user -->|"uploads PDF"| node_upload_route
node_user -->|"asks question"| node_chat_route
node_user -->|"opens dashboard"| node_app
node_app -->|"registers route"| node_upload_route
node_app -->|"registers route"| node_chat_route
node_app -->|"reads metrics"| node_metric_read
node_app -->|"renders template"| node_dashboard
node_app -->|"creates tables"| node_db_setup
node_app -->|"creates index"| node_index_setup
node_main_app -->|"registers route"| node_dashboard_route
node_main_app -->|"registers route"| node_health
node_upload_route -->|"calls ingestion"| node_ingest
node_ingest -->|"converts PDF"| node_pdf_convert
node_ingest -->|"chunks markdown"| node_chunking
node_ingest -->|"uploads chunks"| node_search_store
node_ingest -->|"extracts KPIs"| node_kpi_rag
node_ingest -->|"saves metrics"| node_metric_save
node_ingest -->|"requests embeddings"| node_azure_openai
node_search_store -->|"uploads and searches"| node_azure_search
node_index_setup -->|"configures index"| node_azure_search
node_kpi_rag -->|"retrieves report context"| node_search_store
node_kpi_rag -->|"requests structured output"| node_llm
node_chat_route -->|"retrieves context"| node_search_store
node_chat_route -->|"requests chat completion"| node_llm
node_llm -->|"calls completion API"| node_azure_openai
node_metric_save -->|"gets engine"| node_sql
node_metric_read -->|"queries metrics"| node_sql
node_db_setup -->|"uses connection"| node_sql
node_sql -->|"connects"| node_postgres
node_dashboard_route -->|"reads dashboard data"| node_sql

click node_app "https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/app.py"
click node_main_app "https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/main.py"
click node_upload_route "https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/routes/ingestion.py"
click node_chat_route "https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/routes/chat.py"
click node_dashboard "https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/templates/dashboard.html"
click node_dashboard_route "https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/routes/dashboard.py"
click node_health "https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/routes/health.py"
click node_ingest "https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/ingestion/ingest_documents.py"
click node_pdf_convert "https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/ingestion/pdf_to_markdown.py"
click node_chunking "https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/ingestion/semantic_chunker.py"
click node_search_store "https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/vectorstore/azure_ai_search.py"
click node_index_setup "https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/vectorstore/create_index.py"
click node_kpi_rag "https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/rag/kpi_extractor_rag.py"
click node_llm "https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/llm/azure_openai.py"
click node_metric_save "https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/database/save_metrics.py"
click node_metric_read "https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/database/metrics.py"
click node_db_setup "https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/database/create_table.py"
click node_sql "https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/database/postgres_sql.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_main_app,node_upload_route,node_chat_route,node_dashboard,node_dashboard_route,node_health toneBlue
class node_ingest,node_pdf_convert,node_chunking,node_azure_search,node_postgres toneAmber
class node_search_store,node_index_setup,node_kpi_rag,node_llm toneMint
class node_metric_save,node_metric_read,node_db_setup,node_sql toneRose
class node_user,node_azure_openai toneIndigo
```

## Components

### API and dashboard

- [FastAPI app](https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/app.py): `app.py`
- [Alternate API app](https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/main.py): `main.py`
- [Upload endpoint](https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/routes/ingestion.py): `routes/ingestion.py`
- [Chat endpoint](https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/routes/chat.py): `routes/chat.py`
- [Dashboard view](https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/templates/dashboard.html): `templates/dashboard.html`
- [Dashboard route](https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/routes/dashboard.py): `routes/dashboard.py`
- [Health route](https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/routes/health.py): `routes/health.py`

### Report ingestion

- [Ingestion orchestrator](https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/ingestion/ingest_documents.py): `ingestion/ingest_documents.py`
- [PDF conversion](https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/ingestion/pdf_to_markdown.py): `ingestion/pdf_to_markdown.py`
- [Semantic chunking](https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/ingestion/semantic_chunker.py): `ingestion/semantic_chunker.py`

### Search and AI

- [Search store and retriever](https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/vectorstore/azure_ai_search.py): `vectorstore/azure_ai_search.py`
- [Search index setup](https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/vectorstore/create_index.py): `vectorstore/create_index.py`
- [KPI RAG extraction](https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/rag/kpi_extractor_rag.py): `rag/kpi_extractor_rag.py`
- [OpenAI client](https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/llm/azure_openai.py): `llm/azure_openai.py`

### KPI persistence

- [KPI persistence](https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/database/save_metrics.py): `database/save_metrics.py`
- [KPI reader](https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/database/metrics.py): `database/metrics.py`
- [Database setup](https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/database/create_table.py): `database/create_table.py`
- [PostgreSQL connection](https://github.com/tirthraj1605/ai-powered-investor-intelligence-platform/blob/main/database/postgres_sql.py): `database/postgres_sql.py`

### Other components

- **Investor / uploader**
- **Azure AI Search**
- **Azure OpenAI**
- **PostgreSQL**

## Connections

- Investor / uploader → Upload endpoint: uploads PDF (evidence: `routes/ingestion.py`)
- Investor / uploader → Chat endpoint: asks question (evidence: `routes/chat.py`)
- Investor / uploader → FastAPI app: opens dashboard (evidence: `app.py`)
- FastAPI app → Upload endpoint: registers route (evidence: `app.py`)
- FastAPI app → Chat endpoint: registers route (evidence: `app.py`)
- FastAPI app → KPI reader: reads metrics (evidence: `app.py`)
- FastAPI app → Dashboard view: renders template (evidence: `app.py`)
- FastAPI app → Database setup: creates tables (evidence: `app.py`)
- FastAPI app → Search index setup: creates index (evidence: `app.py`)
- Alternate API app → Dashboard route: registers route (evidence: `main.py`)
- Alternate API app → Health route: registers route (evidence: `main.py`)
- Upload endpoint → Ingestion orchestrator: calls ingestion (evidence: `routes/ingestion.py`)
- Ingestion orchestrator → PDF conversion: converts PDF (evidence: `ingestion/ingest_documents.py`)
- Ingestion orchestrator → Semantic chunking: chunks markdown (evidence: `ingestion/ingest_documents.py`)
- Ingestion orchestrator → Search store and retriever: uploads chunks (evidence: `ingestion/ingest_documents.py`)
- Ingestion orchestrator → KPI RAG extraction: extracts KPIs (evidence: `ingestion/ingest_documents.py`)
- Ingestion orchestrator → KPI persistence: saves metrics (evidence: `ingestion/ingest_documents.py`)
- Ingestion orchestrator → Azure OpenAI: requests embeddings (evidence: `ingestion/ingest_documents.py`)
- Search store and retriever → Azure AI Search: uploads and searches (evidence: `vectorstore/azure_ai_search.py`)
- Search index setup → Azure AI Search: configures index (evidence: `vectorstore/create_index.py`)
- KPI RAG extraction → Search store and retriever: retrieves report context (evidence: `rag/kpi_extractor_rag.py`)
- KPI RAG extraction → OpenAI client: requests structured output (evidence: `rag/kpi_extractor_rag.py`)
- Chat endpoint → Search store and retriever: retrieves context (evidence: `routes/chat.py`)
- Chat endpoint → OpenAI client: requests chat completion (evidence: `routes/chat.py`)
- OpenAI client → Azure OpenAI: calls completion API (evidence: `llm/azure_openai.py`)
- KPI persistence → PostgreSQL connection: gets engine (evidence: `database/save_metrics.py`)
- KPI reader → PostgreSQL connection: queries metrics (evidence: `database/metrics.py`)
- Database setup → PostgreSQL connection: uses connection (evidence: `database/create_table.py`)
- PostgreSQL connection → PostgreSQL: connects (evidence: `database/postgres_sql.py`)
- Dashboard route → PostgreSQL connection: reads dashboard data (evidence: `routes/dashboard.py`)