# sam3305/flysand architecture

> Architecture diagram of the GitHub repository sam3305/flysand, 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/sam3305/flysand
- Repository: https://github.com/sam3305/flysand

## Overview

FlySAND is an AI-operated airline platform combining customer booking, airline operations dashboards, physics-based cost modeling, dynamic pricing, and agent-driven decisions. The main workflow runs from flight search and seat booking through inventory updates and live operations; a separate pricing loop recalculates fares from weather, cost, demand, and ML signals. The README documents seeding, agent, and realtime capabilities not fully represented in sampled source, so those links follow its architecture description. Backend route wiring and physics dependencies are supported by sampled source.

Main entry points: [`backend/app/main.py`](https://github.com/sam3305/flysand/blob/main/backend/app/main.py) (API Application), [`backend/master_agent.py`](https://github.com/sam3305/flysand/blob/main/backend/master_agent.py) (Master Agent), [`backend/app/core/db.py`](https://github.com/sam3305/flysand/blob/main/backend/app/core/db.py) (MongoDB), [`backend/app/tasks/game_loop.py`](https://github.com/sam3305/flysand/blob/main/backend/app/tasks/game_loop.py) (Repricing Loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Customer and Ops UI"]
  node_booking_ui["Booking Portal<br/>[B2CPortal.tsx]"]
  node_ops_ui["Ops Dashboards<br/>[AOCCDashboard.tsx]"]
  node_orchestrator_ui["Agent Console"]
  node_live_hook["Live Flight Hook"]
end

subgraph group_api["Backend Runtime"]
  node_app["API Application<br/>[main.py]"]
  node_booking_api["Booking Route<br/>[booking.py]"]
  node_flights_api["Flight Routes<br/>[flights.py]"]
  node_dashboard_api["Dashboard Route<br/>[dashboard.py]"]
  node_orchestrator_api["Orchestrator Route<br/>[orchestrator.py]"]
  node_game_loop["Repricing Loop<br/>[game_loop.py]"]
  node_live_ops["Live Ops Socket<br/>[live_ops.py]"]
  node_seeding["Flight Seeding"]
end

subgraph group_pricing["Flight Economics"]
  node_physics["Aero Physics<br/>[physics_engine.py]"]
  node_weather["Weather Service<br/>[weather_service.py]"]
  node_thermo["Thermodynamics"]
  node_economics["Cost and Fare Model"]
  node_events["Demand Event Oracle<br/>[event_oracle.py]"]
  node_ml_pricing["ML Pricing"]
end

subgraph group_agents["AI Operations"]
  node_master["Master Agent<br/>[master_agent.py]"]
  node_yield_agent["Yield Agent<br/>[yield_manager.py]"]
  node_finance_agent["Finance Agent"]
  node_network_agent["Network Agent<br/>[network_planner.py]"]
  node_fuel_agent["Fuel Agent"]
  node_swarm["Booking Swarm<br/>[swarm.py]"]
end

subgraph group_state["State and Events"]
  node_mongo[("MongoDB<br/>[db.py]")]
  node_redis[("Redis Bus and Locks<br/>[redis_client.py]")]
end

node_traveler(("Traveler"))
node_operator(("Airline Operator"))
node_weather_provider(("Weather Provider"))

node_traveler -->|"searches and books"| node_booking_ui
node_booking_ui -->|"requests flights"| node_flights_api
node_booking_ui -->|"submits booking"| node_booking_api
node_operator -->|"views operations"| node_ops_ui
node_ops_ui -->|"requests flights"| node_flights_api
node_ops_ui -->|"requests metrics"| node_dashboard_api
node_operator -->|"requests agent run"| node_orchestrator_ui
node_orchestrator_ui -->|"dispatches request"| node_orchestrator_api
node_live_hook -->|"receives updates"| node_live_ops
node_app -->|"starts background loop"| node_game_loop
node_app -->|"registers route"| node_booking_api
node_app -->|"registers route"| node_flights_api
node_app -->|"registers route"| node_dashboard_api
node_app -->|"registers route"| node_orchestrator_api
node_app -->|"mounts socket"| node_live_ops
node_booking_api -->|"locks and publishes"| node_redis
node_booking_api -->|"updates inventory"| node_mongo
node_flights_api -->|"reads flights"| node_mongo
node_dashboard_api -->|"reads operations data"| node_mongo
node_seeding -.->|"computes route cost"| node_economics
node_seeding -.->|"stores flights"| node_mongo
node_physics -->|"fetches profile"| node_weather
node_physics -->|"calculates impact"| node_thermo
node_weather_provider -.->|"supplies conditions"| node_weather
node_economics -->|"uses fuel estimate"| node_physics
node_economics -->|"gets demand signals"| node_events
node_game_loop -->|"recalculates floor"| node_economics
node_game_loop -->|"applies pricing model"| node_ml_pricing
node_game_loop -->|"updates fares"| node_mongo
node_game_loop -->|"subscribes and publishes"| node_redis
node_live_ops -->|"relays events"| node_redis
node_orchestrator_api -->|"dispatches task"| node_master
node_master -->|"queries via MCP"| node_yield_agent
node_master -->|"queries via MCP"| node_finance_agent
node_master -->|"queries via MCP"| node_network_agent
node_master -->|"queries via MCP"| node_fuel_agent
node_master -->|"reads and commits"| node_mongo
node_swarm -.->|"submits bookings"| node_booking_api

click node_booking_ui "https://github.com/sam3305/flysand/blob/main/src/components/b2c/B2CPortal.tsx"
click node_ops_ui "https://github.com/sam3305/flysand/blob/main/src/components/b2b/AOCCDashboard.tsx"
click node_orchestrator_ui "https://github.com/sam3305/flysand/blob/main/src/components/ops/AgentOrchestratorPage.tsx"
click node_live_hook "https://github.com/sam3305/flysand/blob/main/src/hooks/useLiveFlightData.ts"
click node_app "https://github.com/sam3305/flysand/blob/main/backend/app/main.py"
click node_booking_api "https://github.com/sam3305/flysand/blob/main/backend/app/api/routes/booking.py"
click node_flights_api "https://github.com/sam3305/flysand/blob/main/backend/app/api/routes/flights.py"
click node_dashboard_api "https://github.com/sam3305/flysand/blob/main/backend/app/api/routes/dashboard.py"
click node_orchestrator_api "https://github.com/sam3305/flysand/blob/main/backend/app/api/routes/orchestrator.py"
click node_game_loop "https://github.com/sam3305/flysand/blob/main/backend/app/tasks/game_loop.py"
click node_live_ops "https://github.com/sam3305/flysand/blob/main/backend/app/websockets/live_ops.py"
click node_seeding "https://github.com/sam3305/flysand/tree/main/backend/pipeline"
click node_physics "https://github.com/sam3305/flysand/blob/main/backend/app/services/physics_engine.py"
click node_weather "https://github.com/sam3305/flysand/blob/main/backend/app/services/weather_service.py"
click node_thermo "https://github.com/sam3305/flysand/blob/main/backend/app/services/physics_engine_math.py"
click node_economics "https://github.com/sam3305/flysand/blob/main/backend/app/services/economics_engine.py"
click node_events "https://github.com/sam3305/flysand/blob/main/backend/app/services/event_oracle.py"
click node_ml_pricing "https://github.com/sam3305/flysand/blob/main/backend/app/engines/ml_pricing_model.py"
click node_master "https://github.com/sam3305/flysand/blob/main/backend/master_agent.py"
click node_yield_agent "https://github.com/sam3305/flysand/blob/main/backend/agents/yield_manager.py"
click node_finance_agent "https://github.com/sam3305/flysand/blob/main/backend/agents/finance_controller.py"
click node_network_agent "https://github.com/sam3305/flysand/blob/main/backend/agents/network_planner.py"
click node_fuel_agent "https://github.com/sam3305/flysand/blob/main/backend/agents/fuel_procurement.py"
click node_swarm "https://github.com/sam3305/flysand/blob/main/backend/agents/swarm.py"
click node_mongo "https://github.com/sam3305/flysand/blob/main/backend/app/core/db.py"
click node_redis "https://github.com/sam3305/flysand/blob/main/backend/app/core/redis_client.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_booking_ui,node_ops_ui,node_orchestrator_ui,node_live_hook toneBlue
class node_app,node_booking_api,node_flights_api,node_dashboard_api,node_orchestrator_api,node_game_loop,node_live_ops,node_seeding toneAmber
class node_physics,node_weather,node_thermo,node_economics,node_events,node_ml_pricing toneMint
class node_master,node_yield_agent,node_finance_agent,node_network_agent,node_fuel_agent,node_swarm toneRose
class node_mongo,node_redis,node_traveler,node_operator,node_weather_provider toneIndigo
```

## Components

### Customer and Ops UI

- [Booking Portal](https://github.com/sam3305/flysand/blob/main/src/components/b2c/B2CPortal.tsx): `src/components/b2c/B2CPortal.tsx`
- [Ops Dashboards](https://github.com/sam3305/flysand/blob/main/src/components/b2b/AOCCDashboard.tsx): `src/components/b2b/AOCCDashboard.tsx`
- [Agent Console](https://github.com/sam3305/flysand/blob/main/src/components/ops/AgentOrchestratorPage.tsx): `src/components/ops/AgentOrchestratorPage.tsx`
- [Live Flight Hook](https://github.com/sam3305/flysand/blob/main/src/hooks/useLiveFlightData.ts): `src/hooks/useLiveFlightData.ts`

### Backend Runtime

- [API Application](https://github.com/sam3305/flysand/blob/main/backend/app/main.py): `backend/app/main.py`
- [Booking Route](https://github.com/sam3305/flysand/blob/main/backend/app/api/routes/booking.py): `backend/app/api/routes/booking.py`
- [Flight Routes](https://github.com/sam3305/flysand/blob/main/backend/app/api/routes/flights.py): `backend/app/api/routes/flights.py`
- [Dashboard Route](https://github.com/sam3305/flysand/blob/main/backend/app/api/routes/dashboard.py): `backend/app/api/routes/dashboard.py`
- [Orchestrator Route](https://github.com/sam3305/flysand/blob/main/backend/app/api/routes/orchestrator.py): `backend/app/api/routes/orchestrator.py`
- [Repricing Loop](https://github.com/sam3305/flysand/blob/main/backend/app/tasks/game_loop.py): `backend/app/tasks/game_loop.py`
- [Live Ops Socket](https://github.com/sam3305/flysand/blob/main/backend/app/websockets/live_ops.py): `backend/app/websockets/live_ops.py`
- [Flight Seeding](https://github.com/sam3305/flysand/tree/main/backend/pipeline): `backend/pipeline`

### Flight Economics

- [Aero Physics](https://github.com/sam3305/flysand/blob/main/backend/app/services/physics_engine.py): `backend/app/services/physics_engine.py`
- [Weather Service](https://github.com/sam3305/flysand/blob/main/backend/app/services/weather_service.py): `backend/app/services/weather_service.py`
- [Thermodynamics](https://github.com/sam3305/flysand/blob/main/backend/app/services/physics_engine_math.py): `backend/app/services/physics_engine_math.py`
- [Cost and Fare Model](https://github.com/sam3305/flysand/blob/main/backend/app/services/economics_engine.py): `backend/app/services/economics_engine.py`
- [Demand Event Oracle](https://github.com/sam3305/flysand/blob/main/backend/app/services/event_oracle.py): `backend/app/services/event_oracle.py`
- [ML Pricing](https://github.com/sam3305/flysand/blob/main/backend/app/engines/ml_pricing_model.py): `backend/app/engines/ml_pricing_model.py`

### AI Operations

- [Master Agent](https://github.com/sam3305/flysand/blob/main/backend/master_agent.py): `backend/master_agent.py`
- [Yield Agent](https://github.com/sam3305/flysand/blob/main/backend/agents/yield_manager.py): `backend/agents/yield_manager.py`
- [Finance Agent](https://github.com/sam3305/flysand/blob/main/backend/agents/finance_controller.py): `backend/agents/finance_controller.py`
- [Network Agent](https://github.com/sam3305/flysand/blob/main/backend/agents/network_planner.py): `backend/agents/network_planner.py`
- [Fuel Agent](https://github.com/sam3305/flysand/blob/main/backend/agents/fuel_procurement.py): `backend/agents/fuel_procurement.py`
- [Booking Swarm](https://github.com/sam3305/flysand/blob/main/backend/agents/swarm.py): `backend/agents/swarm.py`

### State and Events

- [MongoDB](https://github.com/sam3305/flysand/blob/main/backend/app/core/db.py): `backend/app/core/db.py`
- [Redis Bus and Locks](https://github.com/sam3305/flysand/blob/main/backend/app/core/redis_client.py): `backend/app/core/redis_client.py`

### Other components

- **Traveler**
- **Airline Operator**
- **Weather Provider**

## Connections

- Traveler → Booking Portal: searches and books
- Booking Portal → Flight Routes: requests flights
- Booking Portal → Booking Route: submits booking
- Airline Operator → Ops Dashboards: views operations
- Ops Dashboards → Flight Routes: requests flights
- Ops Dashboards → Dashboard Route: requests metrics
- Airline Operator → Agent Console: requests agent run
- Agent Console → Orchestrator Route: dispatches request
- Live Flight Hook → Live Ops Socket: receives updates
- API Application → Repricing Loop: starts background loop
- API Application → Booking Route: registers route
- API Application → Flight Routes: registers route
- API Application → Dashboard Route: registers route
- API Application → Orchestrator Route: registers route
- API Application → Live Ops Socket: mounts socket
- Booking Route → Redis Bus and Locks: locks and publishes
- Booking Route → MongoDB: updates inventory
- Flight Routes → MongoDB: reads flights
- Dashboard Route → MongoDB: reads operations data
- Flight Seeding → Cost and Fare Model: computes route cost
- Flight Seeding → MongoDB: stores flights
- Aero Physics → Weather Service: fetches profile
- Aero Physics → Thermodynamics: calculates impact
- Weather Provider → Weather Service: supplies conditions
- Cost and Fare Model → Aero Physics: uses fuel estimate
- Cost and Fare Model → Demand Event Oracle: gets demand signals
- Repricing Loop → Cost and Fare Model: recalculates floor
- Repricing Loop → ML Pricing: applies pricing model
- Repricing Loop → MongoDB: updates fares
- Repricing Loop → Redis Bus and Locks: subscribes and publishes
- Live Ops Socket → Redis Bus and Locks: relays events
- Orchestrator Route → Master Agent: dispatches task
- Master Agent → Yield Agent: queries via MCP
- Master Agent → Finance Agent: queries via MCP
- Master Agent → Network Agent: queries via MCP
- Master Agent → Fuel Agent: queries via MCP
- Master Agent → MongoDB: reads and commits
- Booking Swarm → Booking Route: submits bookings