How cacao-research/cacao works
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