# akashpg-m/polaris architecture

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

- Interactive diagram: https://gitdiagram.com/akashpg-m/polaris
- Repository: https://github.com/akashpg-m/polaris

## Overview

Polaris is a real-time IoT fleet orchestration platform. Fleet devices send telemetry through a WebSocket gateway; events are streamed for independent spatial processing, archival, and traffic analysis. Live fleet state and routing support matching and demand analysis, which feed autonomous rebalancing and commands back to devices. Operators use the React command center for fleet, mobility, registry, and operations workflows. Backend implementation links are chiefly based on the README architecture; unsampled implementation details are represented at their existing source paths, with those evidence limits noted.

Main entry points: [`v3.0/backend/cmd/gateway/main.go`](https://github.com/akashpg-m/polaris/blob/main/v3.0/backend/cmd/gateway/main.go) (API Gateway), [`v3.0/backend/internal/application/spatial/engine.go`](https://github.com/akashpg-m/polaris/blob/main/v3.0/backend/internal/application/spatial/engine.go) (Spatial Engine), [`v3.0/frontend/src/App.tsx`](https://github.com/akashpg-m/polaris/blob/main/v3.0/frontend/src/App.tsx) (React Command Center), [`v3.0/frontend/src/features/dashboard/DashboardContext.tsx`](https://github.com/akashpg-m/polaris/blob/main/v3.0/frontend/src/features/dashboard/DashboardContext.tsx) (Live Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Device Ingestion"]
  node_gateway["API Gateway<br/>[main.go]"]
  node_ingestion["Telemetry Handler<br/>[ingestion.go]"]
  node_registry["Node Registry"]
  node_publisher["Event Publisher"]
end

subgraph group_processing["Streaming And Spatial"]
  node_consumer["Telemetry Consumer<br/>[kafka_consumer.go]"]
  node_spatial["Spatial Engine<br/>[engine.go]"]
  node_mobility["Mobility Module<br/>[module.go]"]
  node_matching["Nearby Matching"]
  node_traffic["Traffic Consumer"]
end

subgraph group_orchestration["Fleet Orchestration"]
  node_prediction["Demand Prediction"]
  node_rebalancer["Fleet Rebalancer<br/>[strategies.go]"]
  node_commands["Command Delivery<br/>[dispatcher.go]"]
end

subgraph group_persistence["Storage And Routing"]
  node_archiver["Telemetry Archiver<br/>[archiver.go]"]
  node_routing["OSM Routing<br/>[engine.go]"]
end

subgraph group_console["Operator Console"]
  node_app["React Command Center<br/>[App.tsx]"]
  node_dashboard["Live Dashboard"]
  node_api["API Client<br/>[client.ts]"]
  node_auth["Authentication<br/>[AuthContext.tsx]"]
  node_query["Query Cache<br/>[queryClient.tsx]"]
  node_taskui["Task Operations<br/>[Tasks.tsx]"]
end

node_fleet(("Fleet Devices"))
node_kafka["Kafka Stream"]
node_postgres[("PostgreSQL")]
node_redis["Redis Pub/Sub"]
node_operator(("Fleet Operator"))

node_fleet -->|"sends telemetry"| node_gateway
node_gateway -.->|"routes telemetry"| node_ingestion
node_ingestion -.->|"processes nodes"| node_registry
node_ingestion -->|"publishes events"| node_publisher
node_publisher -->|"writes events"| node_kafka
node_kafka -->|"streams telemetry"| node_consumer
node_kafka -->|"streams telemetry"| node_archiver
node_kafka -->|"streams telemetry"| node_traffic
node_consumer -.->|"updates state"| node_spatial
node_spatial -.->|"maintains fleet state"| node_mobility
node_spatial -->|"finds candidates"| node_matching
node_traffic -->|"updates traffic"| node_routing
node_archiver -->|"archives telemetry"| node_postgres
node_spatial -->|"uses routing"| node_routing
node_postgres -->|"supplies history"| node_prediction
node_prediction -->|"predicts demand"| node_rebalancer
node_spatial -->|"supplies live state"| node_rebalancer
node_rebalancer -->|"publishes commands"| node_redis
node_redis -->|"delivers commands"| node_gateway
node_gateway -->|"sends directives"| node_fleet
node_operator -.->|"uses console"| node_app
node_app -->|"provides session"| node_auth
node_app -->|"provides live context"| node_dashboard
node_dashboard -->|"fetches twin data"| node_api
node_dashboard -->|"updates cached data"| node_query
node_app -->|"routes task views"| node_taskui
node_taskui -.->|"requests task data"| node_api
node_app -.->|"serves API workflows"| node_api
node_api -->|"calls gateway APIs"| node_gateway
node_gateway -->|"streams live updates"| node_dashboard

click node_gateway "https://github.com/akashpg-m/polaris/blob/main/v3.0/backend/cmd/gateway/main.go"
click node_ingestion "https://github.com/akashpg-m/polaris/blob/main/v3.0/backend/internal/adapter/handler/ingestion.go"
click node_publisher "https://github.com/akashpg-m/polaris/blob/main/v3.0/backend/internal/adapter/repository/kafka_event_publisher.go"
click node_consumer "https://github.com/akashpg-m/polaris/blob/main/v3.0/backend/internal/application/stream/kafka_consumer.go"
click node_spatial "https://github.com/akashpg-m/polaris/blob/main/v3.0/backend/internal/application/spatial/engine.go"
click node_mobility "https://github.com/akashpg-m/polaris/blob/main/v3.0/backend/internal/modules/mobility/module.go"
click node_matching "https://github.com/akashpg-m/polaris/blob/main/v3.0/backend/internal/modules/mobility/matching/candidate_provider.go"
click node_traffic "https://github.com/akashpg-m/polaris/blob/main/v3.0/backend/internal/modules/mobility/traffic_consumer.go"
click node_archiver "https://github.com/akashpg-m/polaris/blob/main/v3.0/backend/internal/application/stream/archiver.go"
click node_routing "https://github.com/akashpg-m/polaris/blob/main/v3.0/backend/internal/modules/mobility/routing/engine.go"
click node_prediction "https://github.com/akashpg-m/polaris/blob/main/v3.0/backend/internal/application/orchestrator/predictive_strategy.go"
click node_rebalancer "https://github.com/akashpg-m/polaris/blob/main/v3.0/backend/internal/application/orchestrator/strategies.go"
click node_commands "https://github.com/akashpg-m/polaris/blob/main/v3.0/backend/internal/application/dispatch/dispatcher.go"
click node_app "https://github.com/akashpg-m/polaris/blob/main/v3.0/frontend/src/App.tsx"
click node_dashboard "https://github.com/akashpg-m/polaris/blob/main/v3.0/frontend/src/features/dashboard/DashboardContext.tsx"
click node_api "https://github.com/akashpg-m/polaris/blob/main/v3.0/frontend/src/lib/api/client.ts"
click node_auth "https://github.com/akashpg-m/polaris/blob/main/v3.0/frontend/src/features/auth/AuthContext.tsx"
click node_query "https://github.com/akashpg-m/polaris/blob/main/v3.0/frontend/src/lib/query/queryClient.tsx"
click node_taskui "https://github.com/akashpg-m/polaris/blob/main/v3.0/frontend/src/pages/Tasks.tsx"

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_gateway,node_ingestion,node_registry,node_publisher toneBlue
class node_consumer,node_spatial,node_mobility,node_matching,node_traffic,node_postgres,node_redis toneAmber
class node_prediction,node_rebalancer,node_commands toneMint
class node_archiver,node_routing toneRose
class node_app,node_dashboard,node_api,node_auth,node_query,node_taskui,node_fleet,node_kafka,node_operator toneIndigo
```

## Components

### Device Ingestion

- [API Gateway](https://github.com/akashpg-m/polaris/blob/main/v3.0/backend/cmd/gateway/main.go): `v3.0/backend/cmd/gateway/main.go`
- [Telemetry Handler](https://github.com/akashpg-m/polaris/blob/main/v3.0/backend/internal/adapter/handler/ingestion.go): `v3.0/backend/internal/adapter/handler/ingestion.go`
- **Node Registry**
- [Event Publisher](https://github.com/akashpg-m/polaris/blob/main/v3.0/backend/internal/adapter/repository/kafka_event_publisher.go): `v3.0/backend/internal/adapter/repository/kafka_event_publisher.go`

### Streaming And Spatial

- [Telemetry Consumer](https://github.com/akashpg-m/polaris/blob/main/v3.0/backend/internal/application/stream/kafka_consumer.go): `v3.0/backend/internal/application/stream/kafka_consumer.go`
- [Spatial Engine](https://github.com/akashpg-m/polaris/blob/main/v3.0/backend/internal/application/spatial/engine.go): `v3.0/backend/internal/application/spatial/engine.go`
- [Mobility Module](https://github.com/akashpg-m/polaris/blob/main/v3.0/backend/internal/modules/mobility/module.go): `v3.0/backend/internal/modules/mobility/module.go`
- [Nearby Matching](https://github.com/akashpg-m/polaris/blob/main/v3.0/backend/internal/modules/mobility/matching/candidate_provider.go): `v3.0/backend/internal/modules/mobility/matching/candidate_provider.go`
- [Traffic Consumer](https://github.com/akashpg-m/polaris/blob/main/v3.0/backend/internal/modules/mobility/traffic_consumer.go): `v3.0/backend/internal/modules/mobility/traffic_consumer.go`

### Fleet Orchestration

- [Demand Prediction](https://github.com/akashpg-m/polaris/blob/main/v3.0/backend/internal/application/orchestrator/predictive_strategy.go): `v3.0/backend/internal/application/orchestrator/predictive_strategy.go`
- [Fleet Rebalancer](https://github.com/akashpg-m/polaris/blob/main/v3.0/backend/internal/application/orchestrator/strategies.go): `v3.0/backend/internal/application/orchestrator/strategies.go`
- [Command Delivery](https://github.com/akashpg-m/polaris/blob/main/v3.0/backend/internal/application/dispatch/dispatcher.go): `v3.0/backend/internal/application/dispatch/dispatcher.go`

### Storage And Routing

- [Telemetry Archiver](https://github.com/akashpg-m/polaris/blob/main/v3.0/backend/internal/application/stream/archiver.go): `v3.0/backend/internal/application/stream/archiver.go`
- [OSM Routing](https://github.com/akashpg-m/polaris/blob/main/v3.0/backend/internal/modules/mobility/routing/engine.go): `v3.0/backend/internal/modules/mobility/routing/engine.go`

### Operator Console

- [React Command Center](https://github.com/akashpg-m/polaris/blob/main/v3.0/frontend/src/App.tsx): `v3.0/frontend/src/App.tsx`
- [Live Dashboard](https://github.com/akashpg-m/polaris/blob/main/v3.0/frontend/src/features/dashboard/DashboardContext.tsx): `v3.0/frontend/src/features/dashboard/DashboardContext.tsx`
- [API Client](https://github.com/akashpg-m/polaris/blob/main/v3.0/frontend/src/lib/api/client.ts): `v3.0/frontend/src/lib/api/client.ts`
- [Authentication](https://github.com/akashpg-m/polaris/blob/main/v3.0/frontend/src/features/auth/AuthContext.tsx): `v3.0/frontend/src/features/auth/AuthContext.tsx`
- [Query Cache](https://github.com/akashpg-m/polaris/blob/main/v3.0/frontend/src/lib/query/queryClient.tsx): `v3.0/frontend/src/lib/query/queryClient.tsx`
- [Task Operations](https://github.com/akashpg-m/polaris/blob/main/v3.0/frontend/src/pages/Tasks.tsx): `v3.0/frontend/src/pages/Tasks.tsx`

### Other components

- **Fleet Devices**
- **Kafka Stream**
- **PostgreSQL**
- **Redis Pub/Sub**
- **Fleet Operator**

## Connections

- Fleet Devices → API Gateway: sends telemetry (evidence: `README.md`)
- API Gateway → Telemetry Handler: routes telemetry
- Telemetry Handler → Node Registry: processes nodes
- Telemetry Handler → Event Publisher: publishes events (evidence: `README.md`)
- Event Publisher → Kafka Stream: writes events (evidence: `README.md`)
- Kafka Stream → Telemetry Consumer: streams telemetry (evidence: `README.md`)
- Kafka Stream → Telemetry Archiver: streams telemetry (evidence: `README.md`)
- Kafka Stream → Traffic Consumer: streams telemetry (evidence: `README.md`)
- Telemetry Consumer → Spatial Engine: updates state
- Spatial Engine → Mobility Module: maintains fleet state
- Spatial Engine → Nearby Matching: finds candidates (evidence: `README.md`)
- Traffic Consumer → OSM Routing: updates traffic (evidence: `README.md`)
- Telemetry Archiver → PostgreSQL: archives telemetry (evidence: `README.md`)
- Spatial Engine → OSM Routing: uses routing (evidence: `README.md`)
- PostgreSQL → Demand Prediction: supplies history (evidence: `README.md`)
- Demand Prediction → Fleet Rebalancer: predicts demand (evidence: `README.md`)
- Spatial Engine → Fleet Rebalancer: supplies live state (evidence: `README.md`)
- Fleet Rebalancer → Redis Pub/Sub: publishes commands (evidence: `README.md`)
- Redis Pub/Sub → API Gateway: delivers commands (evidence: `README.md`)
- API Gateway → Fleet Devices: sends directives (evidence: `README.md`)
- Fleet Operator → React Command Center: uses console
- React Command Center → Authentication: provides session (evidence: `v3.0/frontend/src/App.tsx`)
- React Command Center → Live Dashboard: provides live context (evidence: `v3.0/frontend/src/App.tsx`)
- Live Dashboard → API Client: fetches twin data (evidence: `v3.0/frontend/src/features/dashboard/DashboardContext.tsx`)
- Live Dashboard → Query Cache: updates cached data (evidence: `v3.0/frontend/src/features/dashboard/DashboardContext.tsx`)
- React Command Center → Task Operations: routes task views (evidence: `v3.0/frontend/src/App.tsx`)
- Task Operations → API Client: requests task data
- React Command Center → API Client: serves API workflows
- API Client → API Gateway: calls gateway APIs (evidence: `README.md`)
- API Gateway → Live Dashboard: streams live updates (evidence: `README.md`)
