# dhanush342/atlas architecture

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

- Interactive diagram: https://gitdiagram.com/dhanush342/atlas
- Repository: https://github.com/dhanush342/atlas

## Overview

1. **What this system is**
   - Bharat Tech Atlas is a two-tier product: a **React/Vite frontend** for interactive map exploration and a **FastAPI backend** that serves entity search, analytics, chat, ML, ETL, and map tiles.
   - The repo is structured so the backend owns data access and domain logic, while the frontend focuses on visualization and user interaction.

2. **User-facing frontend**
   - `frontend/src/App.jsx` composes the main UI: map, sidebar, stats, analytics, entity detail, search, and chat.
   - Key components include `StartupMap`, `SearchBar`, `Sidebar`, `StatsBar`, `AnalyticsPanel`, `MLInsightsPanel`, `EntityDetail`, and `ChatWidget`.
   - Hooks such as `useMapData`, `useEntityDetail`, `useFilters`, and `useSupabase` separate data-fetching and live-update concerns from presentation.

3. **Backend application boundary**
   - `backend/main.py` is the FastAPI entrypoint that wires routes, middleware, security controls, and health/metrics endpoints.
   - The backend is split by capability rather than by CRUD object, which is why there are distinct modules for chat, ETL, ML, analytics, matching, geocoding, and caching.
   - `backend/routes/*` is the public API surface; the rest of `backend/*` contains the underlying service logic.

4. **Core data layer**
   - The primary entity model is centered on startup ecosystem records such as startups, investors, mentors, incubators, accelerators, corporates, and government bodies.
   - The system supports both **local SQLite** for simpler deployments and **Supabase PostgreSQL + PostGIS** for the full real-time, spatially indexed deployment.
   - `backend/database.py` and `backend/supabase_client.py` indicate the repo can switch between local database access and cloud-backed Supabase access.

5. **Spatial and map-serving path**
   - `backend/routes/mvt_routes.py` serves **Mapbox Vector Tiles** for map rendering, which is the high-performance path for dense geospatial visualization.
   - PostGIS is used for viewport and radius queries, while `geom` plus a GIST index support spatial lookups.
   - The frontend map is designed to request lightweight tiles first and fetch full entity details only on demand through the detail endpoints.

6. **Entity search, filtering, and detail retrieval**
   - `backend/routes/entities.py` and related utilities handle entity listing, filtering, search, and lazy detail loading.
   - This is the main read path for the app: search bar and map interactions drive entity queries, while detail panels request richer profile data only after user selection.
   - The readme’s emphasis on “viewport summary” and “lazy entity detail” matches the repo’s route split between list/summary endpoints and detail endpoints.

7. **Real-time data flow**
   - Supabase Realtime is the cloud event source for live inserts/updates; the frontend can subscribe to these changes, and the backend can also consume them for notifications or refresh logic.
   - `backend/chat` and the SSE chat endpoint provide a second real-time stream: token-by-token responses sent over HTTP with buffering disabled at the proxy layer.
   - This repo therefore has two real-time channels: **database change events** for ecosystem updates and **SSE** for conversational AI output.

8. **Chat and AI subsystem**
   - `backend/chat/engine.py`, `models.py`, `config.py`, and `routes.py` define the chat stack, with both blocking completions and streaming responses.
   - The readme indicates the streaming path uses SSE and token streaming, while search/web context may be injected into responses.
   - The backend also includes `backend/search_agent_routes.py`, suggesting a separate agentic/search-assisted query surface distinct from plain chat.

9. **ML and insights subsystem**
   - `backend/ml/classifier.py`, `predictor.py`, and `serving.py` form the model-serving boundary for keyword-based sector prediction and related ML features.
   - `backend/routes/ml_routes.py` and `backend/routes/mlops_routes.py` expose inference and operational metrics, while `backend/analytics.py` provides ecosystem-level aggregations.
   - On the UI side, `MLInsightsPanel` and `AnalyticsPanel` consume these endpoints to show derived insights rather than raw entity data.

10. **ETL and data ingestion**
   - `backend/etl/extract.py`, `transform.py`, `load.py`, `pipeline.py`, and `live_extract.py` define the ingestion pipeline for startup ecosystem data.
   - This pipeline is the path for bringing in government, commercial, and live source data, then normalizing it into the entity schema.
   - `backend/seed.py` and `backend/seed_entities.py` support initial dataset bootstrapping, while `scripts/scheduler.py` suggests periodic refresh and cache-warming runs.

11. **Normalization, enrichment, and geocoding**
   - `backend/geocoding.py`, `backend/enrichment.py`, `backend/matching.py`, and `backend/directory.py` are the post-ingestion services that improve data quality and usefulness.
   - Geocoding converts place names into coordinates; enrichment adds missing or derived metadata; matching powers mentor/startup or investor/startup recommendations.
   - `scripts/dedupe.py` is a separate maintenance tool for entity consolidation and duplicate resolution.

12. **Caching and performance controls**
   - `backend/cache.py` provides a pluggable cache layer with local TTL/LRU behavior and optional Redis backing.
   - This cache is important because the app serves high-volume spatial queries, analytics aggregations, and repeated detail lookups.
   - The reverse proxy and backend are both tuned for performance, especially for tile delivery and streaming chat responses.

13. **Security and operational boundaries**
   - `backend/security.py` centralizes request validation, rate limits, and other protections called out in the readme.
   - The deployment stack includes **nginx** for SSL, compression, buffering control, SPA fallback, and headers; buffering is especially relevant for SSE chat streaming.
   - Supabase Row-Level Security is part of the data boundary: public reads for active entities, service-role-only writes.

14. **Deployment and runtime topology**
   - `docker-compose.yml` ties together the app, Redis, nginx, and a scheduler service.
   - `Dockerfile`, `systemd/bharat-tech-atlas.service`, and `scripts/deploy.sh` show the project supports containerized deployment as well as a hardened service-managed deployment.
   - `requirements.txt` and the frontend package files imply a classic Python backend plus Node-based frontend build pipeline, with tests in `tests/` validating the API surface.

15. **How to draw the diagram**
   - The most important arrows are: **browser → nginx → FastAPI**, **FastAPI ↔ Supabase/Postgres/PostGIS**, **FastAPI ↔ Redis cache**, **Supabase Realtime → frontend/backend live updates**, and **frontend → MVT tiles/detail endpoints**.
   - The architecture is not one monolith; it is a set of specialized backend services behind one API, optimized for geospatial map rendering, live ecosystem updates, and AI-assisted interaction.

Main entry points: [`frontend/src/App.jsx`](https://github.com/dhanush342/atlas/blob/main/frontend/src/App.jsx) (App shell), [`backend/main.py`](https://github.com/dhanush342/atlas/blob/main/backend/main.py) (API app), [`backend/routes/entities.py`](https://github.com/dhanush342/atlas/blob/main/backend/routes/entities.py) (Entities API), [`backend/database.py`](https://github.com/dhanush342/atlas/blob/main/backend/database.py) (Database layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_fe_app["App shell<br/>React composition<br/>[App.jsx]"]
  node_fe_map["Startup map<br/>map view<br/>[StartupMap.jsx]"]
  node_fe_search["Search bar<br/>query UI<br/>[SearchBar.jsx]"]
  node_fe_sidebar["Sidebar<br/>navigation panel<br/>[Sidebar.jsx]"]
  node_fe_detail["Entity detail<br/>detail panel<br/>[EntityDetail.jsx]"]
  node_fe_analytics["Analytics<br/>insights panel<br/>[AnalyticsPanel.jsx]"]
  node_fe_ml["ML insights<br/>ml panel"]
  node_fe_chat["Chat widget<br/>conversation UI<br/>[ChatWidget.jsx]"]
  node_fe_hooks["Data hooks<br/>react hooks"]
end

subgraph group_backend["Backend"]
  node_be_main["API app<br/>FastAPI entrypoint<br/>[main.py]"]
  node_be_entities["Entities API<br/>read/search API<br/>[entities.py]"]
  node_be_tiles["MVT tiles<br/>map tile API<br/>[mvt_routes.py]"]
  node_be_chat["Chat API<br/>streaming chat<br/>[routes.py]"]
  node_be_ml["ML API<br/>inference service<br/>[ml_routes.py]"]
  node_be_etl["ETL pipeline<br/>ingestion pipeline<br/>[pipeline.py]"]
  node_be_enrich["Enrichment<br/>data quality<br/>[enrichment.py]"]
  node_be_cache["Cache<br/>[cache.py]"]
  node_be_db[("Database layer<br/>postgres/supabase<br/>[database.py]")]
  node_be_supabase[("Supabase client<br/>cloud backend<br/>[supabase_client.py]")]
  node_be_security["Security<br/>controls<br/>[security.py]"]
end

subgraph group_infra["Runtime"]
  node_infra_nginx["nginx<br/>reverse proxy<br/>[nginx.conf]"]
  node_infra_compose["Compose stack<br/>deployment<br/>[docker-compose.yml]"]
  node_infra_sched["Scheduler<br/>ops job<br/>[scheduler.py]"]
end

node_fe_app -->|"renders"| node_fe_map
node_fe_app -->|"includes"| node_fe_search
node_fe_app -->|"includes"| node_fe_sidebar
node_fe_app -->|"includes"| node_fe_detail
node_fe_app -->|"includes"| node_fe_analytics
node_fe_app -->|"includes"| node_fe_ml
node_fe_app -->|"includes"| node_fe_chat
node_fe_hooks -->|"feeds"| node_fe_map
node_fe_hooks -->|"loads"| node_fe_detail
node_fe_hooks -->|"queries"| node_be_entities
node_fe_hooks -->|"subscribes"| node_be_supabase
node_fe_map -->|"requests"| node_be_tiles
node_fe_search -->|"searches"| node_be_entities
node_fe_sidebar -->|"browses"| node_be_entities
node_fe_detail -->|"fetches"| node_be_entities
node_fe_analytics -->|"reads"| node_be_ml
node_fe_ml -->|"reads"| node_be_ml
node_fe_chat -->|"streams"| node_be_chat
node_be_main -->|"applies"| node_be_security
node_be_main -->|"mounts"| node_be_entities
node_be_main -->|"mounts"| node_be_tiles
node_be_main -->|"mounts"| node_be_chat
node_be_main -->|"mounts"| node_be_ml
node_be_entities -->|"reads/writes"| node_be_db
node_be_entities -->|"accelerates"| node_be_cache
node_be_tiles -->|"spatial queries"| node_be_db
node_be_etl -->|"loads"| node_be_db
node_be_enrich -->|"updates"| node_be_db
node_be_enrich -->|"extends"| node_be_etl
node_be_supabase -->|"connects"| node_be_db
node_be_supabase -->|"events"| node_fe_hooks
node_infra_nginx -->|"proxies"| node_be_main
node_infra_compose -->|"orchestrates"| node_infra_nginx
node_infra_compose -->|"orchestrates"| node_be_main
node_infra_compose -->|"orchestrates"| node_infra_sched
node_infra_sched -->|"refreshes"| node_be_etl

click node_fe_app "https://github.com/dhanush342/atlas/blob/main/frontend/src/App.jsx"
click node_fe_map "https://github.com/dhanush342/atlas/blob/main/frontend/src/components/StartupMap.jsx"
click node_fe_search "https://github.com/dhanush342/atlas/blob/main/frontend/src/components/SearchBar.jsx"
click node_fe_sidebar "https://github.com/dhanush342/atlas/blob/main/frontend/src/components/Sidebar.jsx"
click node_fe_detail "https://github.com/dhanush342/atlas/blob/main/frontend/src/components/EntityDetail.jsx"
click node_fe_analytics "https://github.com/dhanush342/atlas/blob/main/frontend/src/components/AnalyticsPanel.jsx"
click node_fe_ml "https://github.com/dhanush342/atlas/blob/main/frontend/src/components/MLInsightsPanel.jsx"
click node_fe_chat "https://github.com/dhanush342/atlas/blob/main/frontend/src/chat/ChatWidget.jsx"
click node_be_main "https://github.com/dhanush342/atlas/blob/main/backend/main.py"
click node_be_entities "https://github.com/dhanush342/atlas/blob/main/backend/routes/entities.py"
click node_be_tiles "https://github.com/dhanush342/atlas/blob/main/backend/routes/mvt_routes.py"
click node_be_chat "https://github.com/dhanush342/atlas/blob/main/backend/chat/routes.py"
click node_be_ml "https://github.com/dhanush342/atlas/blob/main/backend/routes/ml_routes.py"
click node_be_etl "https://github.com/dhanush342/atlas/blob/main/backend/etl/pipeline.py"
click node_be_enrich "https://github.com/dhanush342/atlas/blob/main/backend/enrichment.py"
click node_be_cache "https://github.com/dhanush342/atlas/blob/main/backend/cache.py"
click node_be_db "https://github.com/dhanush342/atlas/blob/main/backend/database.py"
click node_be_supabase "https://github.com/dhanush342/atlas/blob/main/backend/supabase_client.py"
click node_be_security "https://github.com/dhanush342/atlas/blob/main/backend/security.py"
click node_infra_nginx "https://github.com/dhanush342/atlas/blob/main/nginx/nginx.conf"
click node_infra_compose "https://github.com/dhanush342/atlas/blob/main/docker-compose.yml"
click node_infra_sched "https://github.com/dhanush342/atlas/blob/main/scripts/scheduler.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_fe_app,node_fe_map,node_fe_search,node_fe_sidebar,node_fe_detail,node_fe_analytics,node_fe_ml,node_fe_chat,node_fe_hooks toneBlue
class node_be_main,node_be_entities,node_be_tiles,node_be_chat,node_be_ml,node_be_etl,node_be_enrich,node_be_cache,node_be_db,node_be_supabase,node_be_security toneAmber
class node_infra_nginx,node_infra_compose,node_infra_sched toneMint
```

## Components

### Frontend

React/Vite UI for map exploration, search, details, analytics, and chat.

- [App shell](https://github.com/dhanush342/atlas/blob/main/frontend/src/App.jsx): React composition · Assembles the main dashboard layout and coordinates UI regions. · `frontend/src/App.jsx`
- [Startup map](https://github.com/dhanush342/atlas/blob/main/frontend/src/components/StartupMap.jsx): map view · Primary geospatial exploration surface for viewport-based browsing. · `frontend/src/components/StartupMap.jsx`
- [Search bar](https://github.com/dhanush342/atlas/blob/main/frontend/src/components/SearchBar.jsx): query UI · Search and filter entry point driving entity lookup. · `frontend/src/components/SearchBar.jsx`
- [Sidebar](https://github.com/dhanush342/atlas/blob/main/frontend/src/components/Sidebar.jsx): navigation panel · Holds browsable entity lists and supporting controls. · `frontend/src/components/Sidebar.jsx`
- [Entity detail](https://github.com/dhanush342/atlas/blob/main/frontend/src/components/EntityDetail.jsx): detail panel · Lazy-loaded rich profile view for a selected entity. · `frontend/src/components/EntityDetail.jsx`
- [Analytics](https://github.com/dhanush342/atlas/blob/main/frontend/src/components/AnalyticsPanel.jsx): insights panel · Shows ecosystem-level aggregates and derived metrics. · `frontend/src/components/AnalyticsPanel.jsx`
- [ML insights](https://github.com/dhanush342/atlas/blob/main/frontend/src/components/MLInsightsPanel.jsx): ml panel · Displays prediction and model-derived insights. · `frontend/src/components/MLInsightsPanel.jsx`
- [Chat widget](https://github.com/dhanush342/atlas/blob/main/frontend/src/chat/ChatWidget.jsx): conversation UI · Streaming conversational interface for assistant interactions. · `frontend/src/chat/ChatWidget.jsx`
- **Data hooks**: react hooks · Fetches map data, entity detail, filters, and live updates.

### Backend

FastAPI API boundary plus domain services for data, tiles, chat, ML, ETL, and enrichment.

- [API app](https://github.com/dhanush342/atlas/blob/main/backend/main.py): FastAPI entrypoint · Wires middleware, security, routes, and health endpoints. · `backend/main.py`
- [Entities API](https://github.com/dhanush342/atlas/blob/main/backend/routes/entities.py): read/search API · Main read path for listing, filtering, and detail retrieval. · `backend/routes/entities.py`
- [MVT tiles](https://github.com/dhanush342/atlas/blob/main/backend/routes/mvt_routes.py): map tile API · Serves Mapbox Vector Tiles for fast geospatial rendering. · `backend/routes/mvt_routes.py`
- [Chat API](https://github.com/dhanush342/atlas/blob/main/backend/chat/routes.py): streaming chat · Chat routes and engine for blocking and SSE token streaming. · `backend/chat/routes.py`
- [ML API](https://github.com/dhanush342/atlas/blob/main/backend/routes/ml_routes.py): inference service · Exposes prediction and model-serving endpoints. · `backend/routes/ml_routes.py`
- [ETL pipeline](https://github.com/dhanush342/atlas/blob/main/backend/etl/pipeline.py): ingestion pipeline · Extracts, transforms, and loads ecosystem data. · `backend/etl/pipeline.py`
- [Enrichment](https://github.com/dhanush342/atlas/blob/main/backend/enrichment.py): data quality · Geocoding, matching, directory, and enrichment services. · `backend/enrichment.py`
- [Cache](https://github.com/dhanush342/atlas/blob/main/backend/cache.py): cache layer · TTL/LRU and optional Redis-backed acceleration for hot reads. · `backend/cache.py`
- [Database layer](https://github.com/dhanush342/atlas/blob/main/backend/database.py): postgres/supabase · Local SQLite and Supabase/Postgres/PostGIS access boundary. · `backend/database.py`
- [Supabase client](https://github.com/dhanush342/atlas/blob/main/backend/supabase_client.py): cloud backend · Realtime and cloud database integration for live updates. · `backend/supabase_client.py`
- [Security](https://github.com/dhanush342/atlas/blob/main/backend/security.py): controls · Request validation, rate limiting, and API protection. · `backend/security.py`

### Runtime

Deployment, proxy, and operational pieces around the app.

- [nginx](https://github.com/dhanush342/atlas/blob/main/nginx/nginx.conf): reverse proxy · Handles SSL, compression, buffering, and SPA fallback. · `nginx/nginx.conf`
- [Compose stack](https://github.com/dhanush342/atlas/blob/main/docker-compose.yml): deployment · Runs the app with Redis, nginx, and scheduler services. · `docker-compose.yml`
- [Scheduler](https://github.com/dhanush342/atlas/blob/main/scripts/scheduler.py): ops job · Periodic refresh, cache-warming, and maintenance runs. · `scripts/scheduler.py`

## Connections

- App shell → Startup map: renders · The app shell composes the main map workspace.
- App shell → Search bar: includes · Search is part of the primary interaction surface.
- App shell → Sidebar: includes · Sidebar supports entity browsing and navigation.
- App shell → Entity detail: includes · Selected entities open in the detail view.
- App shell → Analytics: includes · Analytics is embedded in the dashboard layout.
- App shell → ML insights: includes · ML insights are surfaced in the UI.
- App shell → Chat widget: includes · Chat is available as an assistant surface.
- Data hooks → Startup map: feeds · Hooks provide data for map rendering and viewport updates.
- Data hooks → Entity detail: loads · Hooks fetch lazy entity detail data.
- Data hooks → Entities API: queries · Frontend data hooks call entity list/detail endpoints.
- Data hooks → Supabase client: subscribes · Live update hooks integrate with Supabase realtime.
- Startup map → MVT tiles: requests · Map UI prefers vector tiles for dense spatial rendering.
- Search bar → Entities API: searches · Search drives filtered entity lookup.
- Sidebar → Entities API: browses · Sidebar content is populated from entity summary endpoints.
- Entity detail → Entities API: fetches · Detail panel loads richer records on demand.
- Analytics → ML API: reads · Analytics panel consumes derived backend metrics and predictions.
- ML insights → ML API: reads · ML insights panel is backed by model-serving endpoints.
- Chat widget → Chat API: streams · Chat UI receives streaming responses from the chat API.
- API app → Security: applies · Security controls are applied at the application boundary.
- API app → Entities API: mounts · Main app wires the public routes.
- API app → MVT tiles: mounts · Main app exposes tile-serving routes.
- API app → Chat API: mounts · Main app exposes chat routes.
- API app → ML API: mounts · Main app exposes ML routes.
- Entities API → Database layer: reads/writes · Entity queries rely on the core data layer.
- Entities API → Cache: accelerates · Hot entity reads and summaries are cached.
- MVT tiles → Database layer: spatial queries · Tile generation reads PostGIS-backed geospatial data.
- ETL pipeline → Database layer: loads · ETL writes normalized records into the data store.
- Enrichment → Database layer: updates · Enrichment services improve stored entity data.
- Enrichment → ETL pipeline: extends · Enrichment is a post-ingestion step in the data flow.
- Supabase client → Database layer: connects · Supabase client provides the cloud data/realtime path.
- Supabase client → Data hooks: events · Realtime updates can be consumed by the frontend.
- nginx → API app: proxies · Reverse proxy forwards requests to the API.
- Compose stack → nginx: orchestrates · Compose brings up the proxy alongside the application stack.
- Compose stack → API app: orchestrates · Compose runs the backend service as part of the stack.
- Compose stack → Scheduler: orchestrates · Scheduler is part of the deployment topology.
- Scheduler → ETL pipeline: refreshes · Scheduled jobs trigger ingestion and maintenance flows.