# forairaaaaa/mooncake architecture

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

- Interactive diagram: https://gitdiagram.com/forairaaaaa/mooncake
- Repository: https://github.com/forairaaaaa/mooncake

## Overview

##### Project type and purpose
- Mooncake is an embedded C++ framework for microcontroller units (MCU). It provides a multi-app management and scheduling system, abstracting application behaviors as “Abilities” and offering lifecycle management for each.
- It is not a full-stack app but rather a library/framework that runs on bare-metal or RTOS-based MCUs, allowing developers to plug in multiple “AppAbility” instances and other Ability types (UIAbility, WorkerAbility, BasicAbility).

##### File structure
- Top-level:
- CMakeLists.txt + cmake/ → build configuration for cross-platform and ESP-IDF builds
- src/ → framework core code
– src/mooncake.cpp/.h → Mooncake class, the core scheduler
– src/ability/ → definitions of AbilityBase and derived Ability types
– src/ability_manager/ → AbilityManager implementation and API wrapping
- example/ → C++ demo applications showing how to install/open/close abilities
- test/ → Python-based automated tests against example outputs
- Configuration and metadata: .clang-format, .gitignore, LICENSE, library.json/properties
- CI config in .github/workflows for multi-platform CMake builds

##### README for additional insights
- Describes the core concepts:
- AbilityBase with onCreate/baseUpdate/baseDestroy
- Derived Ability types: BasicAbility, UIAbility, WorkerAbility, AppAbility, each with distinct lifecycle graphs
- Mooncake holds two AbilityManager instances: one for AppAbility, one for extensions (any AbilityBase)
- Shows usage patterns: installApp, openApp, update loop, thread-safety considerations

##### Main components
a. Hardware layer
– MCU (target hardware platform)
b. Framework core
– Mooncake (central scheduler)
– AbilityManager for AppAbility
– AbilityManager for ExtensionAbility
c. Ability hierarchy
– AbilityBase (abstract)
– AppAbility, UIAbility, WorkerAbility, BasicAbility (derived classes)
d. User-provided code
– User App classes (derive from AppAbility)
– Extensions (derive from other Ability types)
e. Build and test infrastructure (optional detail)
– CMake toolchain
– Python test runner

##### Relationships and interactions
- API calls (installApp, createExtension) → Mooncake → appropriate AbilityManager → stores Ability instance → returns ID
- update() loop in Mooncake → iterates over both AbilityManagers → calls baseUpdate() on each Ability → dispatches to specific lifecycle callbacks (onOpen, onRunning, etc.)
- openApp/closeApp → AppAbilityManager → state transitions in AppAbility
- Manager pattern: AbilityManager hides storage, ID allocation, and raw lifecycle scheduling

##### Architectural patterns and design principles
- Inversion of control / plugin architecture: user code injects derived Ability instances
- Manager pattern: centralized creation/destruction and dispatching
- State-machine lifecycles: each Ability type implements a small state machine
- Single-threaded event loop by default; thread-safety via user-provided locking
- Layered design: low-level hardware build scripts → framework core → user extensions

##### Relevant technologies, frameworks, and libraries
- C++17 (unique_ptr, override)
- CMake (modular scripts, esp-idf integration)
- Python (pytest or custom tests under test/)
- GitHub Actions for CI

- “MCU Hardware”
- “CMake Build System” (optional)
- “Mooncake Scheduler”
- “AppAbility Manager”
- “Extension Ability Manager”
- “AbilityBase & Derived Types”
- “User App Modules”
- “User Extensions”
- API calls → Managers → Stored Abilities
- update() loop → Managers → Ability callbacks

##### Final recommendation
- Be exhaustive in separating each responsibility: build, core scheduler, managers, base class, derived classes, user code
- Plugin-style extensibility and event-driven loop clearly
- Labels and flows are unambiguous—this will directly map to code modules under src/ and example/

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build Infrastructure
    subgraph "Build Infrastructure"
        nodeCMakeList["CMakeLists.txt"]:::build
        nodeCmakeDir["cmake/"]:::build
    end

    %% Hardware Layer
    subgraph "Hardware Layer"
        nodeMCU["MCU Hardware"]:::hw
    end

    %% Framework Core
    subgraph "Framework Core"
        mc["Mooncake Scheduler"]:::core
        subgraph "Managers"
            mApp["AppAbility Manager"]:::core
            mExt["Extension Ability Manager"]:::core
        end
        subgraph "Ability Hierarchy"
            base["AbilityBase"]:::ability
            appA["AppAbility"]:::ability
            uiA["UIAbility"]:::ability
            workA["WorkerAbility"]:::ability
            basicA["BasicAbility"]:::ability
        end
        subgraph "AppAbility Lifecycle"
            st1(["onCreate"]):::lifecycle --> st2(["onOpen"]):::lifecycle
            st2 --> st3(["onRunning"]):::lifecycle
            st3 --> st4(["onDestroy"]):::lifecycle
        end
    end

    %% User Code
    subgraph "Example User App Modules"
        bd["basic_demo.cpp"]:::user
        ma["multiple_apps_demo.cpp"]:::user
        st["singleton_test.cpp"]:::user
        at["app_ability_test.cpp"]:::user
        ut["ui_ability_test.cpp"]:::user
        amt["ability_manager_test.cpp"]:::user
    end
    subgraph "Example User Extensions"
        ext["extension_test.cpp"]:::user
    end

    %% Tests & CI
    subgraph "Tests & CI"
        ci["CI Configuration"]:::build
        pyTest["Python Test Runner"]:::test
    end

    %% Connections
    nodeCMakeList -->|"configures build for"| mc
    nodeCmakeDir -->|"provides toolchain"| mc
    mc -->|"runs on"| nodeMCU

    bd -->|"installApp()"| mc
    ma -->|"installApp()"| mc
    st -->|"installApp()"| mc
    at -->|"installApp()"| mc
    ut -->|"installApp()"| mc
    amt -->|"installApp()"| mc

    ext -->|"createExtension()"| mc

    mc -->|"delegates"| mApp
    mc -->|"delegates"| mExt

    mApp -->|"manages"| appA
    mApp -->|"uses"| base
    mExt -->|"manages"| uiA
    mExt -->|"manages"| workA
    mExt -->|"manages"| basicA
    mExt -->|"uses"| base

    mc -->|"update() loop"| mApp
    mc -->|"update() loop"| mExt

    mApp -->|"baseUpdate()"| appA
    mExt -->|"baseUpdate()"| uiA
    mExt -->|"baseUpdate()"| workA
    mExt -->|"baseUpdate()"| basicA

    pyTest -.->|runs tests on| bd
    pyTest -.->|runs tests on| ma
    pyTest -.->|runs tests on| ext

    ci -->|triggers| pyTest

    %% Click Events
    click nodeCMakeList "https://github.com/forairaaaaa/mooncake/blob/main/CMakeLists.txt"
    click nodeCmakeDir "https://github.com/forairaaaaa/mooncake/tree/main/cmake/"
    click mc "https://github.com/forairaaaaa/mooncake/blob/main/src/mooncake.cpp"
    click mc "https://github.com/forairaaaaa/mooncake/blob/main/src/mooncake.h"
    click mApp "https://github.com/forairaaaaa/mooncake/blob/main/src/ability_manager/ability_manager.cpp"
    click mApp "https://github.com/forairaaaaa/mooncake/blob/main/src/ability_manager/ability_manager.h"
    click mExt "https://github.com/forairaaaaa/mooncake/blob/main/src/ability_manager/ability_api_wrapping.cpp"
    click base "https://github.com/forairaaaaa/mooncake/blob/main/src/ability/ability.h"
    click appA "https://github.com/forairaaaaa/mooncake/blob/main/src/ability/app_ability.cpp"
    click uiA "https://github.com/forairaaaaa/mooncake/blob/main/src/ability/ui_ability.cpp"
    click workA "https://github.com/forairaaaaa/mooncake/blob/main/src/ability/worker_ability.cpp"
    click bd "https://github.com/forairaaaaa/mooncake/blob/main/example/basic_demo.cpp"
    click ma "https://github.com/forairaaaaa/mooncake/blob/main/example/multiple_apps_demo.cpp"
    click st "https://github.com/forairaaaaa/mooncake/blob/main/example/singleton_test.cpp"
    click at "https://github.com/forairaaaaa/mooncake/blob/main/example/app_ability_test.cpp"
    click ut "https://github.com/forairaaaaa/mooncake/blob/main/example/ui_ability_test.cpp"
    click amt "https://github.com/forairaaaaa/mooncake/blob/main/example/ability_manager_test.cpp"
    click ext "https://github.com/forairaaaaa/mooncake/blob/main/example/extension_test.cpp"
    click pyTest "https://github.com/forairaaaaa/mooncake/blob/main/test/example_output_test.py"
    click ci "https://github.com/forairaaaaa/mooncake/blob/main/.github/workflows/cmake-multi-platform.yml"

    %% Styles
    classDef build fill:#f9f,stroke:#333,stroke-width:1px
    classDef hw fill:#bbf,stroke:#333,stroke-width:1px
    classDef core fill:#bfb,stroke:#333,stroke-width:1px
    classDef ability fill:#ffb,stroke:#333,stroke-width:1px
    classDef user fill:#fbb,stroke:#333,stroke-width:1px
    classDef test fill:#fbf,stroke:#333,stroke-width:1px
    classDef lifecycle fill:#fff,stroke:#999,stroke-dasharray: 5 5px
```
