# sandesh-hase/ai-powered-investor-intelligence-platform architecture

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

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

## Overview

This is a FastAPI investor-intelligence backend. Its primary workflow accepts an annual-report PDF, converts and chunks it, indexes the chunks in Azure AI Search, extracts financial metrics with retrieval-augmented Azure OpenAI, and stores KPIs in PostgreSQL; chat and dashboard endpoints expose results. The graph also preserves index initialization and the separate API entry point. Edges reflect the excerpts, SOURCE INDEX references, or README; unsampled internals are not inferred.

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

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and presentation"]
  node_app["FastAPI application<br/>[app.py]"]
  node_dashboard_ui["Dashboard template<br/>[dashboard.html]"]
  node_dashboard_api["Dashboard API routes<br/>[dashboard.py]"]
  node_health_api["Health routes<br/>[health.py]"]
  node_ingestion_api["Upload endpoint<br/>[ingestion.py]"]
  node_chat_api["Chat endpoint<br/>[chat.py]"]
  node_alternate_app["Alternate API entry<br/>[main.py]"]
end

subgraph group_ingestion["Report ingestion"]
  node_pdf_converter["PDF conversion<br/>[pdf_to_markdown.py]"]
  node_chunker["Semantic chunking"]
  node_ingest["Document orchestrator"]
end

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

subgraph group_storage["Persistence"]
  node_metrics_save["KPI persistence<br/>[save_metrics.py]"]
  node_metrics_read["Metrics reader<br/>[metrics.py]"]
  node_table_setup["Metrics table setup<br/>[create_table.py]"]
  node_sql["PostgreSQL connection<br/>[postgres_sql.py]"]
end

subgraph group_cloud["External services"]
  node_azure_search[("Azure AI Search")]
  node_azure_openai["Azure OpenAI service"]
  node_postgres[("PostgreSQL database")]
end

node_user(("Investor / uploader"))

node_user -->|"uses dashboard"| node_app
node_app -->|"renders"| node_dashboard_ui
node_app -->|"reads metrics"| node_metrics_read
node_app -->|"registers"| node_ingestion_api
node_app -->|"registers"| node_chat_api
node_app -->|"initializes database"| node_sql
node_app -->|"creates tables"| node_table_setup
node_app -->|"creates index"| node_index_setup
node_alternate_app -->|"registers"| node_dashboard_api
node_alternate_app -->|"registers"| node_health_api
node_user -->|"uploads report"| node_ingestion_api
node_ingestion_api -->|"invokes"| node_ingest
node_ingest -->|"converts PDF"| node_pdf_converter
node_ingest -->|"chunks Markdown"| node_chunker
node_ingest -->|"uploads chunks"| node_search_store
node_ingest -->|"extracts metrics"| node_kpi_rag
node_ingest -->|"persists metrics"| node_metrics_save
node_ingest -->|"creates 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 context"| node_search_store
node_kpi_rag -->|"requests structured output"| node_chat_model
node_chat_model -->|"completes prompt"| node_azure_openai
node_user -->|"asks question"| node_chat_api
node_chat_api -->|"retrieves context"| node_search_store
node_chat_api -->|"gets client"| node_chat_model
node_chat_api -->|"requests answer"| node_azure_openai
node_metrics_save -->|"writes KPIs"| node_sql
node_metrics_read -->|"queries metrics"| node_sql
node_table_setup -->|"uses connection"| node_sql
node_sql -->|"connects"| node_postgres
node_dashboard_api -->|"queries metrics"| node_sql
node_user -.->|"requests dashboard data"| node_dashboard_api

click node_app "https://github.com/sandesh-hase/ai-powered-investor-intelligence-platform/blob/main/app.py"
click node_dashboard_ui "https://github.com/sandesh-hase/ai-powered-investor-intelligence-platform/blob/main/templates/dashboard.html"
click node_dashboard_api "https://github.com/sandesh-hase/ai-powered-investor-intelligence-platform/blob/main/routes/dashboard.py"
click node_health_api "https://github.com/sandesh-hase/ai-powered-investor-intelligence-platform/blob/main/routes/health.py"
click node_ingestion_api "https://github.com/sandesh-hase/ai-powered-investor-intelligence-platform/blob/main/routes/ingestion.py"
click node_chat_api "https://github.com/sandesh-hase/ai-powered-investor-intelligence-platform/blob/main/routes/chat.py"
click node_alternate_app "https://github.com/sandesh-hase/ai-powered-investor-intelligence-platform/blob/main/main.py"
click node_pdf_converter "https://github.com/sandesh-hase/ai-powered-investor-intelligence-platform/blob/main/ingestion/pdf_to_markdown.py"
click node_chunker "https://github.com/sandesh-hase/ai-powered-investor-intelligence-platform/blob/main/ingestion/semantic_chunker.py"
click node_ingest "https://github.com/sandesh-hase/ai-powered-investor-intelligence-platform/blob/main/ingestion/ingest_documents.py"
click node_search_store "https://github.com/sandesh-hase/ai-powered-investor-intelligence-platform/blob/main/vectorstore/azure_ai_search.py"
click node_index_setup "https://github.com/sandesh-hase/ai-powered-investor-intelligence-platform/blob/main/vectorstore/create_index.py"
click node_kpi_rag "https://github.com/sandesh-hase/ai-powered-investor-intelligence-platform/blob/main/rag/kpi_extractor_rag.py"
click node_chat_model "https://github.com/sandesh-hase/ai-powered-investor-intelligence-platform/blob/main/llm/azure_openai.py"
click node_metrics_save "https://github.com/sandesh-hase/ai-powered-investor-intelligence-platform/blob/main/database/save_metrics.py"
click node_metrics_read "https://github.com/sandesh-hase/ai-powered-investor-intelligence-platform/blob/main/database/metrics.py"
click node_table_setup "https://github.com/sandesh-hase/ai-powered-investor-intelligence-platform/blob/main/database/create_table.py"
click node_sql "https://github.com/sandesh-hase/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_dashboard_ui,node_dashboard_api,node_health_api,node_ingestion_api,node_chat_api,node_alternate_app toneBlue
class node_pdf_converter,node_chunker,node_ingest toneAmber
class node_search_store,node_index_setup,node_kpi_rag,node_chat_model toneMint
class node_metrics_save,node_metrics_read,node_table_setup,node_sql toneRose
class node_azure_search,node_azure_openai,node_postgres,node_user toneIndigo
```

## Components

### API and presentation

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

### Report ingestion

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

### Search and AI

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

### Persistence

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

### External services

- **Azure AI Search**
- **Azure OpenAI service**
- **PostgreSQL database**

### Other components

- **Investor / uploader**

## Connections

- Investor / uploader → FastAPI application: uses dashboard (evidence: `app.py`)
- FastAPI application → Dashboard template: renders (evidence: `app.py`)
- FastAPI application → Metrics reader: reads metrics (evidence: `app.py`)
- FastAPI application → Upload endpoint: registers (evidence: `app.py`)
- FastAPI application → Chat endpoint: registers (evidence: `app.py`)
- FastAPI application → PostgreSQL connection: initializes database (evidence: `app.py`)
- FastAPI application → Metrics table setup: creates tables (evidence: `app.py`)
- FastAPI application → Search index setup: creates index (evidence: `app.py`)
- Alternate API entry → Dashboard API routes: registers (evidence: `main.py`)
- Alternate API entry → Health routes: registers (evidence: `main.py`)
- Investor / uploader → Upload endpoint: uploads report (evidence: `routes/ingestion.py`)
- Upload endpoint → Document orchestrator: invokes (evidence: `routes/ingestion.py`)
- Document orchestrator → PDF conversion: converts PDF (evidence: `ingestion/ingest_documents.py`)
- Document orchestrator → Semantic chunking: chunks Markdown (evidence: `ingestion/ingest_documents.py`)
- Document orchestrator → Search vector store: uploads chunks (evidence: `ingestion/ingest_documents.py`)
- Document orchestrator → KPI extraction RAG: extracts metrics (evidence: `ingestion/ingest_documents.py`)
- Document orchestrator → KPI persistence: persists metrics (evidence: `ingestion/ingest_documents.py`)
- Document orchestrator → Azure OpenAI service: creates embeddings (evidence: `ingestion/ingest_documents.py`)
- Search vector store → 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 extraction RAG → Search vector store: retrieves context (evidence: `rag/kpi_extractor_rag.py`)
- KPI extraction RAG → Azure OpenAI client: requests structured output (evidence: `rag/kpi_extractor_rag.py`)
- Azure OpenAI client → Azure OpenAI service: completes prompt (evidence: `llm/azure_openai.py`)
- Investor / uploader → Chat endpoint: asks question (evidence: `routes/chat.py`)
- Chat endpoint → Search vector store: retrieves context (evidence: `routes/chat.py`)
- Chat endpoint → Azure OpenAI client: gets client (evidence: `routes/chat.py`)
- Chat endpoint → Azure OpenAI service: requests answer (evidence: `routes/chat.py`)
- KPI persistence → PostgreSQL connection: writes KPIs (evidence: `database/save_metrics.py`)
- Metrics reader → PostgreSQL connection: queries metrics (evidence: `database/metrics.py`)
- Metrics table setup → PostgreSQL connection: uses connection (evidence: `database/create_table.py`)
- PostgreSQL connection → PostgreSQL database: connects (evidence: `database/postgres_sql.py`)
- Dashboard API routes → PostgreSQL connection: queries metrics (evidence: `routes/dashboard.py`)
- Investor / uploader → Dashboard API routes: requests dashboard data
