# patilshrutika1803/polaris architecture

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

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

## Overview

POLARIS is a human-in-the-loop Antarctic iceberg forecasting and navigation decision-support application. A user supplies vessel and route inputs in Ship Navigation; the frontend submits them to the FastAPI analysis endpoint, which prepares B15A features, predicts iceberg positions, looks up GLORYS12 conditions, scores proximity risk, and optimizes a constrained route. The normalized result is retained in browser session state for map review and analysis pages, including an assistant that explains analysis outputs. The backend orchestration and frontend request mapping are sampled; other UI-page wiring is represented only where documented or evident from the tree.

Main entry points: [`backend/main.py`](https://github.com/patilshrutika1803/polaris/blob/main/backend/main.py) (FastAPI Analysis), [`frontend/src/pages/ShipNavigation.jsx`](https://github.com/patilshrutika1803/polaris/blob/main/frontend/src/pages/ShipNavigation.jsx) (Route Inputs), [`frontend/src/api/polarisApi.js`](https://github.com/patilshrutika1803/polaris/blob/main/frontend/src/api/polarisApi.js) (API Client), [`frontend/src/pages`](https://github.com/patilshrutika1803/polaris/tree/main/frontend/src/pages) (Review Pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Interactive Review"]
  node_navigation_ui["Route Inputs<br/>[ShipNavigation.jsx]"]
  node_client_api["API Client<br/>[polarisApi.js]"]
  node_analysis_state["Analysis State"]
  node_review_pages["Review Pages"]
  node_map_view["3D Map<br/>[MapView.jsx]"]
  node_assistant["AI Assistant<br/>[AIAssistant.jsx]"]
end

subgraph group_api["Analysis API"]
  node_api_service["FastAPI Analysis<br/>[main.py]"]
end

subgraph group_forecast["Forecast Inputs"]
  node_feature_extraction["Feature Extraction"]
  node_b15a_records["B15A Records"]
  node_trajectory_model["Trajectory Prediction<br/>[predict.py]"]
  node_model_file["Trained Model<br/>[iceberg_model.pkl]"]
  node_environment_service["Environmental Lookup<br/>[environment.py]"]
  node_glorys_data["GLORYS12 Reference<br/>[GLORYS12.nc]"]
end

subgraph group_decision["Risk And Routing"]
  node_risk_engine["Proximity Risk<br/>[risk_engine.py]"]
  node_route_optimizer["Route Optimizer<br/>[navigation.py]"]
end

node_operator(("Vessel Operator"))
node_human_decision(("Human Decision"))

node_operator -->|"enters route inputs"| node_navigation_ui
node_navigation_ui -->|"requests analysis"| node_client_api
node_client_api -->|"POST analysis"| node_api_service
node_api_service -->|"extracts features"| node_feature_extraction
node_feature_extraction -->|"reads records"| node_b15a_records
node_api_service -->|"predicts trajectory"| node_trajectory_model
node_trajectory_model -->|"loads model"| node_model_file
node_api_service -->|"looks up conditions"| node_environment_service
node_environment_service -->|"reads dataset"| node_glorys_data
node_api_service -->|"evaluates risk"| node_risk_engine
node_api_service -->|"optimizes route"| node_route_optimizer
node_route_optimizer -->|"checks grid conditions"| node_environment_service
node_api_service -->|"returns analysis"| node_client_api
node_client_api -->|"normalizes result"| node_navigation_ui
node_navigation_ui -->|"stores analysis"| node_analysis_state
node_analysis_state -->|"provides analysis"| node_review_pages
node_review_pages -->|"renders visualization"| node_map_view
node_review_pages -->|"shows explanations"| node_assistant
node_assistant -->|"supports review"| node_human_decision
node_map_view -->|"presents route"| node_human_decision

click node_navigation_ui "https://github.com/patilshrutika1803/polaris/blob/main/frontend/src/pages/ShipNavigation.jsx"
click node_client_api "https://github.com/patilshrutika1803/polaris/blob/main/frontend/src/api/polarisApi.js"
click node_analysis_state "https://github.com/patilshrutika1803/polaris/blob/main/frontend/src/context/NavigationAnalysisContext.jsx"
click node_review_pages "https://github.com/patilshrutika1803/polaris/tree/main/frontend/src/pages"
click node_map_view "https://github.com/patilshrutika1803/polaris/blob/main/frontend/src/components/MapView.jsx"
click node_assistant "https://github.com/patilshrutika1803/polaris/blob/main/frontend/src/pages/AIAssistant.jsx"
click node_api_service "https://github.com/patilshrutika1803/polaris/blob/main/backend/main.py"
click node_feature_extraction "https://github.com/patilshrutika1803/polaris/blob/main/backend/services/feature_extractor.py"
click node_b15a_records "https://github.com/patilshrutika1803/polaris/blob/main/backend/B15A_Wanderer_2008.txt"
click node_trajectory_model "https://github.com/patilshrutika1803/polaris/blob/main/backend/predict.py"
click node_model_file "https://github.com/patilshrutika1803/polaris/blob/main/backend/iceberg_model.pkl"
click node_environment_service "https://github.com/patilshrutika1803/polaris/blob/main/backend/services/environment.py"
click node_glorys_data "https://github.com/patilshrutika1803/polaris/blob/main/backend/data/GLORYS12.nc"
click node_risk_engine "https://github.com/patilshrutika1803/polaris/blob/main/backend/services/risk_engine.py"
click node_route_optimizer "https://github.com/patilshrutika1803/polaris/blob/main/backend/services/navigation.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_navigation_ui,node_client_api,node_analysis_state,node_review_pages,node_map_view,node_assistant toneBlue
class node_api_service toneAmber
class node_feature_extraction,node_b15a_records,node_trajectory_model,node_model_file,node_environment_service,node_glorys_data toneMint
class node_risk_engine,node_route_optimizer toneRose
class node_operator,node_human_decision toneIndigo
```

## Components

### Interactive Review

- [Route Inputs](https://github.com/patilshrutika1803/polaris/blob/main/frontend/src/pages/ShipNavigation.jsx): `frontend/src/pages/ShipNavigation.jsx`
- [API Client](https://github.com/patilshrutika1803/polaris/blob/main/frontend/src/api/polarisApi.js): `frontend/src/api/polarisApi.js`
- [Analysis State](https://github.com/patilshrutika1803/polaris/blob/main/frontend/src/context/NavigationAnalysisContext.jsx): `frontend/src/context/NavigationAnalysisContext.jsx`
- [Review Pages](https://github.com/patilshrutika1803/polaris/tree/main/frontend/src/pages): `frontend/src/pages`
- [3D Map](https://github.com/patilshrutika1803/polaris/blob/main/frontend/src/components/MapView.jsx): `frontend/src/components/MapView.jsx`
- [AI Assistant](https://github.com/patilshrutika1803/polaris/blob/main/frontend/src/pages/AIAssistant.jsx): `frontend/src/pages/AIAssistant.jsx`

### Analysis API

- [FastAPI Analysis](https://github.com/patilshrutika1803/polaris/blob/main/backend/main.py): `backend/main.py`

### Forecast Inputs

- [Feature Extraction](https://github.com/patilshrutika1803/polaris/blob/main/backend/services/feature_extractor.py): `backend/services/feature_extractor.py`
- [B15A Records](https://github.com/patilshrutika1803/polaris/blob/main/backend/B15A_Wanderer_2008.txt): `backend/B15A_Wanderer_2008.txt`
- [Trajectory Prediction](https://github.com/patilshrutika1803/polaris/blob/main/backend/predict.py): `backend/predict.py`
- [Trained Model](https://github.com/patilshrutika1803/polaris/blob/main/backend/iceberg_model.pkl): `backend/iceberg_model.pkl`
- [Environmental Lookup](https://github.com/patilshrutika1803/polaris/blob/main/backend/services/environment.py): `backend/services/environment.py`
- [GLORYS12 Reference](https://github.com/patilshrutika1803/polaris/blob/main/backend/data/GLORYS12.nc): `backend/data/GLORYS12.nc`

### Risk And Routing

- [Proximity Risk](https://github.com/patilshrutika1803/polaris/blob/main/backend/services/risk_engine.py): `backend/services/risk_engine.py`
- [Route Optimizer](https://github.com/patilshrutika1803/polaris/blob/main/backend/services/navigation.py): `backend/services/navigation.py`

### Other components

- **Vessel Operator**
- **Human Decision**

## Connections

- Vessel Operator → Route Inputs: enters route inputs
- Route Inputs → API Client: requests analysis
- API Client → FastAPI Analysis: POST analysis
- FastAPI Analysis → Feature Extraction: extracts features
- Feature Extraction → B15A Records: reads records
- FastAPI Analysis → Trajectory Prediction: predicts trajectory
- Trajectory Prediction → Trained Model: loads model
- FastAPI Analysis → Environmental Lookup: looks up conditions
- Environmental Lookup → GLORYS12 Reference: reads dataset
- FastAPI Analysis → Proximity Risk: evaluates risk
- FastAPI Analysis → Route Optimizer: optimizes route
- Route Optimizer → Environmental Lookup: checks grid conditions
- FastAPI Analysis → API Client: returns analysis
- API Client → Route Inputs: normalizes result
- Route Inputs → Analysis State: stores analysis
- Analysis State → Review Pages: provides analysis
- Review Pages → 3D Map: renders visualization
- Review Pages → AI Assistant: shows explanations
- AI Assistant → Human Decision: supports review
- 3D Map → Human Decision: presents route