# adamabdelhamed/klooie architecture

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

## Overview

##### Project type and purpose
- **Type**: Open-source .NET framework / library for building GUI applications in any .NET-capable console.
- **Purpose**: Provide controls, containers, animation, theming, input/focus, observability, gaming & physics, audio, video playback, and CLI application hosting. Consumers write console apps that reference the klooie core modules.

##### File structure
Top-level grouping under `src/`:
- **klooie core libraries**:
- Animation, Audio, Containers, Controls, Dialogs, Focus, Forms, Gaming, Geometry, InternalHelpers, Observability, Theming, Video, ConsoleApp (hosting & event loop)
- **Supporting projects**:
- `klooie.Analyzers` (Roslyn source generators for observability & pools)
- `klooie.Windows` (Windows‐only audio playback engine)
- `klooie.VideoPlayer` (sample console video player)
- `Playground` (scratch app with resource‐based sound)
- `Samples` (dozens of sample apps demonstrating features)
- **Test projects** under `src/tests/`: cover core libraries and samples.
- **Solution & CI**: `klooie.sln`, GitHub Actions workflow (`.github/workflows/dotnet.yml`), NuGet packaging.

##### Extract README insights
- High-level categories: Containers & Layout, Controls, Dialogs, Theming, Focus, Forms, Animations, Observability, plus advanced: Physics, Sound (Windows).
- Shows typical usage pattern: derive from `ConsoleApp`, compose a `LayoutRoot` with controls, call `.Run()`.
- External placeholder: PowerArgs for CLI parsing.

a. **Main components**
- **ConsoleApp Host** (EventLoop, FrameRateMeter, InnerLoopAPIs)
- **Core Modules** grouped by domain:
- **Rendering & Drawing**: ConsoleBitmap, Filters, Geometry
- **UI Framework**: Controls ← Containers ← Forms ← Dialogs
- **Input & Focus**
- **Theming & Styles**
- **Animation & Easing**
- **Observability & Data Binding**
- **Gaming & Physics**
- **Audio** (via ISoundProvider, Windows engine)
- **Video Playback** (ConsoleBitmapPlayer)
- **Source Generators**: klooie.Analyzers → augment Observability & pooling
- **Sample & Playground Apps**: HelloWorld, GamingSample, VideoPlayer, Playground
- **Test Harness** (UITestManager, AppTest, GamingTest)
- **External Dependencies**: .NET runtime, PowerArgs, System.Console, Windows APIs

b. **Relationships & interactions**
- **Apps** → reference → **ConsoleApp Host** → uses → **Core Modules**
- **Core Modules** layered:
· Rendering calls Geometry & ConsoleBitmap
· Controls composed via Containers; Containers use Layout, Rendering
· Input & Focus broker keyboard to Controls
· Animation sequences values over time, hooking into EventLoop
· Observability supplies change notifications to UI/Animations
· Theming supplies styling metadata to Controls
· Gaming/Physics modules subscribe to EventLoop; use Geometry & Observability; emit rendering commands
· Audio layer pluggable via ISoundProvider; Windows engine implements provider
· VideoPlayer reads/writes ConsoleBitmap streams; uses Rendering & EventLoop
- **Source Generators** run at build time to inject code into Observability and pooling frameworks.
- **Tests** execute in-process UI tests via UITestManager and capture ConsoleBitmap output.

c. **Architectural patterns & principles**
- **Layered architecture**: Presentation (ConsoleApp, UI) atop Engine (Rendering/Drawing) atop Helpers (Geometry, InternalHelpers).
- **MVVM-like data binding** via Observability → UI reacts to model changes.
- **Plugin / provider pattern** for audio, source generators, controls.
- **Event Loop** driving all time-based services (Animations, Gaming, Video).
- **Separation of concerns**: each domain in its own folder/project.

d. **Key technologies/frameworks**
- .NET 6+ / .NET Standard
- Roslyn source generators (`klooie.Analyzers`)
- System.Console for rendering
- PowerArgs for CLI argument parsing
- GitHub Actions for CI

##### Essential details to capture
- The **EventLoop** as the “heartbeat” connecting Animation, Gaming, Video, and ConsoleApp.
- The **UI composition**: LayoutRoot → Containers → Controls pipelines.
- The **build‐time** augmentation by klooie.Analyzers into Observability/pooling.
- **Sample apps** and **tests** as consumers validating end-to-end scenarios.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Sample and Test Consumers
    subgraph "Consumers"
        A1["Playground App"]:::ext
        A2["Sample Apps"]:::ext
        A3["Automated Tests"]:::ext
    end

    %% Core Host
    subgraph "ConsoleApp Host" 
        direction TB
        CA["ConsoleApp"]:::coreUI
        EL["EventLoop"]:::coreEngine
        FRM["FrameRateMeter"]:::coreEngine
        ILA["InnerLoopAPIs"]:::coreEngine
    end

    %% Core Modules
    subgraph "Rendering & Drawing" 
        RB["ConsoleBitmap"]:::coreEngine
    end

    subgraph "Filters"
        FI["IConsoleControlFilter"]:::coreEngine
        FA["AnimationFilter"]:::coreEngine
        FB["BackgroundColorFilter"]:::coreEngine
        FF["FadeInFadeOut"]:::coreEngine
        FG["ForegroundColorFilter"]:::coreEngine
    end

    subgraph "Geometry"
        GE["Geometry Math"]:::coreEngine
    end

    subgraph "UI Framework"
        direction TB
        CT["Controls"]:::coreUI
        CN["Containers"]:::coreUI
        FM["Forms"]:::coreUI
        DL["Dialogs"]:::coreUI
    end

    IF["Input & Focus"]:::coreUI
    TH["Theming & Styles"]:::coreUI
    AN["Animation & Easing"]:::coreEngine
    OB["Observability & Data Binding"]:::data
    IH["Internal Helpers & Pools"]:::coreEngine
    GM["Gaming & Physics"]:::coreEngine
    AU["Audio Abstraction"]:::ext
    VE["Video Playback"]:::coreEngine
    SG["Source Generators"]:::ext
    TF["Test Framework"]:::ext

    %% Relationships
    A1 -->|references| CA
    A2 -->|references| CA
    A3 -->|runs| TF
    TF -->|hosts tests| CA

    CA -->|uses| EL
    CA -->|uses| FRM
    CA -->|uses| ILA

    EL -->|drives| AN
    EL -->|drives| GM
    EL -->|drives| VE

    CA -->|renders via| RB
    RB -->|applies| FI
    RB -->|applies| FA
    RB -->|applies| FB
    RB -->|applies| FF
    RB -->|applies| FG
    RB -->|calls| GE

    CA -->|hosts UI| CT
    CT -->|placed in| CN
    CN -->|generated by| FM
    FM -->|opens| DL

    CA -->|handles input| IF
    CT -->|styled by| TH
    AN -->|observes| OB
    CT -->|binds to| OB

    GM -->|uses| GE
    GM -->|observes| OB
    GM -->|emits render to| RB

    AU -->|interface| ISP["ISoundProvider"]
    ISP -->|implemented by| WAE["WindowsAudioEngine"] 
    CA -->|plays sound via| AU

    VE -->|reads/writes| RB
    VE -->|sync via| EL

    SG -->|augments build| OB
    SG -->|augments build| IH

    %% Click Events
    click CA "https://github.com/adamabdelhamed/klooie/blob/main/src/klooie/ConsoleApp/ConsoleApp.cs"
    click EL "https://github.com/adamabdelhamed/klooie/blob/main/src/klooie/ConsoleApp/EventLoop.cs"
    click FRM "https://github.com/adamabdelhamed/klooie/blob/main/src/klooie/ConsoleApp/FrameRateMeter.cs"
    click ILA "https://github.com/adamabdelhamed/klooie/blob/main/src/klooie/ConsoleApp/InnerLoopAPIs.cs"
    click RB "https://github.com/adamabdelhamed/klooie/blob/main/src/klooie/Drawing/ConsoleBitmap.cs"
    click FI "https://github.com/adamabdelhamed/klooie/blob/main/src/klooie/Filters/IConsoleControlFilter.cs"
    click FA "https://github.com/adamabdelhamed/klooie/blob/main/src/klooie/Filters/AnimationFilter.cs"
    click FB "https://github.com/adamabdelhamed/klooie/blob/main/src/klooie/Filters/BackgroundColorFilter.cs"
    click FF "https://github.com/adamabdelhamed/klooie/blob/main/src/klooie/Filters/FadeInFadeOut.cs"
    click FG "https://github.com/adamabdelhamed/klooie/blob/main/src/klooie/Filters/ForegroundColorFilter.cs"
    click GE "https://github.com/adamabdelhamed/klooie/tree/main/src/klooie/Geometry"
    click CT "https://github.com/adamabdelhamed/klooie/tree/main/src/klooie/Controls"
    click CN "https://github.com/adamabdelhamed/klooie/tree/main/src/klooie/Containers"
    click FM "https://github.com/adamabdelhamed/klooie/tree/main/src/klooie/Forms"
    click DL "https://github.com/adamabdelhamed/klooie/tree/main/src/klooie/Dialogs"
    click IF "https://github.com/adamabdelhamed/klooie/blob/main/src/klooie/Focus/FocusManager.cs"
    click TH "https://github.com/adamabdelhamed/klooie/tree/main/src/klooie/Theming"
    click AN "https://github.com/adamabdelhamed/klooie/tree/main/src/klooie/Animation"
    click OB "https://github.com/adamabdelhamed/klooie/tree/main/src/klooie/Observability"
    click IH "https://github.com/adamabdelhamed/klooie/tree/main/src/klooie/InternalHelpers"
    click GM "https://github.com/adamabdelhamed/klooie/tree/main/src/klooie/Gaming"
    click AU "https://github.com/adamabdelhamed/klooie/tree/main/src/klooie/Audio"
    click WAE "https://github.com/adamabdelhamed/klooie/blob/main/src/klooie.Windows/AudioPlaybackEngine.cs"
    click VE "https://github.com/adamabdelhamed/klooie/tree/main/src/klooie/Video"
    click SG "https://github.com/adamabdelhamed/klooie/blob/main/src/klooie.Analyzers"
    click A1 "https://github.com/adamabdelhamed/klooie/blob/main/src/Playground/Program.cs"
    click A2 "https://github.com/adamabdelhamed/klooie/tree/main/src/Samples"
    click TF "https://github.com/adamabdelhamed/klooie/blob/main/src/klooie/TestFramework/UITestManager.cs"
    click A3 "https://github.com/adamabdelhamed/klooie/tree/main/src/tests"

    %% Styles
    classDef coreUI fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef coreEngine fill:#ffd9b3,stroke:#333,stroke-width:1px
    classDef data fill:#d4edda,stroke:#333,stroke-width:1px
    classDef ext fill:#fff3cd,stroke:#333,stroke-width:1px
```
