# madhvendra1027/paimaana architecture

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

- Interactive diagram: https://gitdiagram.com/madhvendra1027/paimaana
- Repository: https://github.com/madhvendra1027/paimaana

## Overview

NIRMAAN AI is a synthetic-data infrastructure portfolio monitoring platform. Users explore portfolio KPIs, project dossiers, risk and alerts, geographic concentration, model analytics, and natural-language portfolio queries. The principal runtime flow is browser pages to Next.js API handlers and services, which read project, prediction, and alert records; the ML service is an optional evaluation/training path rather than a prerequisite to the frontend. The tree omits the Prisma schema/database files, so the documented SQLite store is shown without a repository path; unsampled capability links are omitted or marked unverified.

Main entry points: [`frontend/src/app/api/analytics/route.ts`](https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/app/api/analytics/route.ts) (Analytics endpoint), [`frontend/src/lib/services/predictionService.ts`](https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/lib/services/predictionService.ts) (Current predictions), [`frontend/src/lib/services/priorityEngine.ts`](https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/lib/services/priorityEngine.ts) (Priority scoring), [`frontend/src/app/api/states/route.ts`](https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/app/api/states/route.ts) (State aggregation endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Portfolio experience"]
  node_dashboard["Portfolio dashboard<br/>[page.tsx]"]
  node_directory["Project directory<br/>[page.tsx]"]
  node_dossier["Project dossier<br/>[page.tsx]"]
  node_alertsui["Alerts workspace<br/>[page.tsx]"]
  node_analyticsui["Analytics workspace<br/>[page.tsx]"]
  node_mapui["State risk map<br/>[page.tsx]"]
  node_assistantui["AI Officer<br/>[page.tsx]"]
end

subgraph group_api["Application API"]
  node_kpiapi["KPI endpoint<br/>[route.ts]"]
  node_projectapi["Project endpoints<br/>[route.ts]"]
  node_detailapi["Project detail endpoint<br/>[route.ts]"]
  node_alertapi["Alert endpoint<br/>[route.ts]"]
  node_stateapi["State aggregation endpoint<br/>[route.ts]"]
  node_analyticsapi["Analytics endpoint<br/>[route.ts]"]
  node_chatapi["Portfolio query endpoint<br/>[route.ts]"]
end

subgraph group_intelligence["Risk intelligence"]
  node_portfolio["Portfolio aggregation"]
  node_predictions["Current predictions"]
  node_priority["Priority scoring<br/>[priorityEngine.ts]"]
  node_modelservice["Model artifact reader<br/>[modelService.ts]"]
end

subgraph group_ml["ML evaluation"]
  node_mlapi["ML prediction API<br/>[main.py]"]
  node_features["Feature engineering"]
  node_training["Ensemble training"]
  node_mlartifact["Evaluation artifact"]
end

subgraph group_data["Data foundation"]
  node_generator["Synthetic data generator"]
  node_seeder["Database seeder<br/>[seed_db.py]"]
  node_database[("SQLite project store")]
end

node_browser(("Portfolio user"))

node_browser -->|"opens"| node_dashboard
node_browser -->|"browses"| node_directory
node_browser -->|"opens"| node_dossier
node_browser -->|"reviews"| node_alertsui
node_browser -->|"compares"| node_analyticsui
node_browser -->|"explores"| node_mapui
node_browser -->|"queries"| node_assistantui
node_projectapi -->|"queries"| node_database
node_chatapi -->|"queries"| node_database
node_stateapi -->|"aggregates"| node_database
node_stateapi -->|"resolves risk"| node_predictions
node_analyticsapi -->|"aggregates"| node_database
node_analyticsapi -->|"reads metrics"| node_modelservice
node_analyticsapi -.->|"requests features"| node_mlapi
node_portfolio -->|"resolves risk"| node_predictions
node_portfolio -->|"selects priorities"| node_priority
node_priority -->|"loads predictions"| node_predictions
node_priority -->|"reads projects and alerts"| node_database
node_predictions -->|"reads latest records"| node_database
node_generator -->|"supplies synthetic data"| node_seeder
node_seeder -->|"seeds"| node_database
node_training -->|"uses features"| node_features
node_training -->|"writes evaluation"| node_mlartifact
node_mlapi -.->|"engineers inputs"| node_features
node_modelservice -->|"reads artifact"| node_mlartifact
node_dashboard -.->|"loads KPIs"| node_kpiapi
node_directory -.->|"fetches projects"| node_projectapi
node_dossier -.->|"loads dossier"| node_detailapi
node_alertsui -.->|"loads alerts"| node_alertapi
node_mapui -.->|"loads state data"| node_stateapi
node_assistantui -.->|"submits query"| node_chatapi
node_analyticsui -.->|"loads analytics"| node_analyticsapi

click node_dashboard "https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/app/page.tsx"
click node_directory "https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/app/projects/page.tsx"
click node_dossier "https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/app/projects/%5Bid%5D/page.tsx"
click node_alertsui "https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/app/alerts/page.tsx"
click node_analyticsui "https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/app/analytics/page.tsx"
click node_mapui "https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/app/map/page.tsx"
click node_assistantui "https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/app/assistant/page.tsx"
click node_kpiapi "https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/app/api/kpi/route.ts"
click node_projectapi "https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/app/api/projects/route.ts"
click node_detailapi "https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/app/api/projects/%5Bid%5D/route.ts"
click node_alertapi "https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/app/api/alerts/route.ts"
click node_stateapi "https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/app/api/states/route.ts"
click node_analyticsapi "https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/app/api/analytics/route.ts"
click node_chatapi "https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/app/api/chat/route.ts"
click node_portfolio "https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/lib/services/portfolioService.ts"
click node_predictions "https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/lib/services/predictionService.ts"
click node_priority "https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/lib/services/priorityEngine.ts"
click node_modelservice "https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/lib/services/modelService.ts"
click node_mlapi "https://github.com/madhvendra1027/paimaana/blob/main/ml-service/app/main.py"
click node_features "https://github.com/madhvendra1027/paimaana/blob/main/ml-service/app/pipeline/feature_engineering.py"
click node_training "https://github.com/madhvendra1027/paimaana/blob/main/ml-service/app/pipeline/training_pipeline.py"
click node_generator "https://github.com/madhvendra1027/paimaana/blob/main/data-generator/generate_projects.py"
click node_seeder "https://github.com/madhvendra1027/paimaana/blob/main/data-generator/seed_db.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_dashboard,node_directory,node_dossier,node_alertsui,node_analyticsui,node_mapui,node_assistantui,node_browser toneBlue
class node_kpiapi,node_projectapi,node_detailapi,node_alertapi,node_stateapi,node_analyticsapi,node_chatapi toneAmber
class node_portfolio,node_predictions,node_priority,node_modelservice toneMint
class node_mlapi,node_features,node_training,node_mlartifact toneRose
class node_generator,node_seeder,node_database toneIndigo
```

## Components

### Portfolio experience

- [Portfolio dashboard](https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Project directory](https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/app/projects/page.tsx): `frontend/src/app/projects/page.tsx`
- [Project dossier](https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/app/projects/%5Bid%5D/page.tsx): `frontend/src/app/projects/[id]/page.tsx`
- [Alerts workspace](https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/app/alerts/page.tsx): `frontend/src/app/alerts/page.tsx`
- [Analytics workspace](https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/app/analytics/page.tsx): `frontend/src/app/analytics/page.tsx`
- [State risk map](https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/app/map/page.tsx): `frontend/src/app/map/page.tsx`
- [AI Officer](https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/app/assistant/page.tsx): `frontend/src/app/assistant/page.tsx`

### Application API

- [KPI endpoint](https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/app/api/kpi/route.ts): `frontend/src/app/api/kpi/route.ts`
- [Project endpoints](https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/app/api/projects/route.ts): `frontend/src/app/api/projects/route.ts`
- [Project detail endpoint](https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/app/api/projects/%5Bid%5D/route.ts): `frontend/src/app/api/projects/[id]/route.ts`
- [Alert endpoint](https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/app/api/alerts/route.ts): `frontend/src/app/api/alerts/route.ts`
- [State aggregation endpoint](https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/app/api/states/route.ts): `frontend/src/app/api/states/route.ts`
- [Analytics endpoint](https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/app/api/analytics/route.ts): `frontend/src/app/api/analytics/route.ts`
- [Portfolio query endpoint](https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/app/api/chat/route.ts): `frontend/src/app/api/chat/route.ts`

### Risk intelligence

- [Portfolio aggregation](https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/lib/services/portfolioService.ts): `frontend/src/lib/services/portfolioService.ts`
- [Current predictions](https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/lib/services/predictionService.ts): `frontend/src/lib/services/predictionService.ts`
- [Priority scoring](https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/lib/services/priorityEngine.ts): `frontend/src/lib/services/priorityEngine.ts`
- [Model artifact reader](https://github.com/madhvendra1027/paimaana/blob/main/frontend/src/lib/services/modelService.ts): `frontend/src/lib/services/modelService.ts`

### ML evaluation

- [ML prediction API](https://github.com/madhvendra1027/paimaana/blob/main/ml-service/app/main.py): `ml-service/app/main.py`
- [Feature engineering](https://github.com/madhvendra1027/paimaana/blob/main/ml-service/app/pipeline/feature_engineering.py): `ml-service/app/pipeline/feature_engineering.py`
- [Ensemble training](https://github.com/madhvendra1027/paimaana/blob/main/ml-service/app/pipeline/training_pipeline.py): `ml-service/app/pipeline/training_pipeline.py`
- **Evaluation artifact**

### Data foundation

- [Synthetic data generator](https://github.com/madhvendra1027/paimaana/blob/main/data-generator/generate_projects.py): `data-generator/generate_projects.py`
- [Database seeder](https://github.com/madhvendra1027/paimaana/blob/main/data-generator/seed_db.py): `data-generator/seed_db.py`
- **SQLite project store**

### Other components

- **Portfolio user**

## Connections

- Portfolio user → Portfolio dashboard: opens (evidence: `README.md`)
- Portfolio user → Project directory: browses (evidence: `README.md`)
- Portfolio user → Project dossier: opens (evidence: `README.md`)
- Portfolio user → Alerts workspace: reviews (evidence: `README.md`)
- Portfolio user → Analytics workspace: compares (evidence: `README.md`)
- Portfolio user → State risk map: explores (evidence: `README.md`)
- Portfolio user → AI Officer: queries (evidence: `README.md`)
- Project endpoints → SQLite project store: queries (evidence: `frontend/src/app/api/projects/route.ts`)
- Portfolio query endpoint → SQLite project store: queries (evidence: `frontend/src/app/api/chat/route.ts`)
- State aggregation endpoint → SQLite project store: aggregates (evidence: `frontend/src/app/api/states/route.ts`)
- State aggregation endpoint → Current predictions: resolves risk (evidence: `frontend/src/app/api/states/route.ts`)
- Analytics endpoint → SQLite project store: aggregates (evidence: `frontend/src/app/api/analytics/route.ts`)
- Analytics endpoint → Model artifact reader: reads metrics (evidence: `frontend/src/app/api/analytics/route.ts`)
- Analytics endpoint → ML prediction API: requests features (evidence: `frontend/src/app/api/analytics/route.ts`)
- Portfolio aggregation → Current predictions: resolves risk (evidence: `frontend/src/lib/services/portfolioService.ts`)
- Portfolio aggregation → Priority scoring: selects priorities (evidence: `frontend/src/lib/services/portfolioService.ts`)
- Priority scoring → Current predictions: loads predictions (evidence: `frontend/src/lib/services/priorityEngine.ts`)
- Priority scoring → SQLite project store: reads projects and alerts (evidence: `frontend/src/lib/services/priorityEngine.ts`)
- Current predictions → SQLite project store: reads latest records (evidence: `frontend/src/lib/services/predictionService.ts`)
- Synthetic data generator → Database seeder: supplies synthetic data (evidence: `README.md`)
- Database seeder → SQLite project store: seeds (evidence: `README.md`)
- Ensemble training → Feature engineering: uses features (evidence: `ml-service/app/pipeline/training_pipeline.py`)
- Ensemble training → Evaluation artifact: writes evaluation (evidence: `README.md`)
- ML prediction API → Feature engineering: engineers inputs
- Model artifact reader → Evaluation artifact: reads artifact (evidence: `README.md`)
- Portfolio dashboard → KPI endpoint: loads KPIs
- Project directory → Project endpoints: fetches projects
- Project dossier → Project detail endpoint: loads dossier
- Alerts workspace → Alert endpoint: loads alerts
- State risk map → State aggregation endpoint: loads state data
- AI Officer → Portfolio query endpoint: submits query
- Analytics workspace → Analytics endpoint: loads analytics