# tango-tango/cask architecture

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

- Interactive diagram: https://gitdiagram.com/tango-tango/cask
- Repository: https://github.com/tango-tango/cask

## Overview

This project is a C++ header-only library (with a few source files) designed to build asynchronous and event-driven programs using reactive and functional programming ideas. Its main purpose is to provide lazy, composable constructs—namely Task and Observable—to help users build cooperative, highly concurrent applications even on single-threaded environments. The library is built with C++17 and supports various building blocks such as fibers, schedulers, pools, and deferred operations.

##### Project’s Main Components
- Task: Represents the lazy, asynchronous computation. Label its core functions (e.g., eval, flatMap, map, etc.).
- Observable: Models reactive streams and event flows, offering operations like filter, flatMap, and take.
- Execution and Concurrency Infrastructure:
- Scheduler: Illustrate the different scheduler types provided (e.g., BenchScheduler, SingleThreadScheduler, and WorkStealingScheduler) which run the event loop.
- Fiber: Represent the fiber components (CurrentFiber, FiberOp, FiberValue, etc.) that make cooperative multitasking possible.
- Supporting Components:
- Deferred & Promises: Show that these modules support asynchronous operations.
- MVar, Pool, Resource, List, and Queue: Include these as auxiliary components that handle state, resource management, and concurrency control.
- Build and Integration:
- Although primarily a header-only library, note the separation of public API (in the include folder) and core implementation (in the src folder). Include a block representing Meson build system integration.
- Testing Infrastructure:
- Optionally, note the test modules as a verification layer, which indicates how each component is tested through unit tests in the test directory.

##### Relationships and Data Flow
- That Observables can depend on or compose with Tasks and vice versa.
- Interdependency between the Scheduler and helper modules (like the pool or deferred operations) that work behind the scenes to manage concurrency.
- That components like MVar and Queue are used within the Observable implementations for managing state and backpressure.

##### Architectural Patterns and Design Principles
- Functional Composition: Clearly show that Tasks and Observables use monadic operations (map, flatMap, filter, etc.) to compose asynchronous operations.
- Lazy Evaluation: Use annotations to note that these constructs do not execute until explicitly run, which is essential for testability and dependency injection.
- Concurrency & Cooperative Multitasking: Illustrate the role of fibers and various schedulers, showing how they abstract away the low-level concurrency details.

##### Final Checklist
- Component (Task, Observable, Scheduler, Fiber, etc.) is accurately labeled.
- Notes on architectural patterns such as lazy evaluation, monadic composition, and dependency injection to highlight design decisions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Integration Layer
    BI1("Public API"):::build
    BI2("Core Implementation"):::build

    %% Core API
    subgraph "Core API"
        API1("Task (async computation: eval,flatMap,map)"):::api
        API2("Observable (reactive streams: filter,flatMap,take)"):::api
        API3("Deferred"):::support
        API4("Promise"):::support
        API5("MVar"):::support
        API6("Pool"):::support
        API7("Resource"):::support
        API8("List"):::support
        API9("Queue"):::support
    end

    %% Concurrency Engine
    subgraph "Concurrency Engine"
        CE1("Scheduler (Bench,SingleThread,WorkStealing)"):::engine
        CE2("Fiber (Cooperative multitasking)"):::engine
        CE3("Event Loop/Fiber Runtime"):::engine
    end

    %% Testing Infrastructure
    TI1("Unit Tests"):::test

    %% Relationships between Build & Integration and Core Components
    BI1 --> API1
    BI1 --> API2
    BI1 --> API3
    BI1 --> API4
    BI1 --> API5
    BI1 --> API6
    BI1 --> API7
    BI1 --> API8
    BI1 --> API9

    BI2 --> CE1
    BI2 --> CE2

    %% Core API to Concurrency Engine interactions
    API1 -->|"schedules"| CE1
    API2 -->|"composes"| API1
    API2 -->|"managesState"| API5

    %% Concurrency Engine internal flow
    CE1 -->|"utilizes"| API6
    CE1 -->|"triggers"| CE2
    CE2 -->|"runsOn"| CE3

    %% Testing connections
    API1 --> TI1
    API2 --> TI1
    CE1 --> TI1

    %% Click Events
    click API1 "https://github.com/tango-tango/cask/blob/main/include/cask/Task.hpp"
    click API2 "https://github.com/tango-tango/cask/blob/main/include/cask/Observable.hpp"
    click CE1 "https://github.com/tango-tango/cask/tree/main/include/cask/scheduler"
    click CE2 "https://github.com/tango-tango/cask/tree/main/include/cask/fiber"
    click API3 "https://github.com/tango-tango/cask/blob/main/include/cask/Deferred.hpp"
    click API4 "https://github.com/tango-tango/cask/blob/main/include/cask/Promise.hpp"
    click API5 "https://github.com/tango-tango/cask/blob/main/include/cask/MVar.hpp"
    click API6 "https://github.com/tango-tango/cask/blob/main/include/cask/Pool.hpp"
    click API7 "https://github.com/tango-tango/cask/blob/main/include/cask/Resource.hpp"
    click API8 "https://github.com/tango-tango/cask/blob/main/include/cask/List.hpp"
    click API9 "https://github.com/tango-tango/cask/blob/main/include/cask/Queue.hpp"
    click BI1 "https://github.com/tango-tango/cask/tree/main/include"
    click BI2 "https://github.com/tango-tango/cask/tree/main/src"
    click TI1 "https://github.com/tango-tango/cask/tree/main/test"

    %% Styles
    classDef api fill:#FFDDCC,stroke:#D2691E,stroke-width:2px;
    classDef support fill:#CCFFCC,stroke:#008000,stroke-width:2px;
    classDef engine fill:#CCE5FF,stroke:#1E90FF,stroke-width:2px;
    classDef build fill:#FFF2CC,stroke:#DAA520,stroke-width:2px;
    classDef test fill:#FFDDAA,stroke:#FF8C00,stroke-width:2px;
```
