# dhanraj84/infracharge architecture

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

- Interactive diagram: https://gitdiagram.com/dhanraj84/infracharge
- Repository: https://github.com/dhanraj84/infracharge

## Overview

1. **Overall shape**
   - InfraCharge is a Next.js 14 App Router application with a mixed architecture: mostly server-side API routes in the same repo, a client-heavy map/UI frontend, plus a separate Python ML service for solar-related prediction work.

2. **Primary user-facing surfaces**
   - The main app routes are organized by workflow: home/landing, charging search, route planning, vehicle selection, CO₂ savings, infrastructure planning (“where to build”), assist/chat, contact, auth pages, and an about page.
   - This suggests the product is not a single feature app; it is a multi-workflow EV mobility platform with several entry points into the same data layer.

3. **Frontend composition**
   - Reusable UI is concentrated under `app/(components)`, including navigation, hero/marketing sections, route inputs, map widgets, chatbot, location button, theme toggle, and cards/buttons.
   - The map-centric components (`MapClient`, `AssistMap`) indicate that interactive geospatial rendering is a core presentation layer, especially for charger discovery and route planning.

4. **Client state and auth boundary**
   - `context/AuthContext.tsx` and `app/providers.tsx` imply a shared client-side provider model for authentication and global app state.
   - The presence of both `lib/firebase.ts` and `lib/firebase-admin.ts` shows a split between client Firebase SDK usage in the browser and server-side admin verification/privileged operations in API routes.

5. **API layer as the main backend**
   - The `app/api` directory acts as the application backend, exposing route handlers for chargers, amenities, geocoding, reverse geocoding, traffic, solar potential, CO₂, vehicles, EV purchases, user profile, chat, and authentication.
   - These endpoints are the main integration boundary: the frontend pages likely consume them instead of calling external services directly.

6. **Geospatial and mobility data flow**
   - Charger discovery appears to combine geocoding, reverse geocoding, charger datasets, nearby amenities, and likely distance/route computations.
   - The presence of `lib/ors.ts` points to OpenRouteService-style routing support, while the `geocode`/`reverse-geocode` endpoints suggest the app converts user location and destination inputs into map coordinates before querying nearby infrastructure.

7. **Infrastructure planning / analytics flow**
   - The “where to build” feature is likely backed by aggregated spatial and demand data rather than live charger lookup alone.
   - Relevant inputs include traffic, EV purchases, district boundary data (`data/Districts.geojson`, `data/india_osm_districts.json`), and solar potential endpoints, which together support planning and site selection rather than navigation.

8. **Local persistence and caching**
   - The repo contains both SQLite files and database abstractions (`lib/sqlite.ts`, `lib/db.ts`, `lib/amenities-cache.ts`), showing a caching/persistence layer for expensive geospatial lookups.
   - `data/amenities_cache.sqlite` and `data/ev_purchases.sqlite` indicate the app stores or preloads structured datasets locally, likely to reduce API latency and dependency on external services.

9. **Relational model and migration path**
   - `lib/models/Profile.ts` and `lib/models/Vehicle.ts` suggest structured domain entities for user profiles and vehicle data.
   - The migration script `scripts/migrate-sqlite-to-postgres.js` plus the README’s PostgreSQL mention imply a deliberate move from local SQLite-backed data to a more scalable PostgreSQL deployment.

10. **AI / ML service boundary**
   - The `ml-server` folder is a separate Python service with a serialized model (`solar_energy_model.pkl`) and `solar_weather_api.py`.
   - This is a clear architectural boundary: Next.js handles user interaction and orchestration, while Python handles specialized prediction logic for solar/energy estimation.

11. **External service integration**
   - The platform depends on third-party geospatial and environmental APIs, especially for map tiles, routing, weather, charger discovery, and geocoding.
   - These integrations are abstracted behind API routes so the frontend has one stable application interface even when the upstream providers change.

12. **Deployment/runtime implication**
   - The repo is a monorepo-style full stack application: React/Next.js for the main runtime, Firebase for auth, PostgreSQL/SQLite for data, and Python for ML.
   - For an architecture diagram, the key boundaries are: browser UI → Next.js app routes/API → data stores and external APIs → Python ML service for specialized predictions.

Main entry points: [`app/layout.tsx`](https://github.com/dhanraj84/infracharge/blob/main/app/layout.tsx) (App shell), [`app/api/chargers/route.ts`](https://github.com/dhanraj84/infracharge/blob/main/app/api/chargers/route.ts) (API layer), [`app/find-charging/page.tsx`](https://github.com/dhanraj84/infracharge/blob/main/app/find-charging/page.tsx) (Workflows), [`app/api/solar-potential/route.ts`](https://github.com/dhanraj84/infracharge/blob/main/app/api/solar-potential/route.ts) (Planning API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend app"]
  node_app_shell["App shell<br/>Next.js layout/providers<br/>[layout.tsx]"]
  node_home_surface["Home<br/>landing page<br/>[page.tsx]"]
  node_workflow_pages["Workflows<br/>route pages<br/>[page.tsx]"]
  node_auth_pages["Auth pages<br/>login/signup pages<br/>[page.tsx]"]
  node_vehicle_page["Vehicle setup<br/>vehicle page<br/>[page.tsx]"]
  node_shared_ui["Shared UI<br/>components<br/>[Navbar.tsx]"]
  node_map_ui["Map UI<br/>map widgets<br/>[MapClient.tsx]"]
  node_assistant_ui["Assistant UI<br/>chat/map widget<br/>[ChatbotWidget.tsx]"]
  node_auth_context["Auth context<br/>client state<br/>[AuthContext.tsx]"]
end

subgraph group_backend["API backend"]
  node_api_root["API layer<br/>Next.js route handlers<br/>[route.ts]"]
  node_location_api["Geo lookup<br/>geocoding endpoints<br/>[route.ts]"]
  node_mobility_api["Mobility data<br/>chargers/amenities/traffic<br/>[route.ts]"]
  node_planning_api["Planning API<br/>solar/CO₂/route endpoints<br/>[route.ts]"]
  node_vehicles_api["Vehicle API<br/>vehicle/profile endpoints<br/>[route.ts]"]
end

subgraph group_data["Data & integrations"]
  node_firebase["Firebase<br/>auth backend<br/>[firebase.ts]"]
  node_storage[("Local data<br/>SQLite/GeoJSON datasets")]
  node_db_layer["DB layer<br/>persistence abstraction<br/>[db.ts]"]
  node_route_engine["Routing engine<br/>OpenRouteService client<br/>[ors.ts]"]
  node_external_services(("External services<br/>maps/weather/geocoding APIs"))
end

subgraph group_ml["ML service"]
  node_ml_service["Solar ML<br/>Python service"]
end

node_app_shell -->|"hosts"| node_home_surface
node_app_shell -->|"wraps"| node_workflow_pages
node_app_shell -->|"wraps"| node_auth_pages
node_app_shell -->|"wraps"| node_vehicle_page
node_home_surface -->|"composes"| node_shared_ui
node_workflow_pages -->|"uses"| node_shared_ui
node_workflow_pages -->|"uses"| node_map_ui
node_workflow_pages -->|"uses"| node_assistant_ui
node_app_shell -->|"provides"| node_auth_context
node_auth_context -->|"authenticates"| node_firebase
node_api_root -->|"routes"| node_location_api
node_api_root -->|"routes"| node_mobility_api
node_api_root -->|"routes"| node_planning_api
node_api_root -->|"routes"| node_vehicles_api
node_location_api -->|"calls"| node_external_services
node_mobility_api -->|"reads"| node_db_layer
node_mobility_api -->|"reads"| node_storage
node_planning_api -->|"computes"| node_route_engine
node_planning_api -->|"predicts"| node_ml_service
node_planning_api -->|"reads"| node_storage
node_vehicles_api -->|"verifies"| node_firebase
node_vehicles_api -->|"persists"| node_db_layer
node_db_layer -->|"caches"| node_storage
node_db_layer -->|"hydrates"| node_external_services
node_route_engine -->|"calls"| node_external_services

click node_app_shell "https://github.com/dhanraj84/infracharge/blob/main/app/layout.tsx"
click node_home_surface "https://github.com/dhanraj84/infracharge/blob/main/app/page.tsx"
click node_workflow_pages "https://github.com/dhanraj84/infracharge/blob/main/app/find-charging/page.tsx"
click node_auth_pages "https://github.com/dhanraj84/infracharge/blob/main/app/login/page.tsx"
click node_vehicle_page "https://github.com/dhanraj84/infracharge/blob/main/app/select-vehicle/page.tsx"
click node_shared_ui "https://github.com/dhanraj84/infracharge/blob/main/app/(components)/Navbar.tsx"
click node_map_ui "https://github.com/dhanraj84/infracharge/blob/main/app/(components)/MapClient.tsx"
click node_assistant_ui "https://github.com/dhanraj84/infracharge/blob/main/app/(components)/ChatbotWidget.tsx"
click node_auth_context "https://github.com/dhanraj84/infracharge/blob/main/context/AuthContext.tsx"
click node_api_root "https://github.com/dhanraj84/infracharge/blob/main/app/api/chargers/route.ts"
click node_location_api "https://github.com/dhanraj84/infracharge/blob/main/app/api/geocode/route.ts"
click node_mobility_api "https://github.com/dhanraj84/infracharge/blob/main/app/api/chargers-all/route.ts"
click node_planning_api "https://github.com/dhanraj84/infracharge/blob/main/app/api/solar-potential/route.ts"
click node_vehicles_api "https://github.com/dhanraj84/infracharge/blob/main/app/api/vehicles/route.ts"
click node_firebase "https://github.com/dhanraj84/infracharge/blob/main/lib/firebase.ts"
click node_storage "https://github.com/dhanraj84/infracharge/blob/main/data/amenities_cache.sqlite"
click node_db_layer "https://github.com/dhanraj84/infracharge/blob/main/lib/db.ts"
click node_route_engine "https://github.com/dhanraj84/infracharge/blob/main/lib/ors.ts"
click node_ml_service "https://github.com/dhanraj84/infracharge/blob/main/ml-server/solar_weather_api.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_shell,node_home_surface,node_workflow_pages,node_auth_pages,node_vehicle_page,node_shared_ui,node_map_ui,node_assistant_ui,node_auth_context toneBlue
class node_api_root,node_location_api,node_mobility_api,node_planning_api,node_vehicles_api toneAmber
class node_firebase,node_storage,node_db_layer,node_route_engine,node_external_services toneMint
class node_ml_service toneRose
```

## Components

### Frontend app

Next.js App Router pages, shared UI, and client-side state.

- [App shell](https://github.com/dhanraj84/infracharge/blob/main/app/layout.tsx): Next.js layout/providers · Root layout and client providers that wrap the application. · `app/layout.tsx`
- [Home](https://github.com/dhanraj84/infracharge/blob/main/app/page.tsx): landing page · Marketing and entry surface for the product. · `app/page.tsx`
- [Workflows](https://github.com/dhanraj84/infracharge/blob/main/app/find-charging/page.tsx): route pages · Primary user flows for charging, routing, vehicle selection, CO₂, planning, assist, and contact. · `app/find-charging/page.tsx`
- [Auth pages](https://github.com/dhanraj84/infracharge/blob/main/app/login/page.tsx): login/signup pages · Authentication entry points for users. · `app/login/page.tsx`
- [Vehicle setup](https://github.com/dhanraj84/infracharge/blob/main/app/select-vehicle/page.tsx): vehicle page · Vehicle selection and manual vehicle entry. · `app/select-vehicle/page.tsx`
- [Shared UI](https://github.com/dhanraj84/infracharge/blob/main/app/(components)/Navbar.tsx): components · Reusable navigation, cards, sections, buttons, and marketing components. · `app/(components)/Navbar.tsx`
- [Map UI](https://github.com/dhanraj84/infracharge/blob/main/app/(components)/MapClient.tsx): map widgets · Interactive map and route visualization components. · `app/(components)/MapClient.tsx`
- [Assistant UI](https://github.com/dhanraj84/infracharge/blob/main/app/(components)/ChatbotWidget.tsx): chat/map widget · Chat and assist interface for guided interactions. · `app/(components)/ChatbotWidget.tsx`
- [Auth context](https://github.com/dhanraj84/infracharge/blob/main/context/AuthContext.tsx): client state · Shared authentication and app state provider. · `context/AuthContext.tsx`

### API backend

Route handlers that expose the app's main server-side capabilities.

- [API layer](https://github.com/dhanraj84/infracharge/blob/main/app/api/chargers/route.ts): Next.js route handlers · Backend entry point for chargers, amenities, geocoding, routing, traffic, solar, CO₂, vehicles, user, and chat. · `app/api/chargers/route.ts`
- [Geo lookup](https://github.com/dhanraj84/infracharge/blob/main/app/api/geocode/route.ts): geocoding endpoints · Geocoding and reverse-geocoding services used to resolve locations. · `app/api/geocode/route.ts`
- [Mobility data](https://github.com/dhanraj84/infracharge/blob/main/app/api/chargers-all/route.ts): chargers/amenities/traffic · Endpoints for charger discovery, nearby amenities, traffic, and EV purchases. · `app/api/chargers-all/route.ts`
- [Planning API](https://github.com/dhanraj84/infracharge/blob/main/app/api/solar-potential/route.ts): solar/CO₂/route endpoints · Endpoints used by infrastructure planning and impact analysis. · `app/api/solar-potential/route.ts`
- [Vehicle API](https://github.com/dhanraj84/infracharge/blob/main/app/api/vehicles/route.ts): vehicle/profile endpoints · Vehicle and user profile endpoints including seeding and persistence support. · `app/api/vehicles/route.ts`

### Data & integrations

Local datasets, persistence, Firebase, routing, and external service boundaries.

- [Firebase](https://github.com/dhanraj84/infracharge/blob/main/lib/firebase.ts): auth backend · Client and admin Firebase SDK boundary for authentication and privileged access. · `lib/firebase.ts`
- [Local data](https://github.com/dhanraj84/infracharge/blob/main/data/amenities_cache.sqlite): SQLite/GeoJSON datasets · Embedded datasets and caches for districts, amenities, and EV purchases. · `data/amenities_cache.sqlite`
- [DB layer](https://github.com/dhanraj84/infracharge/blob/main/lib/db.ts): persistence abstraction · SQLite/Postgres access and cached amenities support. · `lib/db.ts`
- [Routing engine](https://github.com/dhanraj84/infracharge/blob/main/lib/ors.ts): OpenRouteService client · Route computation support for map and planning flows. · `lib/ors.ts`
- **External services**: maps/weather/geocoding APIs · Upstream providers consumed through the API layer.

### ML service

Separate Python service for solar prediction.

- [Solar ML](https://github.com/dhanraj84/infracharge/blob/main/ml-server/solar_weather_api.py): Python service · Standalone Python prediction service for solar-related estimates. · `ml-server/solar_weather_api.py`

## Connections

- App shell → Home: hosts · The root app shell renders the landing experience.
- App shell → Workflows: wraps · Shared layout/providers support the main workflow routes.
- App shell → Auth pages: wraps · Authentication pages use the same application shell.
- App shell → Vehicle setup: wraps · Vehicle setup runs inside the same Next.js app shell.
- Home → Shared UI: composes · Landing page is built from reusable marketing components.
- Workflows → Shared UI: uses · Workflow pages reuse shared UI primitives.
- Workflows → Map UI: uses · Core workflows depend on interactive map components.
- Workflows → Assistant UI: uses · Assist and chat flows are surfaced through the same frontend.
- App shell → Auth context: provides · Global providers expose auth and app state.
- Auth context → Firebase: authenticates · Client auth flows connect to Firebase.
- API layer → Geo lookup: routes · The API layer exposes geocoding endpoints.
- API layer → Mobility data: routes · The API layer exposes charger, amenities, traffic, and purchase data endpoints.
- API layer → Planning API: routes · The API layer exposes planning and impact analysis endpoints.
- API layer → Vehicle API: routes · The API layer exposes vehicle and profile endpoints.
- Geo lookup → External services: calls · Geocoding requests depend on upstream map/location providers.
- Mobility data → DB layer: reads · Mobility endpoints query cached/local persistence.
- Mobility data → Local data: reads · Endpoints use local spatial and purchase datasets.
- Planning API → Routing engine: computes · Planning endpoints use routing support for distance and path logic.
- Planning API → Solar ML: predicts · Solar-related planning can delegate to the Python ML service.
- Planning API → Local data: reads · Planning combines district and demand datasets from local storage.
- Vehicle API → Firebase: verifies · User and vehicle access uses Firebase auth/admin boundaries.
- Vehicle API → DB layer: persists · Vehicle/profile data is stored through the DB layer.
- DB layer → Local data: caches · SQLite-backed caches and embedded datasets support data access.
- DB layer → External services: hydrates · Persistence layer may be refreshed from external sources.
- Routing engine → External services: calls · Routing relies on an external routing provider.