mirror of
https://github.com/OpenSquawk/OpenSquawk
synced 2026-08-13 13:15:42 +08:00
31 lines
1.5 KiB
Markdown
31 lines
1.5 KiB
Markdown
# 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`
|