# cacao-research/cacao architecture

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

- Interactive diagram: https://gitdiagram.com/cacao-research/cacao
- Repository: https://github.com/cacao-research/cacao

## Overview

##### Project Type & Purpose
- Cacao is a Python-based web framework with real-time, reactive UIs, Hot-Reload, PWA and native desktop support.
- It provides a decorator-based API (`@mix`), JSON UI definitions, component/state isolation, plugin/extension infrastructure, and seamless frontend-backend integration.

##### High-Level File Structure
- Top-Level:
- `cacao_cli.py` / `desktop.py` (CLI entrypoints for web & desktop ‘brew’ commands)
- `Dockerfile` / `docker-compose.yml` / CI workflows (build/deploy)
- `examples/`, `docs/`, `test/`
- Core Package (`cacao/`):
- `cli/` – codegen and scaffolding commands
- `core/` – HTTP + WebSocket server, routing decorators, state management, diffing, PWA, session persistence, static asset serving
- `ui/` – component library (data, forms, navigation, layout), theming system, React integration
- `extensions/` – auth, metrics, plugin entrypoints
- `plugins/` – built-in renderer & plugin implementations
- `utilities/` – caching, background task queue

##### Key Architectural Elements (from README)
- Decorator-based routing → registry of endpoints (`core/decorators.py`)
- Hot-reload via WebSocket channel (`core/server.py`, `static/js/websocket.js`)
- JSON UI definitions & diffing engine (`core/diffing.py`)
- Reactive state (`core/state.py`) & session persistence (`core/session.py`)
- Component system with isolated per-component state (`Component` base class + `component_type`)
- PWA support (`core/pwa.py`, service-worker & manifest generation)
- Desktop mode wrapper (`desktop.py`)
- Extensions & plugin hooks (auth, metrics, ReactExtension)

##### Main Components & Interactions
A. CLI / App Launcher
- Reads `cacao.json`, initializes `App()` with optional extensions, parses `brew()` params (web vs desktop)
B. CacaoServer
- HTTP server (serves static assets + API endpoints)
- WebSocket server (hot-reload & real-time UI updates)
C. Router & Decorators
- Registers view functions (`@mix("/")`), event handlers (`@mix.event`) → maps URLs / actions to handlers
D. State Store & Session Layer
- In-memory / file-based sessions, `State` objects per component, update triggers diff
E. Diffing & Renderer
- Computes minimal JSON patch between old/new UI trees → pushes updates over WebSocket or HTTP
F. UI Component System & Theming
- Component classes in `ui/components`, theme loader applies CSS variables, ReactBridge for 3rd-party React
G. Static Asset Server & PWA
- Serves JS/CSS/HTML template, generates `manifest.json` and service-worker script
H. Desktop Wrapper
- Launches a native window (Electron or WebView), spins up local CacaoServer, proxies UI
I. Extensions & Plugins
- Hook into lifecycle (auth hooks, metrics collectors, custom plugins such as pandas_table)
J. Utilities
- Background task queue for long-running jobs, cache layer

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Tooling Layer"
        CLICLI["cacao_cli.py"]:::cli
        DesktopScript["desktop.py"]:::cli
        Commands["commands.py"]:::cli
        Codegen["codegen.py"]:::cli
        AppInit["app.py"]:::cli
    end

    subgraph "Server Layer"
        CoreServer["CacaoServer (HTTP + WS)"]:::core
        Router["Router & Decorators"]:::core
        StaticAssets["Static Asset Server"]:::core
        PWAService["PWA Support"]:::core
    end

    subgraph "Component Layer"
        Renderer["Diffing & Renderer Engine"]:::state
        UIComp["UI Component System & Theming"]:::ui
    end

    subgraph "Persistence Layer"
        StateStore["State Store"]:::state
        SessionLayer["Session Layer"]:::state
        Cache["Cache"]:::util
        TaskQueue["Task Queue"]:::util
    end

    subgraph "Extension/Plugin Layer"
        Extensions["Extensions & Plugins"]:::ext
    end

    subgraph "Client Layer"
        Browser["Browser"]:::client
        DesktopWrapper["Desktop Wrapper"]:::client
    end

    %% Connections
    CLICLI -->|launches| CoreServer
    DesktopScript -->|launches| CoreServer
    Commands -->|codegen| AppInit
    Codegen -->|scaffolding| AppInit
    AppInit -->|initializes| CoreServer

    CoreServer -->|routes| Router
    CoreServer -->|serves| StaticAssets
    CoreServer -->|pwa init| PWAService
    CoreServer -->|reads/writes| StateStore
    CoreServer -->|reads/writes| SessionLayer
    CoreServer -->|utilizes| Cache
    CoreServer -->|schedules| TaskQueue

    Router -->|dispatches| StateStore
    StateStore -->|updates trigger| Renderer
    SessionLayer -->|persists| StateStore
    Renderer -->|builds UI| UIComp

    UIComp -->|renders| Browser
    PWAService -->|service worker| Browser
    StaticAssets -->|assets| Browser

    Browser -->|events| CoreServer
    Browser -->|WebSocket diff patches| Renderer
    DesktopWrapper -->|hosts| Browser
    DesktopWrapper -->|proxies| CoreServer

    CoreServer -->|extension hooks| Extensions
    UIComp -->|react bridge| Extensions

    %% Click Events
    click CLICLI "https://github.com/cacao-research/cacao/blob/main/cacao_cli.py"
    click DesktopScript "https://github.com/cacao-research/cacao/blob/main/cacao/desktop.py"
    click Commands "https://github.com/cacao-research/cacao/blob/main/cacao/cli/commands.py"
    click Codegen "https://github.com/cacao-research/cacao/blob/main/cacao/cli/codegen.py"
    click AppInit "https://github.com/cacao-research/cacao/blob/main/cacao/core/app.py"
    click CoreServer "https://github.com/cacao-research/cacao/blob/main/cacao/core/server.py"
    click Router "https://github.com/cacao-research/cacao/blob/main/cacao/core/decorators.py"
    click StateStore "https://github.com/cacao-research/cacao/blob/main/cacao/core/state.py"
    click SessionLayer "https://github.com/cacao-research/cacao/blob/main/cacao/core/session.py"
    click Renderer "https://github.com/cacao-research/cacao/blob/main/cacao/core/diffing.py"
    click PWAService "https://github.com/cacao-research/cacao/blob/main/cacao/core/pwa.py"
    click UIComp "https://github.com/cacao-research/cacao/tree/main/cacao/ui/components/"
    click Extensions "https://github.com/cacao-research/cacao/tree/main/cacao/extensions/"
    click Cache "https://github.com/cacao-research/cacao/blob/main/cacao/utilities/cache.py"
    click TaskQueue "https://github.com/cacao-research/cacao/blob/main/cacao/utilities/task_queue.py"

    %% Styles
    classDef core fill:#cce5ff,stroke:#66b2ff,color:#003366
    classDef state fill:#d4edda,stroke:#28a745,color:#155724
    classDef ui fill:#fff3cd,stroke:#ffc107,color:#856404
    classDef ext fill:#e2e3e5,stroke:#6c757d,color:#343a40
    classDef util fill:#f8f9fa,stroke:#adb5bd,color:#495057
    classDef cli fill:#e9ecef,stroke:#ced4da,color:#495057
    classDef client fill:#fff5e6,stroke:#ffcc80,color:#663c00
```
