# ojh050118/circle architecture

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

- Interactive diagram: https://gitdiagram.com/ojh050118/circle
- Repository: https://github.com/ojh050118/circle

## Overview

##### Project Type and Purpose
- This is a multi‐platform, fanmade game client (“Circle”) for the rhythm game “A Dance of Fire and Ice.”
- It targets Android, iOS, Linux, macOS, Windows and includes a core game engine, shared assets, platform‐specific frontends, deployment tooling, and automated tests.

- Core Engine (“Circle.Game”):
– Beatmap management (loading, parsing, caching)
– Rendering pipeline (graphics, shaders, containers)
– Input & rulesets (tile definitions, gameplay logic)
– UI Overlays & Screens (menus, playfield, settings)
– Converters (Adofai → internal format, JSON serializers)
– I/O subsystems (file readers, archive readers, storage abstractions)
- Shared Resources (“Circle.Resources”):
– Fonts, audio samples, shaders, textures
– Exposed via a resource‐provider layer to the core engine
- Platform Frontends:
– Android (“Circle.Android”): Activity entry point, AndroidManifest, Resources
– iOS (“Circle.iOS”): AppDelegate, storyboard, entitlements, Info.plist
- Deployment Tooling (“Circle.Desktop.Deploy”):
– Builders per OS (AndroidBuilder, IOSBuilder, LinuxBuilder, MacOSBuilder, WindowsBuilder)
– Uploader modules (GitHubUploader, VelopackUploader variants)
– Entry program orchestrating build+upload
- Testing Suite (“Circle.Game.Tests”):
– Visual test scenes for UI components, gameplay elements, overlays, selectors
– NUnit console runner configured in CI

##### Relationships & Data Flow
- All platform projects reference the Core Engine and Shared Resources.
- Core Engine loads assets via the IStorageResourceProvider abstraction.
- At runtime, Input → Game Logic → Rendering → Output on screen/sound device.
- Deployment tool consumes compiled platform binaries & templates → produces installers/packages → pushes to GitHub or Velopack.
- CI workflow (ci.yml) runs build → tests (report‐nunit.yml) → packaging → release artifacts.

##### Architectural Patterns & Principles
- Modular layering: separation of “Engine,” “Resources,” “Frontends,” “Deploy.”
- Dependency injection via interfaces (IBeatmapResourceProvider, IWorkingBeatmapCache, IStorageResourceProvider).
- MVC‐like screens/states for UI flow (Screen stack, overlays).
- Strategy pattern in Builders & Uploaders for platform‐specific packaging.
- Single Responsibility: each directory/class has a focused concern (graphics, IO, input, conversion).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1: Shared Resources
    subgraph "Layer 1: Shared Resources"
        RES["Shared Resources"]:::resources
    end

    %% Layer 2: Core Engine
    subgraph "Circle.Game"
        BEAT["Beatmaps"]:::engine
        CONV["Converters"]:::engine
        GRAPH["Graphics"]:::engine
        IO["I/O"]:::engine
        INPUT["Input"]:::engine
        RULES["Rulesets"]:::engine
        OVER["UI Overlays"]:::engine
        SCR["Screens"]:::engine
    end

    %% Layer 3: Platform Frontends
    subgraph "Platform Frontends"
        ANDROID["Android Frontend"]:::frontend
        IOS["iOS Frontend"]:::frontend
        DESKTOP["Desktop Frontend"]:::frontend
    end

    %% Layer 4: Deployment & External Services
    subgraph "Deployment & External"
        DEPLOY["Deployment Tool"]:::tooling
        GITHUB["GitHub"]:::cloud
        VELO["Velopack"]:::cloud
    end

    %% CI/CD Pipeline (Side)
    subgraph "CI/CD Pipeline"
        CI["GitHub Actions"]:::ci
        BUILD["Build Solutions"]:::ci
        TESTS["Run NUnit Tests"]:::ci
        PACK["Package & Deploy"]:::ci
    end

    %% Relationships: Core Engine -> Resources
    BEAT -->|"loads assets from"| RES
    GRAPH -->|"loads shaders/textures from"| RES
    CONV -->|"serializes via"| RES
    IO -->|"reads files from"| RES
    INPUT -->|"uses providers from"| RES
    OVER -->|"renders UI with assets from"| RES
    SCR -->|"renders screens with assets from"| RES

    %% Frontends -> Core Engine
    ANDROID -->|"bootstraps engine"| BEAT
    IOS -->|"bootstraps engine"| BEAT
    DESKTOP -->|"bootstraps engine"| BEAT

    %% Deployment flow
    ANDROID -->|"provides binaries to"| DEPLOY
    IOS -->|"provides binaries to"| DEPLOY
    DESKTOP -->|"provides binaries to"| DEPLOY
    DEPLOY -->|"uploads release to"| GITHUB
    DEPLOY -->|"uploads release to"| VELO

    %% CI/CD flow
    CI -->|"triggers"| BUILD
    BUILD -->|"runs"| TESTS
    TESTS -->|"invokes"| DEPLOY
    PACK -->|"orchestrates"| DEPLOY

    %% Click Events for component mappings
    click RES "https://github.com/ojh050118/circle/tree/master/Circle.Resources/"
    click BEAT "https://github.com/ojh050118/circle/tree/master/Circle.Game/Beatmaps/"
    click CONV "https://github.com/ojh050118/circle/tree/master/Circle.Game/Converting/"
    click GRAPH "https://github.com/ojh050118/circle/tree/master/Circle.Game/Graphics/"
    click IO "https://github.com/ojh050118/circle/tree/master/Circle.Game/IO/"
    click INPUT "https://github.com/ojh050118/circle/tree/master/Circle.Game/Input/"
    click RULES "https://github.com/ojh050118/circle/tree/master/Circle.Game/Rulesets/"
    click OVER "https://github.com/ojh050118/circle/tree/master/Circle.Game/Overlays/"
    click SCR "https://github.com/ojh050118/circle/tree/master/Circle.Game/Screens/"
    click ANDROID "https://github.com/ojh050118/circle/tree/master/Circle.Android/"
    click IOS "https://github.com/ojh050118/circle/tree/master/Circle.iOS/"
    click DESKTOP "https://github.com/ojh050118/circle/tree/master/Circle.Desktop/"
    click DEPLOY "https://github.com/ojh050118/circle/tree/master/Circle.Desktop.Deploy/"
    click Builders "https://github.com/ojh050118/circle/tree/master/Circle.Desktop.Deploy/Builders/"
    click Uploaders "https://github.com/ojh050118/circle/tree/master/Circle.Desktop.Deploy/Uploaders/"
    click templates "https://github.com/ojh050118/circle/tree/master/Circle.Desktop.Deploy/templates/"
    click TESTS "https://github.com/ojh050118/circle/tree/master/Circle.Game.Tests/"
    click CI "https://github.com/ojh050118/circle/blob/master/ .github/workflows/ci.yml"
    click PACK "https://github.com/ojh050118/circle/blob/master/ .github/workflows/report-nunit.yml"

    %% Styling
    classDef resources fill:#f9f871,stroke:#333,stroke-width:1px
    classDef engine fill:#8ecae6,stroke:#333,stroke-width:1px
    classDef frontend fill:#a8dadc,stroke:#333,stroke-width:1px
    classDef tooling fill:#ffb703,stroke:#333,stroke-width:1px
    classDef cloud fill:#caffbf,stroke:#333,stroke-width:1px
    classDef ci fill:#d3d3d3,stroke:#333,stroke-width:1px
```
