Stellar Air — NOVA Platform Architecture

SYSTEM ARCHITECTURE

End-to-end view: Vue UI → Kong gateway (optional) → FastAPI → MCP servers → live and scenario data sources. Langfuse (separate shared cluster) traces every agent run and tool call.

Live API Scenario data MCP protocol

MCP SERVER TOPOLOGY

Three servers scoped by access domain. Each exposes tools, resources, and prompts. FCE connects to shared + passenger. Handover connects to shared + ops.

Shared server Ops server Passenger server

── solid = tool calls ╌╌ dashed = resource reads ··· dotted = prompt gets

FCE AGENT — BEHIND EVERY DEPARTURE

Passenger notification agent. Triages flight status, gathers context from 5 parallel tool calls (including live weather and FAA data), synthesizes an empathetic notification.

SHIFT HANDOVER AGENT

Ops briefing agent. Scans all hubs in parallel, scores issues by severity × time sensitivity, categorizes into IMMEDIATE / MONITOR / FYI, generates a structured brief.

DATA FLOW — REAL vs MOCK

Weather and FAA airport status are live (no API key). Flight, crew, passenger, and maintenance data are scenario-based fixtures switchable from the UI.

Live data (no API key) Scenario data (switchable)

DEPLOYMENT

Kind cluster for dev (Tilt), docker-compose for EC2 production (nova-api + nova-ui on shared gateway network). Woodpecker CI builds images on push to main. EC2 nginx proxies stellarair.mcrn.ar → container; Kong Konnect available as optional governance layer.

REPOSITORY STRUCTURE

Monorepo: MCP servers, agents, IRROP engine, API, Vue UI (with shared component framework), and deployment configs.

stellar-ops/
├── mcp_servers/
│   ├── shared/              server.py · tools.py · resources.py · prompts.py
│   │   └── tools: get_route_weather · get_hub_forecasts · get_airport_status
│   │             get_flight_status · get_flight_details · get_irregular_ops
│   │             get_airport_congestion · get_maintenance_flags
│   ├── ops/                 server.py · tools.py · resources.py · prompts.py
│   │   └── tools: get_crew_notes · get_crew_duty_status · get_pending_rebookings
│   │             generate_narrative
│   ├── passenger/           server.py · tools.py · resources.py · prompts.py
│   │   └── tools: generate_notification
│   ├── shared_llm.py         multi-provider: Groq · Anthropic · Bedrock · OpenAI
│   └── data/
│       ├── models.py         FlightData · CrewMember · Passenger · MELItem · HubInfo
│       ├── real/             openmeteo.py · faa.py
│       └── scenarios/        normal_ops · weather_disruption_ord
│                             maintenance_delay_sfo · crew_swap_ewr
├── agents/
│   ├── fce.py                FCE — "Behind Every Departure" (passenger notifications)
│   ├── handover.py           Shift Handover (ops brief: IMMEDIATE / MONITOR / FYI)
│   └── shared/
│       ├── mcp_client.py     MCPMultiClient + connect_servers context manager
│       ├── parser.py         parse_tool_result · parse_resource_result · parse_prompt_result
│       └── tool_runner.py    build_tool_caller — timeout · Langfuse span · error collection
├── api/
│   ├── main.py               FastAPI: agents, scenarios, WebSocket, /health, Langfuse traces
│   └── config.py             Pydantic Settings — centralized env var reads
├── ui/
│   ├── framework/            soleprint-ui (shared component library)
│   └── app/                  Vue 3 SPA — Operations · Internals · Data · Settings
│       └── src/config.ts     Kong proxy URL + API/WS base
├── ctrl/
│   ├── Dockerfile.api/ui     Container builds
│   ├── nginx.conf            UI nginx (proxies /agents /scenarios /config /health /ws)
│   ├── k8s/                  base/ + overlays/dev/ (Kustomize)
│   ├── Tiltfile              Dev environment (Kind cluster: unt)
│   ├── edge/                 Production docker-compose (nova-api + nova-ui on gateway net)
│   └── deploy.sh             rsync (bypass CI) · edge (pull registry images)
├── tests/                  69 tests: models · clients · MCP · scenarios · agents
│   └── base.py               dual-mode: inprocess (default) · live (CONTRACT_TEST_MODE=live)
├── .woodpecker/            CI pipeline — build API + UI, push to registry.mcrn.ar
├── docs/                   Architecture graphs (this page)
└── .mcp.json                 Claude Code integration — 3 servers