System Architecture
How VibePilot Is Built
Seven operational layers. No layer activates until the one beneath it is stable. Controller behavior emerges only after spatial certainty is established.
01Simulator Intake
Operational
Raw simulator transport and metadata normalisation. UDP socket payload
received from X-Plane, validated, and mapped to internal field names.
NetworkService
Receives simulator UDP frames and forwards validated telemetry
internally.
→
XPlaneMetadataBridge
Extracts simulator metadata such as aircraft identity and
environment context.
Receives: UDP Payload
latitude float
longitude float
heading_true float
groundspeed float
altitude_msl float
vertical_speed float
on_ground bool
sim_time float
Emits: AircraftStateRaw
lat float
lon float
headingTrue float
groundspeedKt float
altitudeFt float
verticalSpeedFpm float
onGround bool
timestamp float
AircraftStateRaw
↓
02Aircraft State Construction
Operational
Constructs a stable, continuous operational aircraft object. First
continuity layer, preserving previous sample for delta calculations.
AircraftState
First normalized aircraft object combining raw motion and
simulator metadata.
→
.fromTelemetry()
Constructs the operational AircraftState object from normalized
telemetry input.
Receives: AircraftStateRaw
lat, lon
headingTrue
groundspeedKt
altitudeFt
verticalSpeedFpm
onGround
timestamp
Emits: AircraftState
position {lat,lon}
heading float
track float
groundspeed float
altitude float
onGround bool
previousPosition {lat,lon}
deltaTime float
AircraftState
↓
03Geometry Core
Operational
Converts aircraft state into runway-relative geometry. This is the first
layer where runway relation becomes measurable, continuously fed by Layer 04 runway candidates.
GeoMath
Provides low-level spatial calculations used across geometry and
runway logic.
→
GeoCalculator
Derives headings, distances, bearings and positional
deltas.
→
MagneticModel
Converts true bearings into local magnetic reference.
→
RunwayHeadingResolver
Aligns aircraft track against runway magnetic heading
families.
Receives
AircraftState
RunwayCandidateSet ← L04
Emits: GeometryState
distanceToThreshold
bearingToThreshold
crossTrackMeters
alongTrackMeters
headingDelta
alignedRunways[]
GeometryState
↓
04Reference Dataset Layer
Operational
Persistent runway reference layer supplying geometry and runway intelligence
with spatial runway context.
AptDatLoader
Parses X-Plane apt.dat runway definitions into structured
memory.
→
RunwayRepository
Persistent runway dataset used by all higher runway logic.
→
RunwayFamilyIndex
Groups reciprocal runways into operational families.
→
AirportSpatialIndex
Fast lookup structure for nearby airport geometry.
Receives: Context Request
aircraft position
search radius
Emits: RunwayCandidateSet
runwayId
thresholdA {lat,lon}
thresholdB {lat,lon}
heading
length, width
airportIcao
RunwayCandidateSet
↓
05RISEngine: Runway Intelligence
Operational
Converts geometry into runway intent. RISEngine orchestrates the call chain.
ApproachCorridorDetector and RunwayLateralDetector are sibling branches that both feed
RunwayIntentPredictor after phase is resolved.
RISEngine
Central runway-intelligence orchestrator resolving runway
intent.
→
RunwayPhaseResolver
Determines whether aircraft is approach, rollout, or airborne
relative to runway.
→
ApproachCorridorDetector
Measures corridor alignment before runway threshold
entry.
branch
RunwayLateralDetector
Tracks lateral displacement relative to runway
centerline.
→
ApproachStabilityMonitor
Evaluates approach continuity before intent confirmation.
→
RunwayIntentPredictor
Predicts target runway before physical threshold crossing.
Receives
AircraftState
GeometryState
RunwayCandidateSet ← L04
Emits: RunwayIntentState
assignedRunway
phase
stableApproach bool
lateralConfidence float
occupancyPrediction
RunwayIntentState
↓
06Surface
Interpretation
In Progress
Extends runway intelligence into ground operations through parallel surface
detectors resolved under SurfaceIntentResolver.
RunwayIntentPredictor
Predicts target runway before physical threshold crossing.
→
LineupDetector
Detects deliberate runway entry for departure
positioning.
parallel
RunwayCrossingDetector
Identifies lateral runway traversal without departure
intent.
·
BacktrackDetector
Detects reverse runway movement after entry.
·
DepartureRollDetector
Confirms acceleration consistent with takeoff roll.
Receives
RunwayIntentState
AircraftState
Emits: SurfaceState
surfaceIntent
lineup bool
crossing bool
backtrack bool
departureRoll bool
SurfaceState
↓
07ATC
Controller Decision
Planned
Controller roles derive clearances only after runway certainty and spatial
confidence are established in lower layers.
GroundController
Future role responsible for taxi clearances, crossings and
surface sequencing.
roles
TowerController
Future role handling departures, landings and runway occupancy
decisions.
·
ApproachController
Future role managing arrivals before tower handoff and runway
assignment continuity.
→
PhraseologyLayer
Future phrase construction layer converting decisions into
standard ATC language.
→
VoiceRenderer
Future phraseology layer converting operational decisions into ATC
voice output.
Receives
RunwayIntentState
SurfaceState
traffic state (future)
Emits: Clearance
clearanceType
assignedRunway
phraseology string
voice audio
e.g. CLEARED TO LAND RWY 28R
Signal Flow
operational
in progress
planned
cross-layer ref
Live Signal Trace
[01]lat=-23.4352
lon=-46.4721 hdg=281° gs=142kt alt=2840ft vs=-680fpm onGround=false
[02]AircraftState.fromTelemetry() → heading=281° track=279° deltaTime=0.10s
previousPosition=(-23.4350,-46.4719)
[03]GeoMath→GeoCalculator: xtrack=-12m alongtrack=4.8nm distToThreshold=4.8nm
headingDelta=1.2°
[04]AirportSpatialIndex: candidates=38 → RunwayFamilyIndex: aligned=[28L,28R]
thresholdA=(-23.4312,-46.4698)
[05]RISEngine:
phase=FINAL_APPROACH corridor=VALID lateral=STABLE stableApproach=true
lateralConfidence=0.94
[06]SurfaceIntentResolver: intent=APPROACH lineup=false crossing=false
backtrack=false departureRoll=false
[07]assignedRunway=28R clearance=PENDING. Phraseology layer not yet
active