# yarram-koushik/insightforgeai architecture

> Architecture diagram of the GitHub repository yarram-koushik/insightforgeai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yarram-koushik/insightforgeai
- Repository: https://github.com/yarram-koushik/insightforgeai

## Overview

InsightForgeAI is a business-intelligence assistant that turns uploaded or connected company data and user questions into grounded answers, analytics, and shareable reports. The main workflow runs from the Streamlit UI through ingestion and workspace data into conversational context, intent routing, and specialized agent work; the API provides a second user-facing boundary. Separate product branches cover knowledge-grounded answers, proactive scans, dashboards and exports, and scheduled delivery. The source excerpts confirm selected calls, but not all UI/API wiring or feature internals; uncertain links are omitted.

Main entry points: [`app/agents/orchestrator.py`](https://github.com/yarram-koushik/insightforgeai/blob/main/app/agents/orchestrator.py) (Agent orchestrator), [`app/frontend/app.py`](https://github.com/yarram-koushik/insightforgeai/blob/main/app/frontend/app.py) (Streamlit UI), [`app/core/scheduling.py`](https://github.com/yarram-koushik/insightforgeai/blob/main/app/core/scheduling.py) (Schedules and delivery), [`app/backend/main.py`](https://github.com/yarram-koushik/insightforgeai/blob/main/app/backend/main.py) (FastAPI boundary)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_streamlit["Streamlit UI<br/>[app.py]"]
  node_api["FastAPI boundary<br/>[main.py]"]
end

subgraph group_query["Question and analytics"]
  node_orchestrator["Agent orchestrator<br/>[orchestrator.py]"]
  node_memory["Conversation context<br/>[context_memory.py]"]
  node_router["Intent router<br/>[router.py]"]
  node_sql_agent["Data query agent<br/>[sql_agent.py]"]
  node_analytics_agent["Analytics agent<br/>[analytics_agent.py]"]
  node_insight_agent["Insight agent<br/>[insight_agent.py]"]
  node_forecast_agent["Forecast agent<br/>[forecast_agent.py]"]
end

subgraph group_data["Data and meaning"]
  node_upload["File ingestion<br/>[ingestion.py]"]
  node_workspace[("Workspace data<br/>[data_manager.py]")]
  node_connectors["SQL connectors"]
end

subgraph group_enterprise["Enterprise features"]
  node_knowledge[("Knowledge base<br/>[knowledge_base.py]")]
  node_proactive["Proactive insights<br/>[proactive.py]"]
  node_dashboard[("Dashboards<br/>[dashboard.py]")]
  node_export["Report export<br/>[export.py]"]
  node_scheduling[("Schedules and delivery<br/>[scheduling.py]")]
end

node_user(("Business user"))
node_api_client(("API client"))
node_external_db[("Company databases")]
node_delivery(("Slack or email"))
node_llm{{"LLM providers"}}

node_user -->|"asks or uploads"| node_streamlit
node_api_client -->|"sends requests"| node_api
node_streamlit -->|"reads files"| node_upload
node_upload -->|"loads datasets"| node_workspace
node_streamlit -->|"saves datasets"| node_workspace
node_streamlit -->|"runs questions"| node_orchestrator
node_api -->|"runs questions"| node_orchestrator
node_orchestrator -->|"expands follow-ups"| node_memory
node_orchestrator -->|"classifies intent"| node_router
node_router -.->|"requests classification"| node_llm
node_orchestrator -->|"dispatches data queries"| node_sql_agent
node_orchestrator -->|"dispatches analytics"| node_analytics_agent
node_orchestrator -->|"dispatches insights"| node_insight_agent
node_orchestrator -->|"dispatches forecasts"| node_forecast_agent
node_orchestrator -->|"requests grounded answers"| node_knowledge
node_orchestrator -->|"requests scans"| node_proactive
node_streamlit -->|"scans selected table"| node_proactive
node_connectors -->|"reads schema and tables"| node_external_db
node_streamlit -->|"pins widgets"| node_dashboard
node_streamlit -->|"exports reports"| node_export
node_scheduling -->|"runs scheduled questions"| node_orchestrator
node_scheduling -.->|"delivers results"| node_delivery

click node_streamlit "https://github.com/yarram-koushik/insightforgeai/blob/main/app/frontend/app.py"
click node_api "https://github.com/yarram-koushik/insightforgeai/blob/main/app/backend/main.py"
click node_upload "https://github.com/yarram-koushik/insightforgeai/blob/main/app/core/ingestion.py"
click node_workspace "https://github.com/yarram-koushik/insightforgeai/blob/main/app/core/data_manager.py"
click node_connectors "https://github.com/yarram-koushik/insightforgeai/tree/main/app/core/connectors"
click node_orchestrator "https://github.com/yarram-koushik/insightforgeai/blob/main/app/agents/orchestrator.py"
click node_memory "https://github.com/yarram-koushik/insightforgeai/blob/main/app/core/context_memory.py"
click node_router "https://github.com/yarram-koushik/insightforgeai/blob/main/app/agents/router.py"
click node_sql_agent "https://github.com/yarram-koushik/insightforgeai/blob/main/app/agents/sql_agent.py"
click node_analytics_agent "https://github.com/yarram-koushik/insightforgeai/blob/main/app/agents/analytics_agent.py"
click node_insight_agent "https://github.com/yarram-koushik/insightforgeai/blob/main/app/agents/insight_agent.py"
click node_forecast_agent "https://github.com/yarram-koushik/insightforgeai/blob/main/app/agents/forecast_agent.py"
click node_knowledge "https://github.com/yarram-koushik/insightforgeai/blob/main/app/core/knowledge_base.py"
click node_proactive "https://github.com/yarram-koushik/insightforgeai/blob/main/app/core/proactive.py"
click node_dashboard "https://github.com/yarram-koushik/insightforgeai/blob/main/app/core/dashboard.py"
click node_export "https://github.com/yarram-koushik/insightforgeai/blob/main/app/core/export.py"
click node_scheduling "https://github.com/yarram-koushik/insightforgeai/blob/main/app/core/scheduling.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_streamlit,node_api,node_user,node_api_client toneBlue
class node_orchestrator,node_memory,node_router,node_sql_agent,node_analytics_agent,node_insight_agent,node_forecast_agent,node_external_db toneAmber
class node_upload,node_workspace,node_connectors toneMint
class node_knowledge,node_proactive,node_dashboard,node_export,node_scheduling toneRose
class node_delivery,node_llm toneIndigo
```

## Components

### User experience

- [Streamlit UI](https://github.com/yarram-koushik/insightforgeai/blob/main/app/frontend/app.py): `app/frontend/app.py`
- [FastAPI boundary](https://github.com/yarram-koushik/insightforgeai/blob/main/app/backend/main.py): `app/backend/main.py`

### Question and analytics

- [Agent orchestrator](https://github.com/yarram-koushik/insightforgeai/blob/main/app/agents/orchestrator.py): `app/agents/orchestrator.py`
- [Conversation context](https://github.com/yarram-koushik/insightforgeai/blob/main/app/core/context_memory.py): `app/core/context_memory.py`
- [Intent router](https://github.com/yarram-koushik/insightforgeai/blob/main/app/agents/router.py): `app/agents/router.py`
- [Data query agent](https://github.com/yarram-koushik/insightforgeai/blob/main/app/agents/sql_agent.py): `app/agents/sql_agent.py`
- [Analytics agent](https://github.com/yarram-koushik/insightforgeai/blob/main/app/agents/analytics_agent.py): `app/agents/analytics_agent.py`
- [Insight agent](https://github.com/yarram-koushik/insightforgeai/blob/main/app/agents/insight_agent.py): `app/agents/insight_agent.py`
- [Forecast agent](https://github.com/yarram-koushik/insightforgeai/blob/main/app/agents/forecast_agent.py): `app/agents/forecast_agent.py`

### Data and meaning

- [File ingestion](https://github.com/yarram-koushik/insightforgeai/blob/main/app/core/ingestion.py): `app/core/ingestion.py`
- [Workspace data](https://github.com/yarram-koushik/insightforgeai/blob/main/app/core/data_manager.py): `app/core/data_manager.py`
- [SQL connectors](https://github.com/yarram-koushik/insightforgeai/tree/main/app/core/connectors): `app/core/connectors`

### Enterprise features

- [Knowledge base](https://github.com/yarram-koushik/insightforgeai/blob/main/app/core/knowledge_base.py): `app/core/knowledge_base.py`
- [Proactive insights](https://github.com/yarram-koushik/insightforgeai/blob/main/app/core/proactive.py): `app/core/proactive.py`
- [Dashboards](https://github.com/yarram-koushik/insightforgeai/blob/main/app/core/dashboard.py): `app/core/dashboard.py`
- [Report export](https://github.com/yarram-koushik/insightforgeai/blob/main/app/core/export.py): `app/core/export.py`
- [Schedules and delivery](https://github.com/yarram-koushik/insightforgeai/blob/main/app/core/scheduling.py): `app/core/scheduling.py`

### Other components

- **Business user**
- **API client**
- **Company databases**
- **Slack or email**
- **LLM providers**

## Connections

- Business user → Streamlit UI: asks or uploads
- API client → FastAPI boundary: sends requests
- Streamlit UI → File ingestion: reads files
- File ingestion → Workspace data: loads datasets
- Streamlit UI → Workspace data: saves datasets
- Streamlit UI → Agent orchestrator: runs questions
- FastAPI boundary → Agent orchestrator: runs questions
- Agent orchestrator → Conversation context: expands follow-ups
- Agent orchestrator → Intent router: classifies intent
- Intent router → LLM providers: requests classification
- Agent orchestrator → Data query agent: dispatches data queries
- Agent orchestrator → Analytics agent: dispatches analytics
- Agent orchestrator → Insight agent: dispatches insights
- Agent orchestrator → Forecast agent: dispatches forecasts
- Agent orchestrator → Knowledge base: requests grounded answers
- Agent orchestrator → Proactive insights: requests scans
- Streamlit UI → Proactive insights: scans selected table
- SQL connectors → Company databases: reads schema and tables
- Streamlit UI → Dashboards: pins widgets
- Streamlit UI → Report export: exports reports
- Schedules and delivery → Agent orchestrator: runs scheduled questions
- Schedules and delivery → Slack or email: delivers results