Skip to content

Latest commit

 

History

History
644 lines (525 loc) · 13.8 KB

README.md

File metadata and controls

644 lines (525 loc) · 13.8 KB

MsfsDebrief Architecture Documentation

This document provides visual architecture diagrams for the MsfsDebrief project using Mermaid.

Table of Contents

High-Level Architecture

graph TB
    subgraph "Microsoft Flight Simulator"
        MSFS[MSFS 2020/2024]
        SC[SimConnect API]
    end

    subgraph "MsfsDebrief Application"
        subgraph "MsfsDebrief.Win"
            UI[Windows Forms UI]
            SCC[SimConnect Client]
            MCC[MCP Client]
        end
        
        subgraph "MsfsDebrief.Core"
            TM[Telemetry Manager]
            PSM[Phase State Machine]
            ED[Event Detector]
            SC2[Scoring Engine]
            FR[Flight Recorder]
            DB[(SQLite Database)]
        end
        
        subgraph "MsfsDebrief.Mcp"
            MCP[MCP Server]
            TOOLS[Flight Tools]
            PROMPTS[Prompt Templates]
            RES[Resources]
        end
    end

    subgraph "AI Integration"
        CLAUDE[Claude Desktop]
        OTHER[Other AI Assistants]
    end

    MSFS --> SC
    SC --> SCC
    SCC --> TM
    TM --> PSM
    TM --> ED
    TM --> FR
    PSM --> ED
    ED --> SC2
    FR --> DB
    SC2 --> DB
    
    UI --> SCC
    UI --> TM
    UI --> DB
    
    MCP --> DB
    TOOLS --> DB
    MCC --> MCP
    
    CLAUDE --> MCP
    OTHER --> MCP

    style MSFS fill:#0078d4,color:#fff
    style UI fill:#68217a,color:#fff
    style MCP fill:#00a67d,color:#fff
    style DB fill:#f39c12,color:#fff
Loading

Component Diagram

graph LR
    subgraph "Core Library"
        direction TB
        
        subgraph Models
            TS[TelemetrySample]
            FE[FlightEvent]
            FP[FlightPhase]
            AP[AircraftProfile]
        end
        
        subgraph "State Machine"
            FSM[FlightPhaseStateMachine]
            PT[PhaseThresholds]
            PTR[PhaseTransition]
        end
        
        subgraph Events
            FED[FlightEventDetector]
            EDS[EventDetectorSettings]
            LED[LiftoffEventData]
            TED[TouchdownEventData]
        end
        
        subgraph Scoring
            LS[LandingScorer]
            TOS[TakeoffScorer]
            PS[PatternScorer]
            FS[FlightScorer]
        end
        
        subgraph Persistence
            FRC[FlightRecorder]
            FRG[FlightRecording]
            CSV[CsvTelemetryWriter]
            SFR[SqliteFlightRepository]
        end
        
        subgraph Profiles
            APR[AircraftProfileRepository]
            DP[DefaultProfiles]
        end
    end

    TS --> FSM
    TS --> FED
    FSM --> FED
    FED --> LS
    FED --> TOS
    TS --> FRC
    FRC --> CSV
    FRC --> SFR
    AP --> PT
    AP --> EDS
Loading

Data Flow

sequenceDiagram
    participant MSFS as MSFS
    participant SC as SimConnect
    participant Client as SimConnectClient
    participant Recorder as FlightRecorder
    participant PSM as PhaseStateMachine
    participant Detector as EventDetector
    participant Scorer as Scorer
    participant DB as Database
    participant UI as UI

    MSFS->>SC: Telemetry Data
    SC->>Client: OnRecvSimobjectData
    Client->>Recorder: AddSample(TelemetrySample)
    
    par Parallel Processing
        Recorder->>PSM: Update(sample)
        PSM-->>Recorder: PhaseTransition?
        
        Recorder->>Detector: Detect(sample, phase)
        Detector-->>Recorder: FlightEvent[]
    end
    
    Recorder->>UI: OnSampleAdded
    Recorder->>UI: OnPhaseChanged
    Recorder->>UI: OnEventDetected
    
    Note over Recorder,DB: On Recording Stop
    
    Recorder->>Scorer: ScoreFlight(recording)
    Scorer-->>Recorder: FlightScores
    
    Recorder->>DB: SaveFlight(recording, scores)
    Recorder->>UI: OnRecordingStopped
Loading

Flight Phase State Machine

stateDiagram-v2
    [*] --> Preflight: Engine Off
    
    Preflight --> EngineStart: Engine Starting
    EngineStart --> Taxi: Engine Running & Ground
    
    Taxi --> TakeoffRoll: Throttle Up & Speed > 30kts
    TakeoffRoll --> InitialClimb: Weight Off Wheels
    
    InitialClimb --> Climb: AGL > 500ft
    Climb --> Cruise: VS < 300fpm & Level
    
    Cruise --> Descent: VS < -500fpm
    Cruise --> Climb: VS > 500fpm
    
    Descent --> Approach: AGL < 3000ft
    Descent --> Climb: VS > 500fpm
    
    Approach --> Final: AGL < 500ft & Gear Down
    Approach --> Climb: Go-Around (Full Power)
    
    Final --> Landing: Touchdown
    Final --> Climb: Go-Around
    
    Landing --> Rollout: On Ground
    
    Rollout --> TakeoffRoll: Touch & Go
    Rollout --> TaxiIn: Speed < 10kts
    
    TaxiIn --> Shutdown: Engine Off
    TaxiIn --> Taxi: Moving to Runway
    
    Shutdown --> [*]

    note right of Preflight
        Aircraft cold & dark
        or parked with engine off
    end note

    note right of Landing
        Single frame event
        at touchdown moment
    end note

    note right of Rollout
        Decelerating on runway
        after touchdown
    end note
Loading

Event Detection Pipeline

flowchart TB
    subgraph Input
        TS[TelemetrySample]
        PH[Current Phase]
        PREV[Previous Sample]
    end

    subgraph "Event Detectors"
        subgraph "Takeoff Events"
            LO[Liftoff Detector]
            ROT[Rotation Detector]
        end
        
        subgraph "Landing Events"
            TD[Touchdown Detector]
            BNC[Bounce Detector]
            GA[Go-Around Detector]
        end
        
        subgraph "Configuration Events"
            GR[Gear Change Detector]
            FL[Flaps Change Detector]
            LT[Lights Change Detector]
        end
        
        subgraph "Warning Events"
            STL[Stall Warning]
            OVS[Overspeed Warning]
            BNK[Bank Limit Warning]
        end
    end

    subgraph Output
        EVT[FlightEvent]
        DATA[Event Data]
    end

    TS --> LO & TD & GR & STL
    PH --> LO & TD & GR & STL
    PREV --> LO & TD & GR & STL
    
    LO --> EVT
    ROT --> EVT
    TD --> EVT
    BNC --> EVT
    GA --> EVT
    GR --> EVT
    FL --> EVT
    LT --> EVT
    STL --> EVT
    OVS --> EVT
    BNK --> EVT
    
    EVT --> DATA

    style EVT fill:#00a67d,color:#fff
Loading

Scoring System

flowchart LR
    subgraph "Flight Recording"
        SAMPLES[Telemetry Samples]
        EVENTS[Flight Events]
        PHASES[Phase Transitions]
    end

    subgraph "Scoring Engines"
        direction TB
        
        subgraph "Landing Scorer"
            LS_TD[Touchdown Rate<br/>30%]
            LS_CL[Centerline<br/>20%]
            LS_AS[Approach Speed<br/>20%]
            LS_FL[Flare Technique<br/>15%]
            LS_TZ[Touchdown Zone<br/>15%]
        end
        
        subgraph "Takeoff Scorer"
            TS_RS[Rotation Speed<br/>25%]
            TS_DC[Directional Control<br/>25%]
            TS_IC[Initial Climb<br/>25%]
            TS_CF[Configuration<br/>25%]
        end
        
        subgraph "Pattern Scorer"
            PS_AL[Altitude<br/>30%]
            PS_SP[Speed Control<br/>30%]
            PS_BK[Bank Angles<br/>20%]
            PS_TM[Timing<br/>20%]
        end
    end

    subgraph "Overall Score"
        WEIGHT[Weighted Average]
        GRADE[Letter Grade]
    end

    SAMPLES --> LS_TD & TS_RS & PS_AL
    EVENTS --> LS_TD & TS_RS
    PHASES --> PS_AL
    
    LS_TD & LS_CL & LS_AS & LS_FL & LS_TZ --> WEIGHT
    TS_RS & TS_DC & TS_IC & TS_CF --> WEIGHT
    PS_AL & PS_SP & PS_BK & PS_TM --> WEIGHT
    
    WEIGHT --> GRADE

    style GRADE fill:#f39c12,color:#fff
Loading

Grade Calculation

flowchart LR
    SCORE[Numeric Score<br/>0-100] --> CHECK{Score Range}
    
    CHECK -->|97-100| AP[A+]
    CHECK -->|93-96| A[A]
    CHECK -->|90-92| AM[A-]
    CHECK -->|87-89| BP[B+]
    CHECK -->|83-86| B[B]
    CHECK -->|80-82| BM[B-]
    CHECK -->|77-79| CP[C+]
    CHECK -->|73-76| C[C]
    CHECK -->|70-72| CM[C-]
    CHECK -->|67-69| DP[D+]
    CHECK -->|63-66| D[D]
    CHECK -->|60-62| DM[D-]
    CHECK -->|<60| F[F]

    style AP fill:#22c55e,color:#fff
    style A fill:#22c55e,color:#fff
    style AM fill:#22c55e,color:#fff
    style BP fill:#84cc16,color:#fff
    style B fill:#84cc16,color:#fff
    style BM fill:#84cc16,color:#fff
    style CP fill:#eab308,color:#fff
    style C fill:#eab308,color:#fff
    style CM fill:#eab308,color:#fff
    style DP fill:#f97316,color:#fff
    style D fill:#f97316,color:#fff
    style DM fill:#f97316,color:#fff
    style F fill:#ef4444,color:#fff
Loading

MCP Integration

flowchart TB
    subgraph "AI Client"
        CLAUDE[Claude Desktop]
        MSG[User Message]
    end

    subgraph "MCP Server"
        SERVER[MsfsDebrief.Mcp]
        
        subgraph Tools
            T1[ListFlights]
            T2[GetFlight]
            T3[GetFlightSummary]
            T4[GetFlightEvents]
            T5[GetFlightPhases]
            T6[GetFlightScores]
            T7[GetLandingDetails]
            T8[GetTakeoffDetails]
            T9[GetAircraftProfile]
            T10[ListAircraftProfiles]
            T11[GetLatestFlight]
            T12[SearchFlights]
        end
        
        subgraph Prompts
            P1[AnalyzeLanding]
            P2[AnalyzeTakeoff]
            P3[AnalyzePattern]
            P4[GenerateDebrief]
            P5[SuggestImprovements]
            P6[CompareLandings]
            P7[ExplainScore]
        end
        
        subgraph Resources
            R1[flights://latest]
            R2[flights://list]
            R3[profiles://list]
        end
    end

    subgraph "Data Layer"
        DB[(SQLite Database)]
        PROFILES[Aircraft Profiles]
    end

    CLAUDE --> MSG
    MSG --> SERVER
    
    SERVER --> T1 & T2 & T3
    SERVER --> P1 & P2 & P3
    SERVER --> R1 & R2 & R3
    
    T1 & T2 & T3 --> DB
    T9 & T10 --> PROFILES

    style CLAUDE fill:#00a67d,color:#fff
    style SERVER fill:#68217a,color:#fff
    style DB fill:#f39c12,color:#fff
Loading

Database Schema

erDiagram
    FLIGHTS {
        string Id PK
        datetime StartTime
        datetime EndTime
        string AircraftTitle
        string AircraftId
        string DepartureIcao
        string ArrivalIcao
        string ProfileId FK
        int SampleCount
        float DurationMinutes
        float DistanceNm
    }
    
    FLIGHT_PHASES {
        int Id PK
        string FlightId FK
        string Phase
        datetime StartTime
        datetime EndTime
        float DurationSeconds
    }
    
    FLIGHT_EVENTS {
        int Id PK
        string FlightId FK
        string EventType
        datetime Timestamp
        string Data
    }
    
    FLIGHT_SCORES {
        string FlightId PK
        float OverallScore
        string OverallGrade
        float TakeoffScore
        float LandingScore
        float PatternScore
        string ScoreDetails
    }
    
    AIRCRAFT_PROFILES {
        string Id PK
        string Name
        string Category
        string VSpeedsJson
        string LimitsJson
    }
    
    TELEMETRY_FILES {
        string FlightId PK
        string FilePath
        int SampleCount
    }

    FLIGHTS ||--o{ FLIGHT_PHASES : has
    FLIGHTS ||--o{ FLIGHT_EVENTS : has
    FLIGHTS ||--o| FLIGHT_SCORES : has
    FLIGHTS ||--o| TELEMETRY_FILES : has
    FLIGHTS }o--|| AIRCRAFT_PROFILES : uses
Loading

Telemetry Sample Structure

classDiagram
    class TelemetrySample {
        +string Title
        +string AtcId
        +double Latitude
        +double Longitude
        +double AltitudeMsl
        +double AltitudeAgl
        +double IndicatedAirspeed
        +double TrueAirspeed
        +double GroundSpeed
        +double VerticalSpeed
        +double Pitch
        +double Bank
        +double Heading
        +double Elevator
        +double Aileron
        +double Rudder
        +bool GearDown
        +int FlapsIndex
        +double FlapsPercent
        +double AngleOfAttack
        +double GForce
        +bool OnGround
        +bool StallWarning
        +bool OverspeedWarning
        +double SimulationTime
        +DateTime CaptureTime
    }

    class ExpandedTelemetrySample {
        +AttitudeData Attitude
        +PositionData Position
        +VelocityData Velocity
        +EngineData Engine
        +ControlSurfaceData Controls
        +FlapsGearData Configuration
        +EnvironmentData Environment
        +WarningsData Warnings
    }

    class AttitudeData {
        +double Pitch
        +double Bank
        +double Heading
        +double AngleOfAttack
    }

    class PositionData {
        +double Latitude
        +double Longitude
        +double AltitudeMsl
        +double AltitudeAgl
    }

    class VelocityData {
        +double IAS
        +double TAS
        +double GS
        +double VS
        +double Mach
    }

    TelemetrySample <|-- ExpandedTelemetrySample
    ExpandedTelemetrySample *-- AttitudeData
    ExpandedTelemetrySample *-- PositionData
    ExpandedTelemetrySample *-- VelocityData
Loading

Build & Test Pipeline

flowchart LR
    subgraph "Source"
        PR[Pull Request]
        PUSH[Push to Main]
    end

    subgraph "CI Pipeline"
        BUILD[Build Solution]
        TEST[Run Tests]
        COV[Code Coverage]
        QUAL[Code Quality]
        SEC[Security Scan]
    end

    subgraph "Artifacts"
        REPORT[Test Report]
        COVERAGE[Coverage Report]
        BIN[Build Output]
    end

    PR --> BUILD
    PUSH --> BUILD
    
    BUILD --> TEST
    BUILD --> QUAL
    BUILD --> SEC
    
    TEST --> COV
    
    COV --> COVERAGE
    TEST --> REPORT
    BUILD --> BIN

    style BUILD fill:#0078d4,color:#fff
    style TEST fill:#22c55e,color:#fff
    style COV fill:#f39c12,color:#fff
Loading