# godarklight/dream architecture

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

- Interactive diagram: https://gitdiagram.com/godarklight/dream
- Repository: https://github.com/godarklight/dream

## Overview

##### Project Type and Purpose
- Dream is a cross-platform, real-time C++ software receiver/transceiver for the Digital Radio Mondiale (DRM) standard.
- It combines a Qt-based GUI (and CLI) with a layered signal-processing pipeline, hardware-abstraction for audio/IQ I/O, and modules for modulation/demodulation, error-correction, multiplexing, and data decoding.

##### Top-Level Architecture from File Structure
- src/GUI-QT & util-QT: the front-end (MVC pattern) for user interaction, parameter dialogs, plots.
- src/main-Qt & src/main.cpp: application entry points (GUI vs. console).
- src/sound & platform-specific dirs (linux/, windows/, android/): audio and SDR I/O abstraction (PortAudio, ALSA, PulseAudio, SoapySDR, Windows API).
- Core signal pipeline modules (under src/):
– Tuner & Resampler: tuner.cpp, InputResample, UpsampleFilter
– Synchronization: sync/ (FreqSyncAcq, TimeSync)
– OFDM Demodulation / Cell Mapping: OFDM.cpp, ofdmcellmapping/
– Error-Correction / Multiplexing: MLC (mlc/), MSCMultiplexer, interleaver/, tables/
– Service Data / Channel Decoding: MDI (MDI/), SDC (SDC/), ServiceInformation, Scheduler
– Data Decoding: datadecoding/ (DABMOT, Journaline, EPG, MOT slideshows)
– Audio Decoding / Playback: sourcedecoders/, AudioCodec, Opus/AAC codecs
- Simulation & Transmit: DrmSimulation, DrmTransmitter, ChannelSimulation
- Build & Packaging: Qt .pro files, debian/, windows/ scripts, macx deploy.sh

##### Key Architectural Patterns & Design Principles
- Layered, pipeline architecture for the signal chain
- Abstraction layers for platform-specific I/O (factory pattern in soundinterfacefactory)
- MVC for GUI (Qt widgets, dialogs in GUI-QT)
- Modular separation of concerns: synchronization, decoding, multiplexing, UI

##### Components & Relationships
a. User Interface Layer
– Qt GUI and/or CLI entry point
– Dialogs & Plotting (QWT)
b. Input Abstraction Layer
– Soundcard/SDR factory → platform/util modules
c. Signal Processing Pipeline
1. Tuner → Resampler
2. Frequency & Time Synchronization
3. OFDM Demodulator → Cell Mapping
4. Error Correction & Multiplexing (MLC, MSC, Interleaver)
5. MDI/SDC Packet Decoding
6. Service Data Extraction & Scheduler
7. Data Decoding (Journaline, EPG, MOT, Audio frames)
d. Output Abstraction Layer
– Audio sink via same soundinterfacefactory
– File output (if configured)
e. Simulation & Transmit (optional branch)
– DrmTransmitter → ChannelSimulation → loop-back into Input pipeline

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interface Layer
    subgraph "User Interface Layer"
        direction TB
        GUI_QT["Qt GUI (MVC Front-End)"]:::frontend
        UTIL_QT["Qt Utility Modules"]:::frontend
        ENTRY_GUI["GUI Entry Point (main-Qt/main.cpp)"]:::frontend
        ENTRY_CLI["CLI Entry Point (main.cpp)"]:::frontend
    end

    %% Input Abstraction Layer
    subgraph "Input Abstraction Layer"
        direction TB
        SIFactory["SoundInterfaceFactory"]:::io
        LinuxIO["Linux Adapters"]:::io
        WindowsIO["Windows Adapters"]:::io
        AndroidIO["Android Adapters"]:::io
    end

    %% Signal Processing Pipeline
    subgraph "Signal Processing Pipeline"
        direction TB
        Tuner["Tuner"]:::processing
        Resample["Resampler\n(InputResample, UpsampleFilter, resample/)"]:::processing
        Sync["Sync Modules\n(FreqSyncAcq, TimeSync)"]:::processing
        OFDM_Demod["OFDM Demodulation"]:::processing
        CellMapping["OFDM Cell Mapping"]:::processing
        ErrorCorr["Error Correction & Multiplexing\n(MLC, MSCMultiplexer, Interleaver, Tables)"]:::processing
        PacketDec["MDI/SDC Packet Decoding"]:::processing
        ServiceSched["Service Extraction & Scheduler"]:::processing
        DataDec["Data Decoding\n(Journaline, EPG, MOT)"]:::processing
        AudioDec["Audio Decoding / Playback"]:::processing
        ReceiverCtrl["Core Receiver Controller"]:::processing
    end

    %% Output Abstraction Layer
    subgraph "Output Abstraction Layer"
        direction TB
        AudioSink["Audio Sink (via SoundInterfaceFactory)"]:::output
        FileOut["File Output"]:::output
    end

    %% Simulation & Transmit
    subgraph "Simulation & Transmit"
        direction TB
        DrmSim["DRM Simulation"]:::sim
        DrmTx["DRM Transmitter"]:::sim
        DrmTransceiver["DRM Transceiver"]:::sim
        ChannelSim["Channel Simulation"]:::sim
    end

    %% Data Flows
    ENTRY_GUI -->|"UI Commands"| SIFactory
    ENTRY_CLI -->|"UI Commands"| SIFactory
    GUI_QT -->|"UI Actions"| ENTRY_GUI
    UTIL_QT -->|"Dialogs/Plots"| GUI_QT

    SIFactory -->|"IQ Samples"| Tuner
    LinuxIO --> SIFactory
    WindowsIO --> SIFactory
    AndroidIO --> SIFactory

    Tuner -->|"Tuned IQ"| Resample
    Resample -->|"Resampled IQ"| Sync
    Sync -->|"Synced Symbols"| OFDM_Demod
    OFDM_Demod -->|"OFDM Symbols"| CellMapping
    CellMapping -->|"Mapped Cells"| ErrorCorr
    ErrorCorr -->|"Corrected Packets"| PacketDec
    PacketDec -->|"Packet Data"| ServiceSched
    ServiceSched -->|"Service Streams"| DataDec
    DataDec -->|"Decoded Frames"| AudioDec
    AudioDec -->|"PCM Audio"| AudioSink
    AudioDec -->|"Data Files"| FileOut

    DrmSim --> DrmTx
    DrmTx --> DrmTransceiver
    DrmTransceiver --> ChannelSim
    ChannelSim -->|"Simulated IQ"| SIFactory

    %% Click Events
    click GUI_QT "https://github.com/godarklight/dream/tree/darklight/src/GUI-QT/"
    click UTIL_QT "https://github.com/godarklight/dream/tree/darklight/src/util-QT/"
    click ENTRY_GUI "https://github.com/godarklight/dream/blob/darklight/src/main-Qt/main.cpp"
    click ENTRY_CLI "https://github.com/godarklight/dream/blob/darklight/src/main.cpp"
    click SIFactory "https://github.com/godarklight/dream/blob/darklight/src/sound/soundinterfacefactory.cpp"
    click LinuxIO "https://github.com/godarklight/dream/tree/darklight/src/linux/"
    click WindowsIO "https://github.com/godarklight/dream/tree/darklight/src/windows/"
    click AndroidIO "https://github.com/godarklight/dream/tree/darklight/src/android/"
    click Tuner "https://github.com/godarklight/dream/blob/darklight/src/tuner.cpp"
    click Resample "https://github.com/godarklight/dream/blob/darklight/src/InputResample.cpp"
    click Resample "https://github.com/godarklight/dream/blob/darklight/src/UpsampleFilter.h"
    click Resample "https://github.com/godarklight/dream/tree/darklight/src/resample/"
    click Sync "https://github.com/godarklight/dream/tree/darklight/src/sync/"
    click OFDM_Demod "https://github.com/godarklight/dream/blob/darklight/src/OFDM.cpp"
    click CellMapping "https://github.com/godarklight/dream/tree/darklight/src/ofdmcellmapping/"
    click ErrorCorr "https://github.com/godarklight/dream/tree/darklight/src/mlc/"
    click ErrorCorr "https://github.com/godarklight/dream/blob/darklight/src/MSCMultiplexer.cpp"
    click ErrorCorr "https://github.com/godarklight/dream/tree/darklight/src/interleaver/"
    click ErrorCorr "https://github.com/godarklight/dream/tree/darklight/src/tables/"
    click PacketDec "https://github.com/godarklight/dream/tree/darklight/src/MDI/"
    click PacketDec "https://github.com/godarklight/dream/tree/darklight/src/SDC/"
    click ServiceSched "https://github.com/godarklight/dream/blob/darklight/src/ServiceInformation.cpp"
    click ServiceSched "https://github.com/godarklight/dream/blob/darklight/src/Scheduler.cpp"
    click DataDec "https://github.com/godarklight/dream/tree/darklight/src/datadecoding/"
    click DataDec "https://github.com/godarklight/dream/tree/darklight/src/datadecoding/journaline/"
    click AudioDec "https://github.com/godarklight/dream/tree/darklight/src/sourcedecoders/"
    click ReceiverCtrl "https://github.com/godarklight/dream/blob/darklight/src/DrmReceiver.cpp"
    click DrmSim "https://github.com/godarklight/dream/blob/darklight/src/DrmSimulation.cpp"
    click DrmTx "https://github.com/godarklight/dream/blob/darklight/src/DrmTransmitter.cpp"
    click DrmTransceiver "https://github.com/godarklight/dream/blob/darklight/src/DrmTransceiver.cpp"
    click ChannelSim "https://github.com/godarklight/dream/tree/darklight/src/drmchannel/"

    %% Styles
    classDef frontend fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef io fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef processing fill:#ffedcc,stroke:#333,stroke-width:1px
    classDef output fill:#e5ccff,stroke:#333,stroke-width:1px
    classDef sim fill:#ffcccc,stroke:#333,stroke-width:1px
    classDef external fill:#f2f2f2,stroke-dasharray: 5 5
```
