OpenSquawk/CLAUDE.md

OpenSquawk - Project Guide

Architecture

• Nuxt 4 (Vue 3 SFC) frontend in /app
• H3 server handlers in /server
• Shared types/utils in /shared
• MongoDB models in /server/models

Key Files

• /shared/utils/communicationsEngine.ts — Core state machine composable (used by /pm live ATC)
• /server/utils/openai.ts — LLM decision router (routeDecision())
• /server/services/decisionFlowService.ts — Builds runtime decision trees from MongoDB
• /app/pages/pm.vue — Live ATC page (speech-to-text, PTT, text input)
• /app/pages/classroom.vue — Classroom learning mode (separate system, does NOT use communicationsEngine)

Live ATC Flow (/pm)

1. User inputs (PTT or text) → handlePilotTransmission()
2. processPilotTransmission() logs the pilot message
3. buildLLMContext() builds candidates from nextCandidates
4. POST /api/llm/decide → routeDecision() selects next state
5. applyLLMDecision() moves to next state, updates vars/flags
6. collectAtcStatesUntilPilotTurn() advances through ATC/system states
7. Each ATC say_tpl is spoken via TTS (scheduleControllerSpeech)

Decision Tree States

States have role: 'pilot' | 'atc' | 'system'. ATC states have say_tpl (what controller says). Pilot states have utterance_tpl (expected pilot response). Transitions: next, ok_next, bad_next, timer_next.

Commands

• bun run dev — dev server
• Decision trees are stored in MongoDB and fetched via /api/decision-flows/runtime