# kotianprakash/ai-portfolio-analytics architecture

> Architecture diagram of the GitHub repository kotianprakash/ai-portfolio-analytics, 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/kotianprakash/ai-portfolio-analytics
- Repository: https://github.com/kotianprakash/ai-portfolio-analytics

## Overview

This is a FastAPI investor-intelligence backend. Its main user-to-result workflow accepts an annual-report PDF, converts it to Markdown, chunks it, indexes it in Azure AI Search, extracts financial KPIs with Azure OpenAI, and stores those KPIs in PostgreSQL; users can also query indexed reports through RAG chat and view stored metrics in a dashboard. The graph includes the separately defined dashboard/health API as well. Edges reflect the shown calls or README capabilities; some UI and service details are documented but not implemented in the sampled excerpts.

Main entry points: [`app.py`](https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/app.py) (FastAPI App), [`ingestion/ingest_documents.py`](https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/ingestion/ingest_documents.py) (Ingestion Orchestrator), [`database/postgres_sql.py`](https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/database/postgres_sql.py) (PostgreSQL Access), [`routes/chat.py`](https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/routes/chat.py) (Chat Route)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and Dashboard"]
  node_app["FastAPI App<br/>[app.py]"]
  node_api_main["Dashboard API<br/>[main.py]"]
  node_upload_route["Upload Route<br/>[ingestion.py]"]
  node_chat_route["Chat Route<br/>[chat.py]"]
  node_dashboard_route["Dashboard Route<br/>[dashboard.py]"]
  node_health_route["Health Route<br/>[health.py]"]
  node_dashboard_ui["Dashboard UI<br/>[dashboard.html]"]
end

subgraph group_ingestion["Report Ingestion"]
  node_ingestor["Ingestion Orchestrator"]
  node_pdf_converter["PDF Converter<br/>[pdf_to_markdown.py]"]
  node_chunker["Semantic Chunker"]
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["OpenAI Client<br/>[azure_openai.py]"]
end

subgraph group_storage["Persistence"]
  node_metrics["Metrics Query<br/>[metrics.py]"]
  node_save_metrics["Metric Persistence<br/>[save_metrics.py]"]
  node_table_setup["Table Setup<br/>[create_table.py]"]
  node_postgres["PostgreSQL Access<br/>[postgres_sql.py]"]
end

node_user(("Investor"))
node_azure_search[("Azure AI Search")]
node_azure_openai["Azure OpenAI"]
node_postgres_db[("PostgreSQL")]

node_user -->|"uploads PDF"| node_upload_route
node_app -->|"registers route"| node_upload_route
node_upload_route -->|"ingests document"| node_ingestor
node_ingestor -->|"converts PDF"| node_pdf_converter
node_ingestor -->|"chunks Markdown"| node_chunker
node_ingestor -->|"uploads chunks"| node_search_store
node_search_store -->|"indexes and searches"| node_azure_search
node_app -->|"creates index"| node_index_setup
node_index_setup -->|"configures index"| node_azure_search
node_ingestor -->|"extracts KPIs"| node_kpi_rag
node_kpi_rag -->|"retrieves context"| node_search_store
node_kpi_rag -->|"requests structured output"| node_chat_model
node_chat_model -->|"calls model"| node_azure_openai
node_ingestor -->|"persists extracted KPIs"| node_save_metrics
node_save_metrics -->|"writes metrics"| node_postgres
node_postgres -->|"connects to"| node_postgres_db
node_user -->|"asks question"| node_chat_route
node_app -->|"registers route"| node_chat_route
node_chat_route -->|"retrieves report context"| node_search_store
node_chat_route -->|"gets model client"| node_chat_model
node_user -.->|"views metrics"| node_dashboard_ui
node_app -->|"renders dashboard"| node_dashboard_ui
node_app -->|"loads metrics"| node_metrics
node_metrics -->|"queries database"| node_postgres
node_user -->|"requests API"| node_api_main
node_api_main -->|"registers route"| node_dashboard_route
node_api_main -->|"registers route"| node_health_route
node_dashboard_route -->|"reads metrics"| node_postgres
node_app -->|"creates database"| node_postgres
node_app -->|"creates tables"| node_table_setup
node_table_setup -->|"uses database access"| node_postgres

click node_app "https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/app.py"
click node_api_main "https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/main.py"
click node_upload_route "https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/routes/ingestion.py"
click node_chat_route "https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/routes/chat.py"
click node_dashboard_route "https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/routes/dashboard.py"
click node_health_route "https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/routes/health.py"
click node_dashboard_ui "https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/templates/dashboard.html"
click node_ingestor "https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/ingestion/ingest_documents.py"
click node_pdf_converter "https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/ingestion/pdf_to_markdown.py"
click node_chunker "https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/ingestion/semantic_chunker.py"
click node_search_store "https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/vectorstore/azure_ai_search.py"
click node_index_setup "https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/vectorstore/create_index.py"
click node_kpi_rag "https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/rag/kpi_extractor_rag.py"
click node_chat_model "https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/llm/azure_openai.py"
click node_metrics "https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/database/metrics.py"
click node_save_metrics "https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/database/save_metrics.py"
click node_table_setup "https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/database/create_table.py"
click node_postgres "https://github.com/kotianprakash/ai-portfolio-analytics/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_api_main,node_upload_route,node_chat_route,node_dashboard_route,node_health_route,node_dashboard_ui toneBlue
class node_ingestor,node_pdf_converter,node_chunker,node_azure_search,node_postgres_db toneAmber
class node_search_store,node_index_setup,node_kpi_rag,node_chat_model toneMint
class node_metrics,node_save_metrics,node_table_setup,node_postgres toneRose
class node_user,node_azure_openai toneIndigo
```

## Components

### API and Dashboard

- [FastAPI App](https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/app.py): `app.py`
- [Dashboard API](https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/main.py): `main.py`
- [Upload Route](https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/routes/ingestion.py): `routes/ingestion.py`
- [Chat Route](https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/routes/chat.py): `routes/chat.py`
- [Dashboard Route](https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/routes/dashboard.py): `routes/dashboard.py`
- [Health Route](https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/routes/health.py): `routes/health.py`
- [Dashboard UI](https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/templates/dashboard.html): `templates/dashboard.html`

### Report Ingestion

- [Ingestion Orchestrator](https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/ingestion/ingest_documents.py): `ingestion/ingest_documents.py`
- [PDF Converter](https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/ingestion/pdf_to_markdown.py): `ingestion/pdf_to_markdown.py`
- [Semantic Chunker](https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/ingestion/semantic_chunker.py): `ingestion/semantic_chunker.py`

### Search and AI

- [Search Vector Store](https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/vectorstore/azure_ai_search.py): `vectorstore/azure_ai_search.py`
- [Search Index Setup](https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/vectorstore/create_index.py): `vectorstore/create_index.py`
- [KPI Extraction RAG](https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/rag/kpi_extractor_rag.py): `rag/kpi_extractor_rag.py`
- [OpenAI Client](https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/llm/azure_openai.py): `llm/azure_openai.py`

### Persistence

- [Metrics Query](https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/database/metrics.py): `database/metrics.py`
- [Metric Persistence](https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/database/save_metrics.py): `database/save_metrics.py`
- [Table Setup](https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/database/create_table.py): `database/create_table.py`
- [PostgreSQL Access](https://github.com/kotianprakash/ai-portfolio-analytics/blob/main/database/postgres_sql.py): `database/postgres_sql.py`

### Other components

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

## Connections

- Investor → Upload Route: uploads PDF (evidence: `routes/ingestion.py`)
- FastAPI App → Upload Route: registers route (evidence: `app.py`)
- Upload Route → Ingestion Orchestrator: ingests document (evidence: `routes/ingestion.py`)
- Ingestion Orchestrator → PDF Converter: converts PDF (evidence: `ingestion/ingest_documents.py`)
- Ingestion Orchestrator → Semantic Chunker: chunks Markdown (evidence: `ingestion/ingest_documents.py`)
- Ingestion Orchestrator → Search Vector Store: uploads chunks (evidence: `ingestion/ingest_documents.py`)
- Search Vector Store → Azure AI Search: indexes and searches (evidence: `vectorstore/azure_ai_search.py`)
- FastAPI App → Search Index Setup: creates index (evidence: `app.py`)
- Search Index Setup → Azure AI Search: configures index (evidence: `vectorstore/create_index.py`)
- Ingestion Orchestrator → KPI Extraction RAG: extracts KPIs (evidence: `ingestion/ingest_documents.py`)
- KPI Extraction RAG → Search Vector Store: retrieves context (evidence: `rag/kpi_extractor_rag.py`)
- KPI Extraction RAG → OpenAI Client: requests structured output (evidence: `rag/kpi_extractor_rag.py`)
- OpenAI Client → Azure OpenAI: calls model (evidence: `llm/azure_openai.py`)
- Ingestion Orchestrator → Metric Persistence: persists extracted KPIs (evidence: `ingestion/ingest_documents.py`)
- Metric Persistence → PostgreSQL Access: writes metrics (evidence: `database/save_metrics.py`)
- PostgreSQL Access → PostgreSQL: connects to (evidence: `database/postgres_sql.py`)
- Investor → Chat Route: asks question (evidence: `routes/chat.py`)
- FastAPI App → Chat Route: registers route (evidence: `app.py`)
- Chat Route → Search Vector Store: retrieves report context (evidence: `routes/chat.py`)
- Chat Route → OpenAI Client: gets model client (evidence: `routes/chat.py`)
- Investor → Dashboard UI: views metrics (evidence: `README.md`)
- FastAPI App → Dashboard UI: renders dashboard (evidence: `app.py`)
- FastAPI App → Metrics Query: loads metrics (evidence: `app.py`)
- Metrics Query → PostgreSQL Access: queries database (evidence: `database/metrics.py`)
- Investor → Dashboard API: requests API (evidence: `main.py`)
- Dashboard API → Dashboard Route: registers route (evidence: `main.py`)
- Dashboard API → Health Route: registers route (evidence: `main.py`)
- Dashboard Route → PostgreSQL Access: reads metrics (evidence: `routes/dashboard.py`)
- FastAPI App → PostgreSQL Access: creates database (evidence: `app.py`)
- FastAPI App → Table Setup: creates tables (evidence: `app.py`)
- Table Setup → PostgreSQL Access: uses database access (evidence: `database/create_table.py`)
