# saptarshi-adhikari/polaris architecture

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

- Interactive diagram: https://gitdiagram.com/saptarshi-adhikari/polaris
- Repository: https://github.com/saptarshi-adhikari/polaris

## Overview

POLARIS is a browser-based polar-navigation digital twin: operators inspect simulated or real maritime conditions, evaluate routes around dynamic ice hazards, and view navigation guidance on a map or radar display. The README documents the main simulation-to-navigation flow, asynchronous pathfinding, route comparison, and optional forecasting service; sampled code also confirms real-data mode and expert-review persistence. Several backend and UI connections are documented but not represented by sampled call sites, so those links are omitted where ownership is uncertain.

Main entry points: [`src/js/ai/aiNavigator.js`](https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/ai/aiNavigator.js) (AI Navigator), [`src/js/main.js`](https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/main.js) (App Loop), [`src/js/geo/modeManager.js`](https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/geo/modeManager.js) (Mode Manager), [`src/js/simulation/vectorField.js`](https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/simulation/vectorField.js) (Drift Physics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Digital Twin"]
  node_app["App Loop<br/>[main.js]"]
  node_physics["Drift Physics<br/>[vectorField.js]"]
  node_vessel["Vessel Model<br/>[ship.js]"]
  node_hazards["Iceberg Model<br/>[iceberg.js]"]
  node_renderer["Map And Radar<br/>[canvasRenderer.js]"]
  node_controls["UI Controls<br/>[uiController.js]"]
end

subgraph group_data["Environment Data"]
  node_mode["Mode Manager<br/>[modeManager.js]"]
  node_demo["Demo Data"]
  node_real["Real Data"]
  node_antarctic["Antarctic Data"]
  node_replay["Historical Replay"]
end

subgraph group_navigation["Navigation Intelligence"]
  node_navigator["AI Navigator<br/>[aiNavigator.js]"]
  node_planner["Route Planner"]
  node_worker["Route Worker<br/>[routeWorker.js]"]
  node_decision["Route Scoring<br/>[decisionEngine.js]"]
  node_compare["Route Comparison"]
end

subgraph group_ml["Forecast Service"]
  node_mlapi["Forecast API<br/>[main.py]"]
  node_mlmodels["Forecast Models<br/>[ml_api.py]"]
end

subgraph group_review["Expert Review"]
  node_reviewapi["Review API<br/>[review_api.py]"]
  node_reviewmanager[("Review Manager")]
end

node_operator(("Operator"))
node_reviewer(("Domain Reviewer"))

node_operator -->|"operates"| node_controls
node_controls -->|"controls"| node_app
node_app -->|"updates"| node_physics
node_app -->|"coordinates"| node_navigator
node_app -->|"renders"| node_renderer
node_physics -->|"drives motion"| node_vessel
node_physics -->|"drives drift"| node_hazards
node_mode -->|"selects provider"| node_demo
node_mode -->|"selects provider"| node_real
node_mode -->|"initializes map"| node_renderer
node_real -->|"reads samples"| node_antarctic
node_replay -->|"reads observations"| node_real
node_navigator -->|"plans routes"| node_planner
node_navigator -->|"dispatches search"| node_worker
node_worker -->|"returns waypoints"| node_navigator
node_navigator -->|"scores candidates"| node_decision
node_navigator -->|"supplies options"| node_compare
node_navigator -.->|"requests forecasts"| node_mlapi
node_mlapi -->|"serves forecasts"| node_mlmodels
node_reviewer -->|"submits annotations"| node_reviewapi
node_reviewapi -->|"manages reviews"| node_reviewmanager

click node_app "https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/main.js"
click node_physics "https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/simulation/vectorField.js"
click node_vessel "https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/simulation/ship.js"
click node_hazards "https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/simulation/iceberg.js"
click node_renderer "https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/render/canvasRenderer.js"
click node_controls "https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/ui/uiController.js"
click node_mode "https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/geo/modeManager.js"
click node_demo "https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/data/DemoDataProvider.js"
click node_real "https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/data/RealDataProvider.js"
click node_antarctic "https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/data/antarcticDataManager.js"
click node_replay "https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/providers/realReplayEngine.js"
click node_navigator "https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/ai/aiNavigator.js"
click node_planner "https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/ai/routePlannerCore.js"
click node_worker "https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/ai/routeWorker.js"
click node_decision "https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/ai/decisionEngine.js"
click node_compare "https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/ui/routeComparisonUI.js"
click node_mlapi "https://github.com/saptarshi-adhikari/polaris/blob/main/backend/main.py"
click node_mlmodels "https://github.com/saptarshi-adhikari/polaris/blob/main/backend/ml_api.py"
click node_reviewapi "https://github.com/saptarshi-adhikari/polaris/blob/main/backend/review_api.py"
click node_reviewmanager "https://github.com/saptarshi-adhikari/polaris/blob/main/backend/polaris_review_manager.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,node_physics,node_vessel,node_hazards,node_renderer,node_controls,node_reviewer toneBlue
class node_mode,node_demo,node_real,node_antarctic,node_replay toneAmber
class node_navigator,node_planner,node_worker,node_decision,node_compare toneMint
class node_mlapi,node_mlmodels toneRose
class node_reviewapi,node_reviewmanager,node_operator toneIndigo
```

## Components

### Digital Twin

- [App Loop](https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/main.js): `src/js/main.js`
- [Drift Physics](https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/simulation/vectorField.js): `src/js/simulation/vectorField.js`
- [Vessel Model](https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/simulation/ship.js): `src/js/simulation/ship.js`
- [Iceberg Model](https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/simulation/iceberg.js): `src/js/simulation/iceberg.js`
- [Map And Radar](https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/render/canvasRenderer.js): `src/js/render/canvasRenderer.js`
- [UI Controls](https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/ui/uiController.js): `src/js/ui/uiController.js`

### Environment Data

- [Mode Manager](https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/geo/modeManager.js): `src/js/geo/modeManager.js`
- [Demo Data](https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/data/DemoDataProvider.js): `src/js/data/DemoDataProvider.js`
- [Real Data](https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/data/RealDataProvider.js): `src/js/data/RealDataProvider.js`
- [Antarctic Data](https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/data/antarcticDataManager.js): `src/js/data/antarcticDataManager.js`
- [Historical Replay](https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/providers/realReplayEngine.js): `src/js/providers/realReplayEngine.js`

### Navigation Intelligence

- [AI Navigator](https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/ai/aiNavigator.js): `src/js/ai/aiNavigator.js`
- [Route Planner](https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/ai/routePlannerCore.js): `src/js/ai/routePlannerCore.js`
- [Route Worker](https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/ai/routeWorker.js): `src/js/ai/routeWorker.js`
- [Route Scoring](https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/ai/decisionEngine.js): `src/js/ai/decisionEngine.js`
- [Route Comparison](https://github.com/saptarshi-adhikari/polaris/blob/main/src/js/ui/routeComparisonUI.js): `src/js/ui/routeComparisonUI.js`

### Forecast Service

- [Forecast API](https://github.com/saptarshi-adhikari/polaris/blob/main/backend/main.py): `backend/main.py`
- [Forecast Models](https://github.com/saptarshi-adhikari/polaris/blob/main/backend/ml_api.py): `backend/ml_api.py`

### Expert Review

- [Review API](https://github.com/saptarshi-adhikari/polaris/blob/main/backend/review_api.py): `backend/review_api.py`
- [Review Manager](https://github.com/saptarshi-adhikari/polaris/blob/main/backend/polaris_review_manager.py): `backend/polaris_review_manager.py`

### Other components

- **Operator**
- **Domain Reviewer**

## Connections

- Operator → UI Controls: operates
- UI Controls → App Loop: controls
- App Loop → Drift Physics: updates
- App Loop → AI Navigator: coordinates
- App Loop → Map And Radar: renders
- Drift Physics → Vessel Model: drives motion
- Drift Physics → Iceberg Model: drives drift
- Mode Manager → Demo Data: selects provider
- Mode Manager → Real Data: selects provider
- Mode Manager → Map And Radar: initializes map
- Real Data → Antarctic Data: reads samples
- Historical Replay → Real Data: reads observations
- AI Navigator → Route Planner: plans routes
- AI Navigator → Route Worker: dispatches search
- Route Worker → AI Navigator: returns waypoints
- AI Navigator → Route Scoring: scores candidates
- AI Navigator → Route Comparison: supplies options
- AI Navigator → Forecast API: requests forecasts
- Forecast API → Forecast Models: serves forecasts
- Domain Reviewer → Review API: submits annotations
- Review API → Review Manager: manages reviews