# dtammam/arcade_station architecture

> Architecture diagram of the GitHub repository dtammam/arcade_station, 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/dtammam/arcade_station
- Repository: https://github.com/dtammam/arcade_station

## Overview

##### Project type and purpose
- Arcade Station is a cross-platform (Windows, Linux, macOS) desktop application—a game front-end with an installation wizard, runtime service, and embedded third-party front-end (Pegasus FE).
- Purpose: let non-technical users install, configure, and launch arcade games in a kiosk-style environment.

##### File structure to extract main blocks
Top-level directories:
- install/ – Python-based installation wizard (UI pages, logic, resources)
- src/arcade_station/ – Core runtime code (common functions, platform adapters, game launchers, listeners)
- src/pegasus-fe/ – Third-party front-end application (executables, QML themes, config files)
- bin/ – OS-specific binaries & helper scripts (AudioSwitch, LightsTest, mame2lit, shell scripts)
- config/ – TOML-based configuration files for defaults and game definitions

##### README for additional insights
- Features: installer wizard, game configuration, kiosk mode
- Architecture not explicitly drawn, but README calls out cross-platform core, installer UI, platform scripts, and Pegasus FE integration

a. Main components:
1) Installer Subsystem
– UI layer (Python install/installer/ui/app.py + pages)
– Installation logic (install/installer/config/installation.py)
– Resource templates (e.g., audioswitch_settings, arcade_station_start scripts)
2) Runtime Core
– Core services (src/arcade_station/core/common)
– Platform adapters (linux, macos, windows subfolders)
3) Pegasus FE
– Executable per platform (pegasus-fe_linux, pegasus-fe_mac, pegasus-fe_windows.exe)
– QML theme files and settings (src/pegasus-fe/themes + config)
4) Launchers & Listeners
– Game launchers (launch_game.py, launch_script.py)
– Key listener (key_listener.py)
– ITGmania monitor (monitor_itgmania.py)
5) Configuration & Assets
– config/*.toml files
– assets/images, assets/sounds
6) External Utilities & Binaries
– AudioSwitch, LightsTest, MAME helper (bin/windows & bin/unix)
– Shell scripts for kiosk mode and startup

b. Relationships and data flows:
- Installation flow:
User → Installer UI → Installation Logic → writes config files + copies assets + installs helper scripts
- Runtime flow:
Launcher (launch_arcade_station.bat / .sh) → Python Core startup →
– Reads config/*.toml
– Spawns Pegasus FE process with appropriate settings
– Initializes key listener → reacts to input → calls core common functions
– On game select: Core calls Launcher modules → spawns game binary or script
– Optional: Core utilities control AudioSwitch, LightsTest, iCloud, VPN
– For ITGmania: Core monitors scores/outputs via monitor_itgmania
- Platform abstraction: Core common functions delegate to platform folders (windows, linux, macos)

c. Architectural patterns and principles:
– Layered architecture: Installer vs. Runtime vs. External
– Modular design: “common” services + “platform” plugins
– Separation of concerns: UI (Pegasus + Installer) ←→ Application logic (Python Core) ←→ Data (Config/Assets) ←→ OS/binaries

d. Key technologies:
– Python 3.12.9 (core, installer, launchers, listeners)
– QML (Pegasus FE themes and UI)
– TOML (configuration)
– Platform scripts: PowerShell, Bash, Batch files
– Third-party executables: Pegasus-FE, AudioSwitch, MAME

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Installer Subsystem
    subgraph "Installer Subsystem"
        direction TB
        InstallerUI["UI Layer\ninstall/installer/ui/app.py + pages"]:::installer
        InstallLogic["Installation Logic\ninstall/installer/config/installation.py"]:::installer
        ResourceTemplates["Resource Templates\ninstall/installer/resources/"]:::installer
    end

    %% Launcher Scripts Entry Points
    subgraph "Launcher Scripts – Entry Points"
        direction TB
        LaunchArcade["launch_arcade_station.bat"]:::installer
        InstallArcade["install_arcade_station.bat"]:::installer
        KillArcade["kill_arcade_station.bat"]:::installer
        InstallMain["install/main.py"]:::installer
        LaunchInstaller["install/launch_installer.pyw"]:::installer
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Config["Config Files\nconfig/*.toml"]:::data
        Assets["Assets\nassets/images/ and assets/sounds/"]:::data
    end

    %% Runtime Core
    subgraph "Runtime Core"
        direction TB
        CoreCommon["Common Services\nsrc/arcade_station/core/common/"]:::core
        subgraph "Platform Adapters"
            direction TB
            LinuxAdapter["Linux Adapter\nsrc/arcade_station/core/linux/arcade_station_start.sh"]:::core
            MacAdapter["macOS Adapter\nsrc/arcade_station/core/macos/arcade_station_start.sh"]:::core
            WinAdapter["Windows Adapter\nsrc/arcade_station/core/windows/arcade_station_start.bat\n(+ .psm1/.ps1)"]:::core
        end
        subgraph "Launchers & Listeners"
            direction TB
            GameLaunchers["Game Launchers\nlaunch_game.py, launch_script.py"]:::core
            ITGMonitor["ITGmania Monitor\nmonitor_itgmania.py"]:::core
            KeyListener["Key Listener\nkey_listener.py"]:::core
            StartupHelpers["Startup Helpers\nstart_frontend_apps.py\nstart_itgmania_monitor.py\ndebug_pegasus_launch.py"]:::core
        end
    end

    %% Pegasus FE
    subgraph "Pegasus Front-End"
        direction TB
        PegasusExec_L["pegasus-fe_linux"]:::fe
        PegasusExec_M["pegasus-fe_mac"]:::fe
        PegasusExec_W["pegasus-fe_windows.exe"]:::fe
        Themes["QML Themes\nsrc/pegasus-fe/themes/"]:::fe
        PEConfig["FE Config Files\nsrc/pegasus-fe/config/"]:::fe
    end

    %% External Utilities & Binaries
    subgraph "External Utilities & Binaries"
        direction TB
        UnixScript["Unix Scripts\nbin/unix/take_screenshot.sh"]:::external
        WinAudio["AudioSwitch\nbin/windows/AudioSwitch/"]:::external
        WinLights["LightsTest.exe\nbin/windows/LightsTest.exe"]:::external
        WinMAME["mame2lit.exe\nbin/windows/mame2lit.exe"]:::external
    end

    %% Flows
    User["User"]:::external
    User -->|"starts"| InstallerUI
    InstallerUI -->|uses| InstallLogic
    InstallerUI -->|loads| ResourceTemplates
    InstallLogic -->|writes| Config
    InstallLogic -->|copies| Assets
    InstallLogic -->|installs| UnixScript
    InstallLogic -->|installs| WinAudio
    InstallLogic -->|installs| WinLights
    InstallLogic -->|installs| WinMAME

    LaunchArcade -->|"executes"| CoreCommon
    CoreCommon -->|"delegates"| LinuxAdapter
    CoreCommon -->|"delegates"| MacAdapter
    CoreCommon -->|"delegates"| WinAdapter

    Config -->|"read by"| CoreCommon
    Assets -->|"used by"| CoreCommon

    CoreCommon -->|"spawns"| PegasusExec_L
    CoreCommon -->|"spawns"| PegasusExec_M
    CoreCommon -->|"spawns"| PegasusExec_W
    PEConfig -->|"loaded by"| PegasusExec_L
    Themes -->|"loaded by"| PegasusExec_L

    PegasusExec_L -->|"events"| CoreCommon
    PegasusExec_M -->|"events"| CoreCommon
    PegasusExec_W -->|"events"| CoreCommon

    CoreCommon -->|"launches"| GameLaunchers
    CoreCommon -->|"starts"| ITGMonitor
    CoreCommon -->|"listens via"| KeyListener
    CoreCommon -->|"runs"| StartupHelpers

    GameLaunchers -->|"launch game"| WinMAME
    ITGMonitor -->|"monitor"| External
    KeyListener -->|"captures input"| CoreCommon

    %% Click Events
    click InstallerUI "https://github.com/dtammam/arcade_station/blob/main/install/installer/ui/app.py"
    click InstallerUI "https://github.com/dtammam/arcade_station/tree/main/install/installer/ui/pages/"
    click InstallLogic "https://github.com/dtammam/arcade_station/blob/main/install/installer/config/installation.py"
    click ResourceTemplates "https://github.com/dtammam/arcade_station/tree/main/install/installer/resources/"
    click CoreCommon "https://github.com/dtammam/arcade_station/tree/main/src/arcade_station/core/common/"
    click LinuxAdapter "https://github.com/dtammam/arcade_station/blob/main/src/arcade_station/core/linux/arcade_station_start.sh"
    click MacAdapter "https://github.com/dtammam/arcade_station/blob/main/src/arcade_station/core/macos/arcade_station_start.sh"
    click WinAdapter "https://github.com/dtammam/arcade_station/blob/main/src/arcade_station/core/windows/arcade_station_start.bat"
    click PegasusExec_L "https://github.com/dtammam/arcade_station/tree/main/src/pegasus-fe/pegasus-fe_linux"
    click PegasusExec_M "https://github.com/dtammam/arcade_station/tree/main/src/pegasus-fe/pegasus-fe_mac"
    click PegasusExec_W "https://github.com/dtammam/arcade_station/blob/main/src/pegasus-fe/pegasus-fe_windows.exe"
    click Themes "https://github.com/dtammam/arcade_station/tree/main/src/pegasus-fe/themes/"
    click PEConfig "https://github.com/dtammam/arcade_station/tree/main/src/pegasus-fe/config/"
    click GameLaunchers "https://github.com/dtammam/arcade_station/blob/main/src/arcade_station/launchers/launch_game.py"
    click GameLaunchers "https://github.com/dtammam/arcade_station/blob/main/src/arcade_station/launchers/launch_script.py"
    click ITGMonitor "https://github.com/dtammam/arcade_station/blob/main/src/arcade_station/launchers/monitor_itgmania.py"
    click KeyListener "https://github.com/dtammam/arcade_station/blob/main/src/arcade_station/listeners/key_listener.py"
    click StartupHelpers "https://github.com/dtammam/arcade_station/blob/main/src/arcade_station/start_frontend_apps.py"
    click StartupHelpers "https://github.com/dtammam/arcade_station/blob/main/src/arcade_station/start_itgmania_monitor.py"
    click StartupHelpers "https://github.com/dtammam/arcade_station/blob/main/src/arcade_station/debug_pegasus_launch.py"
    click Config "https://github.com/dtammam/arcade_station/tree/main/config/"
    click Assets "https://github.com/dtammam/arcade_station/tree/main/assets/"
    click UnixScript "https://github.com/dtammam/arcade_station/blob/main/bin/unix/take_screenshot.sh"
    click WinAudio "https://github.com/dtammam/arcade_station/tree/main/bin/windows/AudioSwitch/"
    click WinLights "https://github.com/dtammam/arcade_station/blob/main/bin/windows/LightsTest.exe"
    click WinMAME "https://github.com/dtammam/arcade_station/blob/main/bin/windows/mame2lit.exe"
    click LaunchArcade "https://github.com/dtammam/arcade_station/blob/main/launch_arcade_station.bat"
    click InstallArcade "https://github.com/dtammam/arcade_station/blob/main/install_arcade_station.bat"
    click KillArcade "https://github.com/dtammam/arcade_station/blob/main/kill_arcade_station.bat"
    click InstallMain "https://github.com/dtammam/arcade_station/blob/main/install/main.py"
    click LaunchInstaller "https://github.com/dtammam/arcade_station/blob/main/install/launch_installer.pyw"

    %% Styles
    classDef installer fill:#D0E3FF,stroke:#1f77b4,color:#000;
    classDef core fill:#DFF7D9,stroke:#2ca02c,color:#000;
    classDef fe fill:#FFE5B4,stroke:#ff7f0e,color:#000;
    classDef data fill:#EED2EE,stroke:#9467bd,color:#000;
    classDef external fill:#E8E8E8,stroke:#7f7f7f,color:#000;
```
