# raghav-305/freight-sih architecture

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

- Interactive diagram: https://gitdiagram.com/raghav-305/freight-sih
- Repository: https://github.com/raghav-305/freight-sih

## Overview

Freight Chartering Intelligence is a human-reviewed maritime procurement decision-support platform. Users provide cargo, route, vessel class, timing and contract requirements through the frontend; the FastAPI backend exposes analysis and recommendation capabilities, with results including forecasts, feasibility, vessel and contract recommendations, costs, savings and risk. The README documents the services-to-ML/optimization/database architecture and offline operating modes. The graph preserves major documented capabilities, but unsampled implementation details are represented at subsystem level rather than connected speculatively.

Main entry points: [`backend/app/main.py`](https://github.com/raghav-305/freight-sih/blob/main/backend/app/main.py) (FastAPI boundary), [`frontend/src/main.tsx`](https://github.com/raghav-305/freight-sih/blob/main/frontend/src/main.tsx) (Decision workspace), [`backend/app/api/charter.py`](https://github.com/raghav-305/freight-sih/blob/main/backend/app/api/charter.py) (Charter recommendation), [`backend/app/api/market.py`](https://github.com/raghav-305/freight-sih/blob/main/backend/app/api/market.py) (Market intelligence)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_frontend["Decision workspace<br/>[main.tsx]"]
end

subgraph group_api["API capabilities"]
  node_fastapi["FastAPI boundary<br/>[main.py]"]
  node_chartering["Charter recommendation<br/>[charter.py]"]
  node_forecast["Freight forecasts<br/>[forecast.py]"]
  node_market["Market intelligence<br/>[market.py]"]
  node_vessel["Vessel intelligence<br/>[vessels.py]"]
  node_eligibility["Constraint eligibility<br/>[eligibility.py]"]
  node_risk["Risk intelligence<br/>[risk.py]"]
  node_scenarios["Scenario analysis<br/>[scenarios.py]"]
  node_counterfactual["Counterfactuals<br/>[counterfactual.py]"]
  node_map["Maritime map<br/>[map.py]"]
  node_collusion["Bid anomaly review<br/>[collusion.py]"]
  node_contracts["Charterparty studio<br/>[charterparty.py]"]
  node_quality["Data quality<br/>[data_quality.py]"]
end

subgraph group_decision["Decision engines"]
  node_portfolio["Charter optimization"]
  node_marketml["Market inference"]
end

subgraph group_data["Data and operations"]
  node_ais["Live AIS tracking<br/>[ais_tracker.py]"]
  node_database[("Operational database<br/>[models.py]")]
  node_freightdata[("Freight data store<br/>[freight_store.py]")]
end

node_user(("Chartering user"))
node_externalais(("AIS feed"))

node_user -->|"submits requirements"| node_frontend
node_frontend -->|"requests analysis"| node_fastapi
node_fastapi -->|"routes requests"| node_chartering
node_fastapi -->|"routes requests"| node_forecast
node_fastapi -->|"routes requests"| node_market
node_fastapi -->|"routes requests"| node_vessel
node_fastapi -->|"routes requests"| node_eligibility
node_fastapi -->|"routes requests"| node_risk
node_fastapi -->|"routes requests"| node_scenarios
node_fastapi -->|"routes requests"| node_counterfactual
node_fastapi -->|"routes requests"| node_map
node_fastapi -->|"routes requests"| node_collusion
node_fastapi -->|"routes requests"| node_contracts
node_fastapi -->|"routes requests"| node_quality
node_chartering -.->|"optimizes charter"| node_portfolio
node_market -.->|"uses inference"| node_marketml
node_fastapi -->|"starts ingestion"| node_ais
node_externalais -.->|"supplies positions"| node_ais
node_fastapi -.->|"uses persistence"| node_database
node_fastapi -->|"reads freight status"| node_freightdata
node_database -.->|"stores freight data"| node_freightdata

click node_frontend "https://github.com/raghav-305/freight-sih/blob/main/frontend/src/main.tsx"
click node_fastapi "https://github.com/raghav-305/freight-sih/blob/main/backend/app/main.py"
click node_chartering "https://github.com/raghav-305/freight-sih/blob/main/backend/app/api/charter.py"
click node_forecast "https://github.com/raghav-305/freight-sih/blob/main/backend/app/api/forecast.py"
click node_market "https://github.com/raghav-305/freight-sih/blob/main/backend/app/api/market.py"
click node_vessel "https://github.com/raghav-305/freight-sih/blob/main/backend/app/api/vessels.py"
click node_eligibility "https://github.com/raghav-305/freight-sih/blob/main/backend/app/api/eligibility.py"
click node_risk "https://github.com/raghav-305/freight-sih/blob/main/backend/app/api/risk.py"
click node_scenarios "https://github.com/raghav-305/freight-sih/blob/main/backend/app/api/scenarios.py"
click node_counterfactual "https://github.com/raghav-305/freight-sih/blob/main/backend/app/api/counterfactual.py"
click node_portfolio "https://github.com/raghav-305/freight-sih/blob/main/data/charter_strategy/optimize_charter.py"
click node_marketml "https://github.com/raghav-305/freight-sih/blob/main/ml/inference/market_intelligence.py"
click node_ais "https://github.com/raghav-305/freight-sih/blob/main/backend/app/services/ais_tracker.py"
click node_map "https://github.com/raghav-305/freight-sih/blob/main/backend/app/api/map.py"
click node_collusion "https://github.com/raghav-305/freight-sih/blob/main/backend/app/api/collusion.py"
click node_contracts "https://github.com/raghav-305/freight-sih/blob/main/backend/app/api/charterparty.py"
click node_quality "https://github.com/raghav-305/freight-sih/blob/main/backend/app/api/data_quality.py"
click node_database "https://github.com/raghav-305/freight-sih/blob/main/backend/app/database/models.py"
click node_freightdata "https://github.com/raghav-305/freight-sih/blob/main/backend/app/database/freight_store.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_frontend,node_user toneBlue
class node_fastapi,node_chartering,node_forecast,node_market,node_vessel,node_eligibility,node_risk,node_scenarios,node_counterfactual,node_map,node_collusion,node_contracts,node_quality toneAmber
class node_portfolio,node_marketml toneMint
class node_ais,node_database,node_freightdata toneRose
class node_externalais toneIndigo
```

## Components

### User experience

- [Decision workspace](https://github.com/raghav-305/freight-sih/blob/main/frontend/src/main.tsx): `frontend/src/main.tsx`

### API capabilities

- [FastAPI boundary](https://github.com/raghav-305/freight-sih/blob/main/backend/app/main.py): `backend/app/main.py`
- [Charter recommendation](https://github.com/raghav-305/freight-sih/blob/main/backend/app/api/charter.py): `backend/app/api/charter.py`
- [Freight forecasts](https://github.com/raghav-305/freight-sih/blob/main/backend/app/api/forecast.py): `backend/app/api/forecast.py`
- [Market intelligence](https://github.com/raghav-305/freight-sih/blob/main/backend/app/api/market.py): `backend/app/api/market.py`
- [Vessel intelligence](https://github.com/raghav-305/freight-sih/blob/main/backend/app/api/vessels.py): `backend/app/api/vessels.py`
- [Constraint eligibility](https://github.com/raghav-305/freight-sih/blob/main/backend/app/api/eligibility.py): `backend/app/api/eligibility.py`
- [Risk intelligence](https://github.com/raghav-305/freight-sih/blob/main/backend/app/api/risk.py): `backend/app/api/risk.py`
- [Scenario analysis](https://github.com/raghav-305/freight-sih/blob/main/backend/app/api/scenarios.py): `backend/app/api/scenarios.py`
- [Counterfactuals](https://github.com/raghav-305/freight-sih/blob/main/backend/app/api/counterfactual.py): `backend/app/api/counterfactual.py`
- [Maritime map](https://github.com/raghav-305/freight-sih/blob/main/backend/app/api/map.py): `backend/app/api/map.py`
- [Bid anomaly review](https://github.com/raghav-305/freight-sih/blob/main/backend/app/api/collusion.py): `backend/app/api/collusion.py`
- [Charterparty studio](https://github.com/raghav-305/freight-sih/blob/main/backend/app/api/charterparty.py): `backend/app/api/charterparty.py`
- [Data quality](https://github.com/raghav-305/freight-sih/blob/main/backend/app/api/data_quality.py): `backend/app/api/data_quality.py`

### Decision engines

- [Charter optimization](https://github.com/raghav-305/freight-sih/blob/main/data/charter_strategy/optimize_charter.py): `data/charter_strategy/optimize_charter.py`
- [Market inference](https://github.com/raghav-305/freight-sih/blob/main/ml/inference/market_intelligence.py): `ml/inference/market_intelligence.py`

### Data and operations

- [Live AIS tracking](https://github.com/raghav-305/freight-sih/blob/main/backend/app/services/ais_tracker.py): `backend/app/services/ais_tracker.py`
- [Operational database](https://github.com/raghav-305/freight-sih/blob/main/backend/app/database/models.py): `backend/app/database/models.py`
- [Freight data store](https://github.com/raghav-305/freight-sih/blob/main/backend/app/database/freight_store.py): `backend/app/database/freight_store.py`

### Other components

- **Chartering user**
- **AIS feed**

## Connections

- Chartering user → Decision workspace: submits requirements
- Decision workspace → FastAPI boundary: requests analysis
- FastAPI boundary → Charter recommendation: routes requests (evidence: `backend/app/main.py`)
- FastAPI boundary → Freight forecasts: routes requests (evidence: `backend/app/main.py`)
- FastAPI boundary → Market intelligence: routes requests (evidence: `backend/app/main.py`)
- FastAPI boundary → Vessel intelligence: routes requests (evidence: `backend/app/main.py`)
- FastAPI boundary → Constraint eligibility: routes requests (evidence: `backend/app/main.py`)
- FastAPI boundary → Risk intelligence: routes requests (evidence: `backend/app/main.py`)
- FastAPI boundary → Scenario analysis: routes requests (evidence: `backend/app/main.py`)
- FastAPI boundary → Counterfactuals: routes requests (evidence: `backend/app/main.py`)
- FastAPI boundary → Maritime map: routes requests (evidence: `backend/app/main.py`)
- FastAPI boundary → Bid anomaly review: routes requests (evidence: `backend/app/main.py`)
- FastAPI boundary → Charterparty studio: routes requests (evidence: `backend/app/main.py`)
- FastAPI boundary → Data quality: routes requests (evidence: `backend/app/main.py`)
- Charter recommendation → Charter optimization: optimizes charter
- Market intelligence → Market inference: uses inference
- FastAPI boundary → Live AIS tracking: starts ingestion (evidence: `backend/app/main.py`)
- AIS feed → Live AIS tracking: supplies positions
- FastAPI boundary → Operational database: uses persistence
- FastAPI boundary → Freight data store: reads freight status
- Operational database → Freight data store: stores freight data