# bluestormdna/kocoboy architecture

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

- Interactive diagram: https://gitdiagram.com/bluestormdna/kocoboy
- Repository: https://github.com/bluestormdna/kocoboy

## Overview

##### Main Components
- Core Emulator Module (kocoboy-core):
- Contains the emulator’s CPU, PPU, APU, Bus, Timer, Cartridge handling (MBC1, MBC2, etc.), and other core components.
- Represents the “backend” or business logic of the emulator.
- Compose Application Module (composeApp):
- Provides the UI built using Compose Multiplatform.
- Contains common UI code (commonMain) along with platform-specific implementations (androidMain, iosMain, desktopMain, wasmJsMain, nativeMain) for tasks like audio and image handling.
- Platform-Specific Wrappers/Applications:
- iOS App: The iosApp folder with Xcode project files handling iOS-specific configuration and integration.
- Android Manifest & resources under composeApp’s androidMain.
- Other platform setups (Desktop, WASM/JS) through dedicated source sets and resource folders.
- Supporting Build and Configuration Files:
- Gradle build scripts (build.gradle.kts, settings.gradle.kts, gradlew.*) managing builds, dependencies, and multiplatform configurations.

##### Relationships & Interactions
- The Compose UI (frontend) communicates with the emulator core (kocoboy-core) via clear APIs. For example:
- UI components (buttons, sidebars, previews) in composeApp access the emulator core logic (emulator main loop, CPU, PPU events) to run or control the emulation.
- Platform-specific implementations in composeApp (such as AudioPlayer.*.kt and ImageBitmap.*.kt files) serve as adapters bridging the common UI logic with native multimedia and system services.
- The IOS, Android, Desktop, and WASM/JS platforms each have their own entry points and resource bundles that feed into the Compose UI, but ultimately the common code and the core module drive emulator functionality.

##### Architectural Patterns & Technologies
- Kotlin Multiplatform Design:
- Separation between common code (shared among platforms) and platform-specific code (androidMain, iosMain, etc.).
- Compose Multiplatform for UI:
- Use of Compose-based UI components, including previews (with annotations provided in androidMain for compatibility).
- Modular Architecture:
- The division of the project into at least two modules: the core emulator logic (kocoboy-core) and the UI/app layer (composeApp), with external apps (iOS app backing project) that serve as wrappers.
- Adapter/Bridge Pattern:
- The per-platform implementations for multimedia (e.g., AudioPlayer and ImageBitmap), highlight how the project abstracts platform-specific functionality.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Emulator Module
    subgraph "Core Emulator"
        E["Emulator Core (CPU, PPU, APU, Bus, Timer, Cartridge)"]:::core
    end

    %% Compose UI Module
    subgraph "Compose UI Layer"
        UI["Compose UI (Common & Platform Implementations)"]:::ui
    end

    %% Platform Specific Implementations
    subgraph "Platform Specific Implementations"
        A["Android (MainActivity & Resources)"]:::platform
        I["iOS (Wrapper & Configurations)"]:::platform
        D["Desktop (Entry Point & Adaptations)"]:::platform
        W["WASM/JS (Entry Point & Web Resources)"]:::platform
    end

    %% Build and Configuration Files
    subgraph "Build & Configuration"
        B1["build.gradle.kts"]:::build
        B2["settings.gradle.kts"]:::build
        B3["gradle/"]:::build
        B4["gradlew"]:::build
        B5["gradlew.bat"]:::build
    end

    %% Arrows from Platform Implementations to Compose UI
    A -->|"feeds"| UI
    I -->|"feeds"| UI
    D -->|"feeds"| UI
    W -->|"feeds"| UI

    %% Arrow from Compose UI to Core Emulator
    UI -->|"controls"| E

    %% Arrows from Build & Config nodes to Compose UI
    B1 -->|"builds"| UI
    B2 -->|"builds"| UI
    B3 -->|"builds"| UI
    B4 -->|"builds"| UI
    B5 -->|"builds"| UI

    %% Click Events
    click E "https://github.com/bluestormdna/kocoboy/tree/main/kocoboy-core/"
    click UI "https://github.com/bluestormdna/kocoboy/tree/main/composeApp/"
    click A "https://github.com/bluestormdna/kocoboy/tree/main/composeApp/src/androidMain/"
    click I "https://github.com/bluestormdna/kocoboy/tree/main/iosApp/"
    click D "https://github.com/bluestormdna/kocoboy/tree/main/composeApp/src/desktopMain/"
    click W "https://github.com/bluestormdna/kocoboy/tree/main/composeApp/src/wasmJsMain/"
    click B1 "https://github.com/bluestormdna/kocoboy/blob/main/build.gradle.kts"
    click B2 "https://github.com/bluestormdna/kocoboy/blob/main/settings.gradle.kts"
    click B3 "https://github.com/bluestormdna/kocoboy/tree/main/gradle/"
    click B4 "https://github.com/bluestormdna/kocoboy/tree/main/gradlew"
    click B5 "https://github.com/bluestormdna/kocoboy/blob/main/gradlew.bat"

    %% Styles
    classDef core fill:#FFD700,stroke:#DAA520,stroke-width:2px;
    classDef ui fill:#87CEFA,stroke:#4682B4,stroke-width:2px;
    classDef platform fill:#90EE90,stroke:#32CD32,stroke-width:2px;
    classDef build fill:#E6E6FA,stroke:#9370DB,stroke-width:2px;
```
