# shruthiofficial29-creator/polarisai architecture

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

- Interactive diagram: https://gitdiagram.com/shruthiofficial29-creator/polarisai
- Repository: https://github.com/shruthiofficial29-creator/polarisai

## Overview

POLARIS is an offline-first Antarctic navigation decision-support prototype using deterministic demo models. Its main workflow is mission analysis: the navigator selects a destination and priority, mission state requests candidate routes, and the console presents risk, forecast, and route comparisons. During simulation, changing conditions can trigger a reroute proposal for operator adoption. The map, iceberg intelligence, sea-ice forecast, assistant, and analytics are distinct product capabilities. Source excerpts show the core orchestration and model calls; some page wiring is supported only by the SOURCE INDEX or README. The optional backend is documented as a future integration, not a required runtime dependency.

Main entry points: [`src/state/useMission.tsx`](https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/state/useMission.tsx) (Mission state), [`src/services/riskService.ts`](https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/services/riskService.ts) (Risk assessment), [`src/App.tsx`](https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/App.tsx) (App shell), [`src/components/map/AntarcticMap.tsx`](https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/components/map/AntarcticMap.tsx) (Antarctic map)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_console["Navigation console"]
  node_app["App shell<br/>[App.tsx]"]
  node_dashboard["Dashboard<br/>[Dashboard.tsx]"]
  node_map["Antarctic map<br/>[AntarcticMap.tsx]"]
  node_mission_planner["Mission planner<br/>[MissionPlanner.tsx]"]
end

subgraph group_mission["Mission workflow"]
  node_mission_state["Mission state<br/>[useMission.tsx]"]
  node_route_planner["Route planner<br/>[RoutePlanner.tsx]"]
  node_route_optimizer["Route optimizer"]
  node_route_compare["Route comparison"]
  node_why_route["Route rationale<br/>[WhyThisRoute.tsx]"]
  node_simulation["Simulation<br/>[Simulation.tsx]"]
  node_sim_controls["Simulation controls"]
  node_reroute["Reroute review"]
end

subgraph group_models["Demo models"]
  node_risk["Risk assessment<br/>[riskService.ts]"]
  node_environment["Environment snapshot<br/>[environment.ts]"]
  node_sea_ice["Sea-ice forecast"]
  node_weather["Weather model<br/>[weatherService.ts]"]
  node_iceberg_tracks["Iceberg trajectories"]
  node_geo["Geospatial utilities<br/>[geo.ts]"]
  node_alert_service["Alert generation<br/>[alertService.ts]"]
  node_scenario_data["Scenario data<br/>[scenario.ts]"]
  node_iceberg_data["Iceberg data<br/>[icebergs.ts]"]
end

subgraph group_insights["Intelligence tools"]
  node_iceberg_page["Iceberg intelligence"]
  node_iceberg_panel["Iceberg details<br/>[IcebergPanel.tsx]"]
  node_seaice_page["Sea-ice forecast page<br/>[SeaIceForecast.tsx]"]
  node_analytics["Analytics<br/>[Analytics.tsx]"]
  node_assistant["POLARIS assistant"]
  node_assistant_service["Assistant responses"]
end

subgraph group_integration["Optional backend"]
  node_backend["Optional FastAPI backend<br/>[main.py]"]
  node_backend_schemas["Backend schemas<br/>[schemas.py]"]
end

node_navigator(("Vessel navigator"))

node_navigator -->|"opens console"| node_app
node_app -->|"provides state"| node_mission_state
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_route_planner
node_app -->|"routes to"| node_simulation
node_app -->|"routes to"| node_seaice_page
node_app -->|"routes to"| node_iceberg_page
node_app -->|"routes to"| node_analytics
node_dashboard -->|"renders"| node_map
node_dashboard -->|"renders"| node_mission_planner
node_dashboard -->|"renders"| node_assistant
node_mission_planner -->|"uses mission state"| node_mission_state
node_mission_state -->|"requests routes"| node_route_optimizer
node_mission_state -->|"checks risk"| node_risk
node_mission_state -->|"generates alerts"| node_alert_service
node_mission_state -->|"requests forecast"| node_sea_ice
node_mission_state -->|"drives mission state"| node_simulation
node_simulation -->|"renders"| node_sim_controls
node_simulation -->|"renders"| node_reroute
node_sim_controls -->|"controls simulation"| node_mission_state
node_route_optimizer -->|"scores routes"| node_risk
node_route_optimizer -->|"samples ice"| node_sea_ice
node_route_optimizer -->|"samples tracks"| node_iceberg_tracks
node_route_optimizer -->|"samples weather"| node_weather
node_route_optimizer -->|"measures distance"| node_geo
node_risk -->|"reads concentration"| node_sea_ice
node_risk -->|"reads positions"| node_iceberg_tracks
node_risk -->|"reads conditions"| node_weather
node_risk -->|"measures proximity"| node_geo
node_risk -->|"assesses hazards"| node_iceberg_data
node_iceberg_tracks -->|"projects positions"| node_geo
node_seaice_page -->|"renders map"| node_map
node_seaice_page -->|"reads mission state"| node_mission_state
node_iceberg_page -->|"renders details"| node_iceberg_panel
node_iceberg_page -->|"renders map"| node_map
node_iceberg_page -->|"shows trajectories"| node_iceberg_tracks
node_iceberg_panel -->|"reads iceberg data"| node_iceberg_data
node_iceberg_panel -->|"shows trajectory"| node_iceberg_tracks
node_assistant -->|"requests answers"| node_assistant_service
node_assistant_service -->|"uses risk results"| node_risk
node_assistant_service -->|"uses trajectories"| node_iceberg_tracks
node_map -->|"draws ice layers"| node_sea_ice
node_map -->|"draws conditions"| node_weather
node_map -->|"draws risk"| node_risk
node_map -->|"draws tracks"| node_iceberg_tracks
node_sea_ice -->|"reads time steps"| node_scenario_data
node_navigator -.->|"may connect"| node_backend
node_backend -->|"uses schemas"| node_backend_schemas

click node_app "https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/App.tsx"
click node_dashboard "https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/pages/Dashboard.tsx"
click node_map "https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/components/map/AntarcticMap.tsx"
click node_mission_planner "https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/components/panels/MissionPlanner.tsx"
click node_mission_state "https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/state/useMission.tsx"
click node_route_planner "https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/pages/RoutePlanner.tsx"
click node_route_optimizer "https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/services/routeOptimizationService.ts"
click node_route_compare "https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/components/panels/RouteComparison.tsx"
click node_why_route "https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/components/panels/WhyThisRoute.tsx"
click node_simulation "https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/pages/Simulation.tsx"
click node_sim_controls "https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/components/panels/SimulationControls.tsx"
click node_reroute "https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/components/panels/RouteUpdateModal.tsx"
click node_risk "https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/services/riskService.ts"
click node_environment "https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/services/environment.ts"
click node_sea_ice "https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/services/seaIceForecastService.ts"
click node_weather "https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/services/weatherService.ts"
click node_iceberg_tracks "https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/services/icebergTrajectoryService.ts"
click node_geo "https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/services/geo.ts"
click node_alert_service "https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/services/alertService.ts"
click node_iceberg_page "https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/pages/IcebergIntelligence.tsx"
click node_iceberg_panel "https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/components/panels/IcebergPanel.tsx"
click node_seaice_page "https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/pages/SeaIceForecast.tsx"
click node_analytics "https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/pages/Analytics.tsx"
click node_assistant "https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/components/assistant/PolarisAssistant.tsx"
click node_assistant_service "https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/services/assistantService.ts"
click node_scenario_data "https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/data/scenario.ts"
click node_iceberg_data "https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/data/icebergs.ts"
click node_backend "https://github.com/shruthiofficial29-creator/polarisai/blob/main/backend/main.py"
click node_backend_schemas "https://github.com/shruthiofficial29-creator/polarisai/blob/main/backend/schemas.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_dashboard,node_map,node_mission_planner toneBlue
class node_mission_state,node_route_planner,node_route_optimizer,node_route_compare,node_why_route,node_simulation,node_sim_controls,node_reroute toneAmber
class node_risk,node_environment,node_sea_ice,node_weather,node_iceberg_tracks,node_geo,node_alert_service,node_scenario_data,node_iceberg_data toneMint
class node_iceberg_page,node_iceberg_panel,node_seaice_page,node_analytics,node_assistant,node_assistant_service toneRose
class node_backend,node_backend_schemas,node_navigator toneIndigo
```

## Components

### Navigation console

- [App shell](https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/App.tsx): `src/App.tsx`
- [Dashboard](https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/pages/Dashboard.tsx): `src/pages/Dashboard.tsx`
- [Antarctic map](https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/components/map/AntarcticMap.tsx): `src/components/map/AntarcticMap.tsx`
- [Mission planner](https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/components/panels/MissionPlanner.tsx): `src/components/panels/MissionPlanner.tsx`

### Mission workflow

- [Mission state](https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/state/useMission.tsx): `src/state/useMission.tsx`
- [Route planner](https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/pages/RoutePlanner.tsx): `src/pages/RoutePlanner.tsx`
- [Route optimizer](https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/services/routeOptimizationService.ts): `src/services/routeOptimizationService.ts`
- [Route comparison](https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/components/panels/RouteComparison.tsx): `src/components/panels/RouteComparison.tsx`
- [Route rationale](https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/components/panels/WhyThisRoute.tsx): `src/components/panels/WhyThisRoute.tsx`
- [Simulation](https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/pages/Simulation.tsx): `src/pages/Simulation.tsx`
- [Simulation controls](https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/components/panels/SimulationControls.tsx): `src/components/panels/SimulationControls.tsx`
- [Reroute review](https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/components/panels/RouteUpdateModal.tsx): `src/components/panels/RouteUpdateModal.tsx`

### Demo models

- [Risk assessment](https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/services/riskService.ts): `src/services/riskService.ts`
- [Environment snapshot](https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/services/environment.ts): `src/services/environment.ts`
- [Sea-ice forecast](https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/services/seaIceForecastService.ts): `src/services/seaIceForecastService.ts`
- [Weather model](https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/services/weatherService.ts): `src/services/weatherService.ts`
- [Iceberg trajectories](https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/services/icebergTrajectoryService.ts): `src/services/icebergTrajectoryService.ts`
- [Geospatial utilities](https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/services/geo.ts): `src/services/geo.ts`
- [Alert generation](https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/services/alertService.ts): `src/services/alertService.ts`
- [Scenario data](https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/data/scenario.ts): `src/data/scenario.ts`
- [Iceberg data](https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/data/icebergs.ts): `src/data/icebergs.ts`

### Intelligence tools

- [Iceberg intelligence](https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/pages/IcebergIntelligence.tsx): `src/pages/IcebergIntelligence.tsx`
- [Iceberg details](https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/components/panels/IcebergPanel.tsx): `src/components/panels/IcebergPanel.tsx`
- [Sea-ice forecast page](https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/pages/SeaIceForecast.tsx): `src/pages/SeaIceForecast.tsx`
- [Analytics](https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/pages/Analytics.tsx): `src/pages/Analytics.tsx`
- [POLARIS assistant](https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/components/assistant/PolarisAssistant.tsx): `src/components/assistant/PolarisAssistant.tsx`
- [Assistant responses](https://github.com/shruthiofficial29-creator/polarisai/blob/main/src/services/assistantService.ts): `src/services/assistantService.ts`

### Optional backend

- [Optional FastAPI backend](https://github.com/shruthiofficial29-creator/polarisai/blob/main/backend/main.py): `backend/main.py`
- [Backend schemas](https://github.com/shruthiofficial29-creator/polarisai/blob/main/backend/schemas.py): `backend/schemas.py`

### Other components

- **Vessel navigator**

## Connections

- Vessel navigator → App shell: opens console (evidence: `README.md`)
- App shell → Mission state: provides state (evidence: `src/App.tsx`)
- App shell → Dashboard: routes to (evidence: `src/App.tsx`)
- App shell → Route planner: routes to (evidence: `src/App.tsx`)
- App shell → Simulation: routes to (evidence: `src/App.tsx`)
- App shell → Sea-ice forecast page: routes to (evidence: `src/App.tsx`)
- App shell → Iceberg intelligence: routes to (evidence: `src/App.tsx`)
- App shell → Analytics: routes to (evidence: `src/App.tsx`)
- Dashboard → Antarctic map: renders (evidence: `src/pages/Dashboard.tsx`)
- Dashboard → Mission planner: renders (evidence: `src/pages/Dashboard.tsx`)
- Dashboard → POLARIS assistant: renders (evidence: `src/pages/Dashboard.tsx`)
- Mission planner → Mission state: uses mission state
- Mission state → Route optimizer: requests routes (evidence: `src/state/useMission.tsx`)
- Mission state → Risk assessment: checks risk (evidence: `src/state/useMission.tsx`)
- Mission state → Alert generation: generates alerts (evidence: `src/state/useMission.tsx`)
- Mission state → Sea-ice forecast: requests forecast (evidence: `src/state/useMission.tsx`)
- Mission state → Simulation: drives mission state (evidence: `src/pages/Simulation.tsx`)
- Simulation → Simulation controls: renders (evidence: `src/pages/Simulation.tsx`)
- Simulation → Reroute review: renders (evidence: `src/pages/Simulation.tsx`)
- Simulation controls → Mission state: controls simulation (evidence: `src/components/panels/SimulationControls.tsx`)
- Route optimizer → Risk assessment: scores routes (evidence: `src/services/routeOptimizationService.ts`)
- Route optimizer → Sea-ice forecast: samples ice (evidence: `src/services/routeOptimizationService.ts`)
- Route optimizer → Iceberg trajectories: samples tracks (evidence: `src/services/routeOptimizationService.ts`)
- Route optimizer → Weather model: samples weather (evidence: `src/services/routeOptimizationService.ts`)
- Route optimizer → Geospatial utilities: measures distance (evidence: `src/services/routeOptimizationService.ts`)
- Risk assessment → Sea-ice forecast: reads concentration (evidence: `src/services/riskService.ts`)
- Risk assessment → Iceberg trajectories: reads positions (evidence: `src/services/riskService.ts`)
- Risk assessment → Weather model: reads conditions (evidence: `src/services/riskService.ts`)
- Risk assessment → Geospatial utilities: measures proximity (evidence: `src/services/riskService.ts`)
- Risk assessment → Iceberg data: assesses hazards (evidence: `src/services/riskService.ts`)
- Iceberg trajectories → Geospatial utilities: projects positions (evidence: `src/services/icebergTrajectoryService.ts`)
- Sea-ice forecast page → Antarctic map: renders map (evidence: `src/pages/SeaIceForecast.tsx`)
- Sea-ice forecast page → Mission state: reads mission state (evidence: `src/pages/SeaIceForecast.tsx`)
- Iceberg intelligence → Iceberg details: renders details (evidence: `src/pages/IcebergIntelligence.tsx`)
- Iceberg intelligence → Antarctic map: renders map (evidence: `src/pages/IcebergIntelligence.tsx`)
- Iceberg intelligence → Iceberg trajectories: shows trajectories (evidence: `src/pages/IcebergIntelligence.tsx`)
- Iceberg details → Iceberg data: reads iceberg data (evidence: `src/components/panels/IcebergPanel.tsx`)
- Iceberg details → Iceberg trajectories: shows trajectory (evidence: `src/components/panels/IcebergPanel.tsx`)
- POLARIS assistant → Assistant responses: requests answers (evidence: `src/components/assistant/PolarisAssistant.tsx`)
- Assistant responses → Risk assessment: uses risk results (evidence: `src/services/assistantService.ts`)
- Assistant responses → Iceberg trajectories: uses trajectories (evidence: `src/services/assistantService.ts`)
- Antarctic map → Sea-ice forecast: draws ice layers (evidence: `src/components/map/AntarcticMap.tsx`)
- Antarctic map → Weather model: draws conditions (evidence: `src/components/map/AntarcticMap.tsx`)
- Antarctic map → Risk assessment: draws risk (evidence: `src/components/map/AntarcticMap.tsx`)
- Antarctic map → Iceberg trajectories: draws tracks (evidence: `src/components/map/AntarcticMap.tsx`)
- Sea-ice forecast → Scenario data: reads time steps (evidence: `src/services/seaIceForecastService.ts`)
- Vessel navigator → Optional FastAPI backend: may connect (evidence: `README.md`)
- Optional FastAPI backend → Backend schemas: uses schemas (evidence: `backend/main.py`)
