# xcsoar/xcsoar architecture

> Architecture diagram of the GitHub repository xcsoar/xcsoar, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xcsoar/xcsoar
- Repository: https://github.com/xcsoar/xcsoar

## Overview

##### Major Components
- Core Engine Layer:
– Contains the “Engine” directory along with various submodules for flight computations such as the “GlideComputer”, “TaskComputer”, “Wind” solvers, “PathSolvers”, and “Contest” modules.
– Handles navigation algorithms, flight path calculation, task planning, and glide performance analysis.
- Device and Sensor Interfaces:
– The “Device” directory and subdirectories (including “Driver”, “Port”, etc.) implement drivers that interface with hardware sensors (GPS, barometric sensors, FLARM devices, Bluetooth interfaces, etc.).
– Includes platform-specific folders (e.g., “android”, “Apple”, “Kobo”) for handling OS-specific device interactions.
- User Interface (UI) Layer:
– The “UI”, “Dialogs”, “Widget”, “Look”, “Form”, “MapWindow”, “Canvas”, and “Renderer” directories cover the graphical presentation.
– It incorporates both native UI elements and cross-platform rendering (e.g., via OpenGL, SDL, GDI, EGL) to display maps, infoboxes and flight data.
- Communication and External Services:
– Components under “Cloud”, “Net”, “net/http”, “Tracking”, and even the “lua” script interfaces manage networking (uploading flight logs, receiving weather updates, integration with cloud services and tracking systems).
- Data Storage and File I/O:
– The “src” subdirectories also include routines for reading/writing IGC flight logs, waypoint files, and profile/paradata used to persist settings.
- Build and Test Infrastructure:
– The “build”, “tools”, “test”, and “ide” directories indicate comprehensive build scripts, continuous integration workflows, and testing harnesses (including fuzzers and regression tests).

##### Relationships and Data Flow
- Sensor data, whether from hardware drivers or networked sources, flows from the Device and Sensor Interface layer into lower-level processing modules (within the Core Engine).
- The Engine processes live sensor data to compute flight trajectories, detect thermal bands, and dynamically plan tasks. This output is then routed to the UI layer.
- The UI layer collects user inputs via dialogs and widgets (from the “Dialogs” or “Widget” modules) and displays computed flight data (maps, gauges, texts, infoboxes).
- File I/O and configuration services also connect throughout, ensuring that persistent flight profiles, logs, and configurations are read from or written to disk.

##### Architectural Patterns and Design Principles
- Cross-platform Modularization:
– The use of subdirectories for “android”, “Apple”, “Kobo”, and “unix” suggests separation of OS-specific implementations behind common abstractions.
- Layered Design:
- Event-Driven and Asynchronous Processing:
– With “event”, “io”, “thread”, and “job” directories, the code adopts an event-driven approach to schedule sensor reads, UI updates, and network tasks asynchronously.
- Extensibility through Scripting:
– Integration of Lua (and even Python for analysis) helps in customizing behaviors, allowing scripting to react to user preferences or extend core features.
- Clean Separation of Concerns:
– The build and test infrastructure is separate, emphasizing automated testing, continuous integration, and modular compilation via the “build” and “ide” directories.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Hardware & Device Drivers"
        DI["Device & Sensor Interfaces"]:::device
    end

    subgraph "Core Flight Engine"
        CE["Core Flight Engine"]:::engine
    end

    subgraph "User Interface & Presentation"
        UI1["UI Core"]:::ui
        D["Dialogs"]:::ui
        W["Widget"]:::ui
        MW["MapWindow"]:::ui
        L["Look"]:::ui
    end

    subgraph "Communications & External Services"
        C["Cloud"]:::external
        N["net"]:::external
        T["Tracking"]:::external
    end

    subgraph "Data Storage & File I/O"
        DS["Data Storage"]:::data
    end

    subgraph "Build & Test Infrastructure"
        BUIL["Build Infrastructure"]:::build
        TES["Test Infrastructure"]:::build
    end

    %% Relationships and Data Flow
    DI -->|"SensorData"| CE
    C -->|"WeatherUpdate"| CE
    N -->|"NetworkData"| CE
    T -->|"TrackingData"| CE
    CE -->|"ComputedTrajectory"| UI1
    UI1 -->|"UserInput"| CE
    CE -->|"ConfigRW"| DS

    %% Click Events
    click DI "https://github.com/xcsoar/xcsoar/tree/master/src/Device"
    click CE "https://github.com/xcsoar/xcsoar/tree/master/src/Engine"
    click UI1 "https://github.com/xcsoar/xcsoar/tree/master/src/UI"
    click D "https://github.com/xcsoar/xcsoar/tree/master/src/Dialogs"
    click W "https://github.com/xcsoar/xcsoar/tree/master/src/Widget"
    click MW "https://github.com/xcsoar/xcsoar/tree/master/src/MapWindow"
    click L "https://github.com/xcsoar/xcsoar/tree/master/src/Look"
    click C "https://github.com/xcsoar/xcsoar/tree/master/src/Cloud"
    click N "https://github.com/xcsoar/xcsoar/tree/master/src/net"
    click T "https://github.com/xcsoar/xcsoar/tree/master/src/Tracking"
    click DS "https://github.com/xcsoar/xcsoar/tree/master/Data"
    click BUIL "https://github.com/xcsoar/xcsoar/tree/master/build"
    click TES "https://github.com/xcsoar/xcsoar/tree/master/test"

    %% Styles
    classDef device fill:#ffcccc,stroke:#990000,stroke-width:2px;
    classDef engine fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef ui fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef external fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef data fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef build fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
```
