# madhvendra1027/arthalens architecture

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

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

## Overview

ArthaLens is an India macroeconomic intelligence platform: users explore official economic series and provenance, compare methodology, inspect diagnostics, and ask citation-grounded research questions. The principal data path is source adapters through validation and ingestion into persistent data, then API domain services to the web experience. The README documents additional capabilities such as forecasts and sovereign ratings. Sampled source confirms selected service and storage calls; unsampled wiring is omitted where it cannot be established.

Main entry points: [`services/api/src/main/java/com/arthalens/api/ApiApplication.java`](https://github.com/madhvendra1027/arthalens/blob/main/services/api/src/main/java/com/arthalens/api/ApiApplication.java) (Spring REST API), [`services/ingestion/ingestion/pipeline.py`](https://github.com/madhvendra1027/arthalens/blob/main/services/ingestion/ingestion/pipeline.py) (Validate and ingest), [`apps/web/src/app`](https://github.com/madhvendra1027/arthalens/tree/main/apps/web/src/app) (Next.js experience), [`services/api/src/main/java/com/arthalens/api/domain/gdp/service/GdpService.java`](https://github.com/madhvendra1027/arthalens/blob/main/services/api/src/main/java/com/arthalens/api/domain/gdp/service/GdpService.java) (GDP and revisions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_web["Next.js experience"]
  node_webdata["Charts and pages"]
  node_authclient["Auth provider<br/>[useAuth.tsx]"]
end

subgraph group_ingestion["Data ingestion"]
  node_adapters["Official source adapters"]
  node_pipeline["Validate and ingest<br/>[pipeline.py]"]
  node_run["Run provenance<br/>[run_manager.py]"]
  node_quarantine["Invalid-row quarantine<br/>[quarantine.py]"]
end

subgraph group_api["REST API"]
  node_api["Spring REST API"]
  node_dashboard["Dashboard metrics"]
  node_gdp["GDP and revisions<br/>[GdpService.java]"]
  node_deflators["Deflator series"]
  node_methodology["Methodology comparison"]
  node_indicators["Economic indicators"]
  node_ratings["Sovereign ratings"]
  node_sources["Source provenance<br/>[SourceService.java]"]
  node_aiorchestrator["AI orchestration"]
end

subgraph group_intelligence["Research intelligence"]
  node_rag["Citation-grounded RAG"]
  node_ml["ML diagnostics and forecasts"]
end

subgraph group_identity["User identity"]
  node_authroutes["Auth routes"]
  node_redis[("Redis sessions<br/>[redis.ts]")]
end

node_researcher(("Researcher"))
node_postgres[("Macroeconomic data")]

node_researcher -->|"explores"| node_web
node_web -->|"renders"| node_webdata
node_web -->|"requests data"| node_api
node_authclient -->|"calls auth"| node_authroutes
node_authroutes -->|"reads and writes"| node_redis
node_adapters -->|"provides source data"| node_pipeline
node_pipeline -->|"updates run"| node_run
node_pipeline -->|"quarantines invalid rows"| node_quarantine
node_pipeline -->|"upserts valid rows"| node_postgres
node_api -->|"dispatches"| node_dashboard
node_api -->|"dispatches"| node_gdp
node_api -->|"dispatches"| node_deflators
node_api -->|"dispatches"| node_methodology
node_api -->|"dispatches"| node_indicators
node_api -->|"dispatches"| node_ratings
node_api -->|"dispatches"| node_sources
node_api -->|"dispatches"| node_aiorchestrator
node_gdp -->|"queries observations"| node_postgres
node_deflators -->|"queries series"| node_postgres
node_methodology -->|"queries versions"| node_postgres
node_indicators -->|"queries indexes"| node_postgres
node_ratings -->|"queries ratings"| node_postgres
node_sources -->|"queries sources"| node_postgres
node_aiorchestrator -->|"posts query"| node_rag

click node_web "https://github.com/madhvendra1027/arthalens/tree/main/apps/web/src/app"
click node_webdata "https://github.com/madhvendra1027/arthalens/tree/main/apps/web/src/components"
click node_authclient "https://github.com/madhvendra1027/arthalens/blob/main/apps/web/src/hooks/useAuth.tsx"
click node_authroutes "https://github.com/madhvendra1027/arthalens/tree/main/apps/web/src/app/api/auth"
click node_redis "https://github.com/madhvendra1027/arthalens/blob/main/apps/web/src/lib/redis.ts"
click node_adapters "https://github.com/madhvendra1027/arthalens/tree/main/services/ingestion/ingestion/adapters"
click node_pipeline "https://github.com/madhvendra1027/arthalens/blob/main/services/ingestion/ingestion/pipeline.py"
click node_run "https://github.com/madhvendra1027/arthalens/blob/main/services/ingestion/ingestion/core/run_manager.py"
click node_quarantine "https://github.com/madhvendra1027/arthalens/blob/main/services/ingestion/ingestion/core/quarantine.py"
click node_api "https://github.com/madhvendra1027/arthalens/blob/main/services/api/src/main/java/com/arthalens/api/ApiApplication.java"
click node_dashboard "https://github.com/madhvendra1027/arthalens/blob/main/services/api/src/main/java/com/arthalens/api/domain/dashboard/service/DashboardService.java"
click node_gdp "https://github.com/madhvendra1027/arthalens/blob/main/services/api/src/main/java/com/arthalens/api/domain/gdp/service/GdpService.java"
click node_deflators "https://github.com/madhvendra1027/arthalens/blob/main/services/api/src/main/java/com/arthalens/api/domain/deflator/service/DeflatorService.java"
click node_methodology "https://github.com/madhvendra1027/arthalens/blob/main/services/api/src/main/java/com/arthalens/api/domain/methodology/service/MethodologyService.java"
click node_indicators "https://github.com/madhvendra1027/arthalens/blob/main/services/api/src/main/java/com/arthalens/api/domain/indicators/service/IndicatorService.java"
click node_ratings "https://github.com/madhvendra1027/arthalens/blob/main/services/api/src/main/java/com/arthalens/api/domain/ratings/service/RatingsService.java"
click node_sources "https://github.com/madhvendra1027/arthalens/blob/main/services/api/src/main/java/com/arthalens/api/domain/sources/service/SourceService.java"
click node_aiorchestrator "https://github.com/madhvendra1027/arthalens/blob/main/services/api/src/main/java/com/arthalens/api/domain/ai/service/AiOrchestrationService.java"
click node_rag "https://github.com/madhvendra1027/arthalens/tree/main/services/ai/rag"
click node_ml "https://github.com/madhvendra1027/arthalens/tree/main/services/ml/ml"

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_web,node_webdata,node_authclient toneBlue
class node_adapters,node_pipeline,node_run,node_quarantine,node_postgres toneAmber
class node_api,node_dashboard,node_gdp,node_deflators,node_methodology,node_indicators,node_ratings,node_sources,node_aiorchestrator toneMint
class node_rag,node_ml toneRose
class node_authroutes,node_redis,node_researcher toneIndigo
```

## Components

### Web experience

- [Next.js experience](https://github.com/madhvendra1027/arthalens/tree/main/apps/web/src/app): `apps/web/src/app`
- [Charts and pages](https://github.com/madhvendra1027/arthalens/tree/main/apps/web/src/components): `apps/web/src/components`
- [Auth provider](https://github.com/madhvendra1027/arthalens/blob/main/apps/web/src/hooks/useAuth.tsx): `apps/web/src/hooks/useAuth.tsx`

### Data ingestion

- [Official source adapters](https://github.com/madhvendra1027/arthalens/tree/main/services/ingestion/ingestion/adapters): `services/ingestion/ingestion/adapters`
- [Validate and ingest](https://github.com/madhvendra1027/arthalens/blob/main/services/ingestion/ingestion/pipeline.py): `services/ingestion/ingestion/pipeline.py`
- [Run provenance](https://github.com/madhvendra1027/arthalens/blob/main/services/ingestion/ingestion/core/run_manager.py): `services/ingestion/ingestion/core/run_manager.py`
- [Invalid-row quarantine](https://github.com/madhvendra1027/arthalens/blob/main/services/ingestion/ingestion/core/quarantine.py): `services/ingestion/ingestion/core/quarantine.py`

### REST API

- [Spring REST API](https://github.com/madhvendra1027/arthalens/blob/main/services/api/src/main/java/com/arthalens/api/ApiApplication.java): `services/api/src/main/java/com/arthalens/api/ApiApplication.java`
- [Dashboard metrics](https://github.com/madhvendra1027/arthalens/blob/main/services/api/src/main/java/com/arthalens/api/domain/dashboard/service/DashboardService.java): `services/api/src/main/java/com/arthalens/api/domain/dashboard/service/DashboardService.java`
- [GDP and revisions](https://github.com/madhvendra1027/arthalens/blob/main/services/api/src/main/java/com/arthalens/api/domain/gdp/service/GdpService.java): `services/api/src/main/java/com/arthalens/api/domain/gdp/service/GdpService.java`
- [Deflator series](https://github.com/madhvendra1027/arthalens/blob/main/services/api/src/main/java/com/arthalens/api/domain/deflator/service/DeflatorService.java): `services/api/src/main/java/com/arthalens/api/domain/deflator/service/DeflatorService.java`
- [Methodology comparison](https://github.com/madhvendra1027/arthalens/blob/main/services/api/src/main/java/com/arthalens/api/domain/methodology/service/MethodologyService.java): `services/api/src/main/java/com/arthalens/api/domain/methodology/service/MethodologyService.java`
- [Economic indicators](https://github.com/madhvendra1027/arthalens/blob/main/services/api/src/main/java/com/arthalens/api/domain/indicators/service/IndicatorService.java): `services/api/src/main/java/com/arthalens/api/domain/indicators/service/IndicatorService.java`
- [Sovereign ratings](https://github.com/madhvendra1027/arthalens/blob/main/services/api/src/main/java/com/arthalens/api/domain/ratings/service/RatingsService.java): `services/api/src/main/java/com/arthalens/api/domain/ratings/service/RatingsService.java`
- [Source provenance](https://github.com/madhvendra1027/arthalens/blob/main/services/api/src/main/java/com/arthalens/api/domain/sources/service/SourceService.java): `services/api/src/main/java/com/arthalens/api/domain/sources/service/SourceService.java`
- [AI orchestration](https://github.com/madhvendra1027/arthalens/blob/main/services/api/src/main/java/com/arthalens/api/domain/ai/service/AiOrchestrationService.java): `services/api/src/main/java/com/arthalens/api/domain/ai/service/AiOrchestrationService.java`

### Research intelligence

- [Citation-grounded RAG](https://github.com/madhvendra1027/arthalens/tree/main/services/ai/rag): `services/ai/rag`
- [ML diagnostics and forecasts](https://github.com/madhvendra1027/arthalens/tree/main/services/ml/ml): `services/ml/ml`

### User identity

- [Auth routes](https://github.com/madhvendra1027/arthalens/tree/main/apps/web/src/app/api/auth): `apps/web/src/app/api/auth`
- [Redis sessions](https://github.com/madhvendra1027/arthalens/blob/main/apps/web/src/lib/redis.ts): `apps/web/src/lib/redis.ts`

### Other components

- **Researcher**
- **Macroeconomic data**

## Connections

- Researcher → Next.js experience: explores
- Next.js experience → Charts and pages: renders
- Next.js experience → Spring REST API: requests data
- Auth provider → Auth routes: calls auth
- Auth routes → Redis sessions: reads and writes
- Official source adapters → Validate and ingest: provides source data
- Validate and ingest → Run provenance: updates run
- Validate and ingest → Invalid-row quarantine: quarantines invalid rows
- Validate and ingest → Macroeconomic data: upserts valid rows
- Spring REST API → Dashboard metrics: dispatches
- Spring REST API → GDP and revisions: dispatches
- Spring REST API → Deflator series: dispatches
- Spring REST API → Methodology comparison: dispatches
- Spring REST API → Economic indicators: dispatches
- Spring REST API → Sovereign ratings: dispatches
- Spring REST API → Source provenance: dispatches
- Spring REST API → AI orchestration: dispatches
- GDP and revisions → Macroeconomic data: queries observations
- Deflator series → Macroeconomic data: queries series
- Methodology comparison → Macroeconomic data: queries versions
- Economic indicators → Macroeconomic data: queries indexes
- Sovereign ratings → Macroeconomic data: queries ratings
- Source provenance → Macroeconomic data: queries sources
- AI orchestration → Citation-grounded RAG: posts query