# companion-thecube/core architecture

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

- Interactive diagram: https://gitdiagram.com/companion-thecube/core
- Repository: https://github.com/companion-thecube/core

## Overview

##### Project type and purpose
- This is a full-stack, embedded C++ “core” application for a Raspberry-Pi-based desktop companion (“Companion, TheCube”) that integrates:
- A local 3D GUI (SFML/OpenGL)
- A built-in HTTP/REST server serving a web UI
- A modular decision engine (NLP, scheduling, personality)
- App management (native, Docker, Python)
- Audio I/O (speech in/out)
- Hardware drivers (Bluetooth, Wi-Fi, IMU, NFC, mmWave)
- Persistence (SQLite) + telemetry + localization

##### File structure
- Top-level folders:
- src/api → REST endpoints, authentication, builder
- src/decisionEngine → intent registry, triggers, scheduler, transcriber, personality, remote API
- src/gui → 3D scene graph, mesh loader, shaders, event handler, menus
- src/audio → audio capture & playback
- src/apps → app lifecycle & APIs (native/Docker/Python)
- src/hardware → low-level drivers & peripheral manager
- src/database → SQLite wrappers (cubeDB, db)
- src/logger, src/telemetry → logging & telemetry pipelines
- src/settings, src/utils, src/config.cpp → configuration loader, util functions
- Static web UI assets in http/
- CMakeLists.txt, .env example, install-deps.sh, tests/ and benchmarks/

##### Insights from README
- Uses cpp-httplib for HTTP server, SFML/OpenGL for GUI, SQLite for persistence, GoogleTest for unit tests, GetText for i18n
- Reads .env for HTTP address/port and IPC socket
- Provides both local GUI and remote web UI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Layer
    subgraph "Hardware Layer"
        HW_Bluetooth["Bluetooth"]:::hardware
        HW_WiFi["Wi-Fi"]:::hardware
        HW_IMU["IMU"]:::hardware
        HW_NFC["NFC"]:::hardware
        HW_mmWave["mmWave"]:::hardware
        HW_PeripheralMgr["Peripheral Manager"]:::hardware
    end

    %% Core Services Layer
    subgraph "Core Services Layer"
        CS_ConfigLoader["Config Loader"]:::core
        CS_GlobalSettings["Global Settings"]:::core
        CS_Logger["Logger"]:::core
        CS_Telemetry["Telemetry Pipeline"]:::core
        CS_Database["Database Wrappers"]:::core
        CS_IPCSocket["IPC Socket Server"]:::core
    end

    %% Decision Engine Layer
    subgraph "Decision Engine Layer"
        DE_IntentRegistry["Intent Registry"]:::engine
        DE_FunctionRegistry["Function Registry"]:::engine
        DE_Triggers["Triggers"]:::engine
        DE_Scheduler["Scheduler"]:::engine
        DE_PersonalityMgr["Personality Manager"]:::engine
        DE_Transcriber["Transcriber (STT)"]:::engine
        DE_RemoteAPI["Remote API/Server"]:::engine
    end

    %% Application Manager Layer
    subgraph "Application Manager Layer"
        AM_AppsManager["Apps Manager"]:::appmgr
        AM_AppsDBManager["AppsDB Manager"]:::appmgr
        AM_NativeAPI["Native API"]:::appmgr
        AM_DockerAPI["Docker API"]:::appmgr
        AM_PythonAPI["Python API"]:::appmgr
    end

    %% Audio Layer
    subgraph "Audio Layer"
        AU_SpeechIn["Speech Input (STT)"]:::audio
        AU_AudioOutput["Audio Output (TTS)"]:::audio
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        subgraph "Local GUI"
            GUI_Renderer["Renderer & Scene"]:::ui
            GUI_EventHandler["Event Handler"]:::ui
            GUI_Menu["Menus"]:::ui
            GUI_MessageBox["Message Boxes"]:::ui
            GUI_MeshLoader["Mesh Loader"]:::ui
            GUI_Shaders["Shaders"]:::ui
            GUI_StatusBar["Status Bar"]:::ui
        end
        subgraph "HTTP UI"
            HTTP_Server["HTTP/REST Server"]:::ui
            HTTP_Static["Static Web Assets"]:::ui
        end
    end

    %% Connections
    HW_PeripheralMgr -->|"peripheral events"| CS_IPCSocket
    HW_PeripheralMgr -->|"peripheral events"| CS_ConfigLoader
    HW_PeripheralMgr -->|"peripheral events"| DE_IntentRegistry

    CS_ConfigLoader -->|"config data"| DE_Scheduler
    CS_GlobalSettings -->|"settings"| DE_PersonalityMgr
    CS_IPCSocket -->|"IPC commands"| DE_RemoteAPI

    CS_Database <-->|"read/write"| CS_Logger
    CS_Database <-->|"read/write"| DE_Triggers

    CS_Logger -->|"log events"| CS_Telemetry

    DE_IntentRegistry -->|"intent event"| DE_Triggers
    DE_Triggers -->|"trigger"| AM_AppsManager
    AM_AppsManager -->|"app status"| DE_Triggers

    DE_Transcriber -->|"STT data"| DE_IntentRegistry
    DE_Transcriber -->|"STT data"| AU_SpeechIn
    AU_AudioOutput -->|"TTS"| DE_PersonalityMgr

    DE_PersonalityMgr -->|"TTS output"| AU_AudioOutput
    DE_PersonalityMgr -->|"display/update"| GUI_Renderer
    DE_RemoteAPI -->|"HTTP RPC"| HTTP_Server

    HTTP_Server -->|"serve files"| HTTP_Static

    %% Click Events
    click HW_PeripheralMgr "https://github.com/companion-thecube/core/tree/master/src/hardware"
    click CS_ConfigLoader "https://github.com/companion-thecube/core/blob/master/src/config.cpp"
    click CS_GlobalSettings "https://github.com/companion-thecube/core/blob/master/src/settings/globalSettings.cpp"
    click CS_Logger "https://github.com/companion-thecube/core/blob/master/src/logger/logger.cpp"
    click CS_Telemetry "https://github.com/companion-thecube/core/blob/master/src/telemetry/telemetry.cpp"
    click CS_Database "https://github.com/companion-thecube/core/blob/master/src/database/cubeDB.cpp"
    click DE_IntentRegistry "https://github.com/companion-thecube/core/blob/master/src/decisionEngine/intentRegistry.cpp"
    click DE_FunctionRegistry "https://github.com/companion-thecube/core/blob/master/src/decisionEngine/functionRegistry.cpp"
    click DE_Triggers "https://github.com/companion-thecube/core/blob/master/src/decisionEngine/triggers.cpp"
    click DE_Scheduler "https://github.com/companion-thecube/core/blob/master/src/decisionEngine/scheduler.cpp"
    click DE_PersonalityMgr "https://github.com/companion-thecube/core/blob/master/src/decisionEngine/personalityManager.cpp"
    click DE_Transcriber "https://github.com/companion-thecube/core/blob/master/src/decisionEngine/transcriber.cpp"
    click DE_RemoteAPI "https://github.com/companion-thecube/core/blob/master/src/decisionEngine/remoteServer.cpp"
    click AM_AppsManager "https://github.com/companion-thecube/core/blob/master/src/apps/appsManager.cpp"
    click AM_AppsDBManager "https://github.com/companion-thecube/core/blob/master/src/apps/appsDBManager.cpp"
    click AM_NativeAPI "https://github.com/companion-thecube/core/blob/master/src/apps/nativeApi.cpp"
    click AM_DockerAPI "https://github.com/companion-thecube/core/blob/master/src/apps/dockerApi.cpp"
    click AM_PythonAPI "https://github.com/companion-thecube/core/blob/master/src/apps/pythonApi.cpp"
    click AU_SpeechIn "https://github.com/companion-thecube/core/blob/master/src/audio/speechIn.cpp"
    click AU_AudioOutput "https://github.com/companion-thecube/core/blob/master/src/audio/audioOutput.cpp"
    click GUI_Renderer "https://github.com/companion-thecube/core/blob/master/src/gui/renderer.cpp"
    click GUI_EventHandler "https://github.com/companion-thecube/core/blob/master/src/gui/eventHandler/eventHandler.cpp"
    click GUI_Menu "https://github.com/companion-thecube/core/blob/master/src/gui/menu/menu.cpp"
    click GUI_MessageBox "https://github.com/companion-thecube/core/blob/master/src/gui/messageBox/messageBox.cpp"
    click GUI_MeshLoader "https://github.com/companion-thecube/core/blob/master/src/gui/renderables/meshLoader.cpp"
    click GUI_Shaders "https://github.com/companion-thecube/core/blob/master/src/gui/shader.cpp"
    click HTTP_Server "https://github.com/companion-thecube/core/blob/master/src/api/api.cpp"
    click HTTP_Static "https://github.com/companion-thecube/core/blob/master/http/index.html"

    %% Styles
    classDef hardware fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef engine fill:#ffd9b3,stroke:#333,stroke-width:1px
    classDef appmgr fill:#e0b3ff,stroke:#333,stroke-width:1px
    classDef audio fill:#b3ecff,stroke:#333,stroke-width:1px
    classDef ui fill:#e0e0e0,stroke:#333,stroke-width:1px
```
