# strikerx3/ymir architecture

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

- Interactive diagram: https://gitdiagram.com/strikerx3/ymir
- Repository: https://github.com/strikerx3/ymir

## Overview

##### Main components
- Core Library (libs/ymir-core)
– Submodules:
- System & Scheduler (sys, core)
- Hardware Emulation (hw/*: SH2, SCU, SCSP, VDP, SMPC, M68K, CD Block, Cartridge)
- Media Loader & Filesystem (media/loader, iso, CHD, etc.)
- State Management (state/*)
- Utility & Serialization (util, serdes)
- Database (db: game_db, rom_cart_db, IPL DB)
- Front-end Applications (apps/)
– ymdasm (CLI disassembler)
– ymir-sandbox (headless sandbox harness)
– ymir-sdl3 (SDL3-based GUI emulator)
- UI Layer (windows, views, widgets, events)
- Input System (SDL3 back-end, binding, context)
- Audio System (SCSP output)
- Profile & Settings manager
- Save-state & Rewind feature (via serdes)
- Build & Packaging
– CMake scripts (CMakelists.txt, cmake/)
– Packaging modules (YmirConfig, installers)
- Tests
– Unit tests targeting libs/ymir-core (under tests/ymir-core-tests)

##### Relationships & data flow
- The front-end apps link against the core library.
- User input → SDL3 Input subsystem → Event queue → Core API (e.g., SMPC peripheral callbacks).
- Core Scheduler drives simulated hardware modules; these modules update System State.
- Media Loader feeds raw game data into the core (disc images, ISO, CHD).
- Core exposes frame buffers and audio buffers back to the front-end, which then renders via SDL3.
- Save-state and rewind use serialization (cereal) on the core’s state objects.
- The tests invoke core APIs directly to validate emulation correctness.

##### Architectural patterns & principles
- Layered modular design: “libs/ymir-core” is a purely computational layer, “apps” are presentation layers.
- Dependency inversion: front-ends depend on abstracted core APIs.
- Single-responsibility: each hardware component lives in its own namespace/subdirectory.
- Event-driven UI: separates GUI rendering, input, and emulation callbacks.
- Plugin-like media loaders: loader_bin_cue, loader_iso, loader_chd implement a common loader interface.

##### Technologies & frameworks
- C++17/20
- CMake build system
- SDL3 (for GUI, input, audio)
- cereal (for serialization of save-state)
- Doxygen (docs)
- GitHub Actions (CI, release workflows)
- MAME CHD, ISO, BIN+CUE, IMG+CCD, MDF+MDS support

- Use clear labels:
– Core modules in blue
– Front-ends (CLI tools, GUI) in green
– Media loaders in orange
– Tests/CI in purple
– Rectangles for modules
– Core library (blue)
– Front-end apps (green)
– Build & packaging (gray)
– Tests/CI (purple)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Library
    subgraph "Core Library" 
        direction TB
        CoreLib["libs/ymir-core"]:::core
        subgraph "System & Scheduler" 
            direction TB
            Scheduler["Scheduler"]:::core
            SystemAPI["System APIs"]:::core
        end
        subgraph "Hardware Emulation" 
            direction TB
            SH2["SH2"]:::core
            SCU["SCU"]:::core
            SCSP["SCSP"]:::core
            VDP["VDP"]:::core
            SMPC["SMPC"]:::core
            M68K["M68K"]:::core
            CDBlock["CD Block"]:::core
            Cartridge["Cartridge"]:::core
        end
        subgraph "Media Loader & Filesystem" 
            direction TB
            MediaLoader["Loader Interface & Plugins"]:::media
            Filesystem["Filesystem"]:::media
        end
        subgraph "State Management" 
            direction TB
            State["State"]:::core
        end
        subgraph "Utility & Serialization" 
            direction TB
            Util["Utility"]:::core
            Version["Versioning"]:::core
        end
        subgraph "Database" 
            direction TB
            GameDB["Game DB"]:::core
            RomCartDB["ROM Cartridge DB"]:::core
            IPLDB["IPL DB"]:::core
        end
        CoreLib --> Scheduler
        CoreLib --> SH2
        CoreLib --> MediaLoader
        CoreLib --> State
        CoreLib --> Util
        CoreLib --> GameDB
    end

    %% Front-end Applications
    subgraph "Front-end Applications" 
        direction TB
        ymdasm["ymdasm (CLI)"]:::front
        sandbox["ymir-sandbox (Headless)"]:::front
        subgraph "ymir-sdl3 (SDL3 GUI)" 
            direction TB
            SDL3App["GUI Emulator"]:::front
            UI["UI Layer"]:::front
            Input["Input System"]:::front
            Audio["Audio System"]:::front
            Profile["Profile & Settings"]:::front
            Rewind["Save-State & Rewind"]:::front
        end
        ymdasm -->|links| CoreLib
        sandbox -->|links| CoreLib
        SDL3App -->|links| CoreLib
        Input -->|async events| CoreLib
        CoreLib -->|video/audio buffers| Audio
        CoreLib -->|frame data| UI
        Rewind -->|serialization APIs| Util
    end

    %% Build & Packaging
    subgraph "Build & Packaging" 
        direction TB
        CMakeRoot["CMakeLists.txt"]:::build
        CMakeModules["cmake/"]:::build
        YmirConfig["YmirConfig.cmake"]:::build
        ymdasmPkg["apps/ymdasm/packaging"]:::build
        sdl3Pkg["apps/ymir-sdl3/packaging"]:::build
        CMakeRoot --> CMakeModules
        CMakeRoot --> YmirConfig
    end

    %% Tests
    subgraph "Tests/CI" 
        direction TB
        CoreTests["tests/ymir-core-tests"]:::test
    end
    CoreTests -->|invokes| CoreLib

    %% External Dependencies
    SDL3["SDL3"]:::ext
    cereal["cereal"]:::ext
    CHD["MAME CHD"]:::ext
    SDL3 --> Input
    cereal --> Rewind
    CHD --> MediaLoader

    %% Click Events
    click CoreLib "https://github.com/strikerx3/ymir/tree/main/libs/ymir-core"
    click Scheduler "https://github.com/strikerx3/ymir/blob/main/libs/ymir-core/include/ymir/core/scheduler.hpp"
    click SystemAPI "https://github.com/strikerx3/ymir/blob/main/libs/ymir-core/include/ymir/sys/system.hpp"
    click SH2 "https://github.com/strikerx3/ymir/tree/main/libs/ymir-core/include/ymir/hw/sh2"
    click SCU "https://github.com/strikerx3/ymir/tree/main/libs/ymir-core/include/ymir/hw/scu"
    click SCSP "https://github.com/strikerx3/ymir/tree/main/libs/ymir-core/include/ymir/hw/scsp"
    click VDP "https://github.com/strikerx3/ymir/tree/main/libs/ymir-core/include/ymir/hw/vdp"
    click SMPC "https://github.com/strikerx3/ymir/tree/main/libs/ymir-core/include/ymir/hw/smpc"
    click M68K "https://github.com/strikerx3/ymir/tree/main/libs/ymir-core/include/ymir/hw/m68k"
    click CDBlock "https://github.com/strikerx3/ymir/tree/main/libs/ymir-core/include/ymir/hw/cdblock"
    click Cartridge "https://github.com/strikerx3/ymir/tree/main/libs/ymir-core/include/ymir/hw/cart"
    click MediaLoader "https://github.com/strikerx3/ymir/tree/main/libs/ymir-core/include/ymir/media/loader"
    click Filesystem "https://github.com/strikerx3/ymir/blob/main/libs/ymir-core/include/ymir/media/filesystem.hpp"
    click State "https://github.com/strikerx3/ymir/tree/main/libs/ymir-core/include/ymir/state"
    click Util "https://github.com/strikerx3/ymir/tree/main/libs/ymir-core/include/ymir/util"
    click Version "https://github.com/strikerx3/ymir/blob/main/libs/ymir-core/include/ymir/version.hpp"
    click GameDB "https://github.com/strikerx3/ymir/blob/main/libs/ymir-core/include/ymir/db/game_db.hpp"
    click RomCartDB "https://github.com/strikerx3/ymir/blob/main/libs/ymir-core/include/ymir/db/rom_cart_db.hpp"
    click IPLDB "https://github.com/strikerx3/ymir/blob/main/libs/ymir-core/include/ymir/db/ipl_db.hpp"
    click ymdasm "https://github.com/strikerx3/ymir/tree/main/apps/ymdasm"
    click ymdasm "https://github.com/strikerx3/ymir/blob/main/apps/ymdasm/src/ymdasm.cpp"
    click sandbox "https://github.com/strikerx3/ymir/tree/main/apps/ymir-sandbox"
    click sandbox "https://github.com/strikerx3/ymir/blob/main/apps/ymir-sandbox/src/main.cpp"
    click SDL3App "https://github.com/strikerx3/ymir/tree/main/apps/ymir-sdl3"
    click SDL3App "https://github.com/strikerx3/ymir/blob/main/apps/ymir-sdl3/src/main.cpp"
    click SDL3App "https://github.com/strikerx3/ymir/blob/main/apps/ymir-sdl3/src/winmain.cpp"
    click UI "https://github.com/strikerx3/ymir/tree/main/apps/ymir-sdl3/src/app/ui"
    click Input "https://github.com/strikerx3/ymir/tree/main/apps/ymir-sdl3/src/app/input"
    click Audio "https://github.com/strikerx3/ymir/blob/main/apps/ymir-sdl3/src/app/audio_system.cpp"
    click Profile "https://github.com/strikerx3/ymir/blob/main/apps/ymir-sdl3/src/app/profile.cpp"
    click Profile "https://github.com/strikerx3/ymir/blob/main/apps/ymir-sdl3/src/app/settings.cpp"
    click Rewind "https://github.com/strikerx3/ymir/blob/main/apps/ymir-sdl3/src/app/rewind_buffer.cpp"
    click Rewind "https://github.com/strikerx3/ymir/tree/main/apps/ymir-sdl3/src/serdes"
    click embed "https://github.com/strikerx3/ymir/tree/main/apps/ymir-sdl3/res/embed"
    click CMakeRoot "https://github.com/strikerx3/ymir/blob/main/CMakeLists.txt"
    click CMakeModules "https://github.com/strikerx3/ymir/tree/main/cmake/"
    click YmirConfig "https://github.com/strikerx3/ymir/blob/main/packaging/YmirConfig.cmake"
    click ymdasmPkg "https://github.com/strikerx3/ymir/tree/main/apps/ymdasm/packaging"
    click sdl3Pkg "https://github.com/strikerx3/ymir/tree/main/apps/ymir-sdl3/packaging"
    click CoreTests "https://github.com/strikerx3/ymir/tree/main/tests/ymir-core-tests"
    click CoreTests "https://github.com/strikerx3/ymir/tree/main/tests/ymir-core-tests/src/hw"

    %% Styles
    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef front fill:#d4edda,stroke:#333,stroke-width:1px
    classDef media fill:#ffe5cc,stroke:#333,stroke-width:1px
    classDef build fill:#e2e3e5,stroke:#333,stroke-width:1px
    classDef test fill:#f5c2e7,stroke:#333,stroke-width:1px
    classDef ext fill:#f8d7da,stroke:#333,stroke-width:1px
```
