# gmitch215/cmdfx architecture

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

- Interactive diagram: https://gitdiagram.com/gmitch215/cmdfx
- Repository: https://github.com/gmitch215/cmdfx

## Overview

##### Project Type and Purpose
- CmdFX is a **cross-platform C library** (game engine) for drawing and animating in the terminal.
- It exposes a public API (Canvas, Sprites, Physics, Events, Builder) and handles platform-specific details under the hood.
- It’s designed for embedding in C (or Kotlin/Native) programs, with samples and tests illustrating usage.

##### File Structure
Top-level directories and their responsibilities:
- /cmdfx/...
– Public headers (API): core, animation, canvas, builder, costumes, device, events, scenes, sprites, util, physics, ui.
- src/common/...
– Core engine implementations, platform-agnostic logic for animation, canvas drawing, physics calculations, UI widgets, event dispatching.
- src/{linux, macos, posix, windows}/core and physics
– Platform adapters implementing low-level terminal I/O, screen management, device queries, and any platform-specific physics hooks (if needed).
- cmake, CMakeLists.txt
– Build system: generates static/shared libraries, exports a Config.cmake, sets up installation targets.
- samples/
– Example applications demonstrating each API facet.
- test/
– Automated unit tests (test/src/core, test/src/physics) and manual smoke tests (test/src/manual).
- docs/
– Doxygen configuration and doc generator scripts.

##### README for Insights
- Confirms cross-platform support (Windows, macOS, Linux)
- Highlights subsystems: Events API, Canvas API (with Sprite extensions), Builder API, Physics Engine, Input API, and platform utilities.
- Points to samples and contributing guidelines.

##### Main Components & Their Relationships

[A] Consumer Applications
- Samples, User Code (integates via `#include <cmdfx.h>`)
→ calls

[B] Public API Layer (Headers)
- cmdfx.h orchestrates everything
- Sub-APIs: Canvas, Sprites, Builder, Events, Physics, UI, Device
→ invokes

[C] Core Engine Modules (src/common)
- Animation Engine, Canvas Renderer, Event Dispatcher, Physics Solver, UI Widgets, Utility functions
→ delegates low-level work to

[D] Platform Abstraction Interfaces
- Abstract interfaces declared in include/cmdfx/core/device.h, screen.h, util.h
→ implemented by

[E] Platform-Specific Modules
- src/linux/core/device.c & screen.c
- src/macos/core/device.c & screen.c
- src/windows/core/...
- src/posix/... (fallback)
→ make system calls / ANSI escape sequences / WinAPI calls to drive the terminal

[F] Build & Packaging
- CMake and cmake/Config.cmake.in generate library artifacts and export a Config module for downstream Kotlin/Native usage
→ enables

[G] Documentation Generator & CI
- docs/Doxyfile.in → doxygen.sh
- .github/workflows/build.yml & release.yml

[H] Testing
- test/src/core & test/src/physics → unit test executables
- test/src/manual → interactive/manual validation scripts

##### Architectural Patterns & Design Principles
- **Layered Architecture:** Clear separation between Public API, Core Logic, and Platform Drivers.
- **Abstraction & Portability:** Define interfaces in common headers, implement per-platform under src/{linux, windows, …}.
- **Modularity:** Each domain (animation, physics, UI) is a self-contained module under both include/ and src/common/.
- **Testability:** Core logic sits in src/common so it can be tested without depending on platform code.
- **Build-Time Configuration:** CMake orchestrates discovery of platform code and generation of a cross-platform library.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Consumer Layer"
        ConsumerApps["Consumer Applications"]:::utility
    end

    subgraph "Public API Layer"
        API["cmdfx.h"]:::publicapi
        CanvasAPI["Canvas API<br/>include/cmdfx/core/canvas.h"]:::publicapi
        SpriteAPI["Sprites API<br/>include/cmdfx/core/sprites.h"]:::publicapi
        BuilderAPI["Builder API<br/>include/cmdfx/core/builder.h"]:::publicapi
        EventsAPI["Events API<br/>include/cmdfx/core/events.h"]:::publicapi
        PhysicsAPI["Physics API<br/>include/cmdfx/physics/"]:::publicapi
        UIAPI["UI API<br/>include/cmdfx/ui/"]:::publicapi
    end

    subgraph "Core Engine Modules"
        AnimCore["Animation Engine<br/>src/common/core/animation/"]:::core
        CanvasCore["Canvas Renderer<br/>src/common/core/canvas.c"]:::core
        EventsCore["Event Dispatcher<br/>src/common/core/events.c"]:::core
        PhysicsCore["Physics Solver<br/>src/common/physics/"]:::core
        UICore["UI Widgets<br/>src/common/ui/"]:::core
    end

    subgraph "Platform Abstraction Interfaces"
        DeviceH["device.h"]:::publicapi
        ScreenH["screen.h"]:::publicapi
        UtilH["util.h"]:::publicapi
    end

    subgraph "Platform-Specific Modules"
        LinuxPS["Linux Module<br/>src/linux/core/device.c & screen.c"]:::platform
        MacPS["macOS Module<br/>src/macos/core/device.c & screen.c"]:::platform
        WinPS["Windows Module<br/>src/windows/core/device.c & screen.c<br/>src/windows/physics/engine.c & force.c"]:::platform
        PosixPS["POSIX Fallback<br/>src/posix/core/screen.c & util.c<br/>src/posix/physics/engine.c & force.c"]:::platform
    end

    subgraph "Build & Packaging"
        CMake["CMakeLists.txt"]:::utility
        Config["Config.cmake.in"]:::utility
    end

    subgraph "Docs & CI"
        Doxy["Doxyfile.in"]:::utility
        DoxygenSH["doxygen.sh"]:::utility
        BuildYML["build.yml"]:::utility
        ReleaseYML["release.yml"]:::utility
    end

    subgraph "Testing"
        UTCore["Unit Tests Core<br/>test/src/core/"]:::utility
        UTPhysics["Unit Tests Physics<br/>test/src/physics/"]:::utility
        ManualTest["Manual Tests<br/>test/src/manual/"]:::utility
        TestCMake["test/CMakeLists.txt"]:::utility
    end

    %% Connections
    ConsumerApps -->|"#include <cmdfx.h>"| API

    API -->|"calls"| AnimCore
    API -->|"calls"| CanvasCore
    API -->|"calls"| EventsCore
    API -->|"calls"| PhysicsCore
    API -->|"calls"| UICore

    AnimCore -->|"delegates to"| DeviceH
    CanvasCore -->|"delegates to"| ScreenH
    PhysicsCore -->|"uses"| UtilH

    DeviceH -->|"implements interface"| LinuxPS
    DeviceH -->|"implements interface"| MacPS
    DeviceH -->|"implements interface"| WinPS
    DeviceH -->|"implements interface"| PosixPS

    ScreenH -->|"implements interface"| LinuxPS
    ScreenH -->|"implements interface"| MacPS
    ScreenH -->|"implements interface"| WinPS
    ScreenH -->|"implements interface"| PosixPS

    UtilH -->|"implements interface"| LinuxPS
    UtilH -->|"implements interface"| MacPS
    UtilH -->|"implements interface"| WinPS
    UtilH -->|"implements interface"| PosixPS

    CMake -.->|"build-time"| API
    CMake -.->|"build-time"| AnimCore
    Config -.->|"generates"| CMake

    Doxy -.->|"documents"| API
    Doxy -.->|"documents"| AnimCore
    BuildYML -.->|"CI triggers"| CMake
    ReleaseYML -.->|"CI triggers"| CMake

    UTCore -.->|"tests"| AnimCore
    UTPhysics -.->|"tests"| PhysicsCore
    ManualTest -.->|"tests"| LinuxPS
    ManualTest -.->|"tests"| MacPS
    ManualTest -.->|"tests"| WinPS
    ManualTest -.->|"tests"| PosixPS

    %% Click Events
    click ConsumerApps "https://github.com/gmitch215/cmdfx/tree/master/samples/"
    click ConsumerApps "https://github.com/gmitch215/cmdfx/tree/master/test/src/manual/"
    click API "https://github.com/gmitch215/cmdfx/blob/master/include/cmdfx.h"
    click CanvasAPI "https://github.com/gmitch215/cmdfx/blob/master/include/cmdfx/core/canvas.h"
    click SpriteAPI "https://github.com/gmitch215/cmdfx/blob/master/include/cmdfx/core/sprites.h"
    click BuilderAPI "https://github.com/gmitch215/cmdfx/blob/master/include/cmdfx/core/builder.h"
    click EventsAPI "https://github.com/gmitch215/cmdfx/blob/master/include/cmdfx/core/events.h"
    click PhysicsAPI "https://github.com/gmitch215/cmdfx/tree/master/include/cmdfx/physics/"
    click UIAPI "https://github.com/gmitch215/cmdfx/tree/master/include/cmdfx/ui/"
    click AnimCore "https://github.com/gmitch215/cmdfx/tree/master/src/common/core/animation/"
    click CanvasCore "https://github.com/gmitch215/cmdfx/blob/master/src/common/core/canvas.c"
    click EventsCore "https://github.com/gmitch215/cmdfx/blob/master/src/common/core/events.c"
    click PhysicsCore "https://github.com/gmitch215/cmdfx/tree/master/src/common/physics/"
    click UICore "https://github.com/gmitch215/cmdfx/tree/master/src/common/ui/"
    click DeviceH "https://github.com/gmitch215/cmdfx/blob/master/include/cmdfx/core/device.h"
    click ScreenH "https://github.com/gmitch215/cmdfx/blob/master/include/cmdfx/core/screen.h"
    click UtilH "https://github.com/gmitch215/cmdfx/blob/master/include/cmdfx/core/util.h"
    click LinuxPS "https://github.com/gmitch215/cmdfx/blob/master/src/linux/core/device.c"
    click MacPS "https://github.com/gmitch215/cmdfx/blob/master/src/macos/core/device.c"
    click WinPS "https://github.com/gmitch215/cmdfx/blob/master/src/windows/core/device.c"
    click PosixPS "https://github.com/gmitch215/cmdfx/blob/master/src/posix/core/screen.c"
    click CMake "https://github.com/gmitch215/cmdfx/blob/master/CMakeLists.txt"
    click Config "https://github.com/gmitch215/cmdfx/blob/master/cmake/Config.cmake.in"
    click Doxy "https://github.com/gmitch215/cmdfx/blob/master/docs/Doxyfile.in"
    click DoxygenSH "https://github.com/gmitch215/cmdfx/blob/master/docs/doxygen.sh"
    click BuildYML "https://github.com/gmitch215/cmdfx/blob/master/.github/workflows/build.yml"
    click ReleaseYML "https://github.com/gmitch215/cmdfx/blob/master/.github/workflows/release.yml"
    click UTCore "https://github.com/gmitch215/cmdfx/tree/master/test/src/core/"
    click UTPhysics "https://github.com/gmitch215/cmdfx/tree/master/test/src/physics/"
    click ManualTest "https://github.com/gmitch215/cmdfx/tree/master/test/src/manual/"
    click TestCMake "https://github.com/gmitch215/cmdfx/blob/master/test/CMakeLists.txt"

    %% Styles
    classDef publicapi fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef platform fill:#ffddcc,stroke:#333,stroke-width:1px
    classDef utility fill:#e0e0e0,stroke:#333,stroke-width:1px
```
