Skip to content
paiOS Docs

C4 Architecture Model

This page documents the paiOS architecture using the C4 model: a hierarchical approach to software architecture visualization.

Level 1: System Context Diagram

Section titled “Level 1: System Context Diagram”

The highest level of abstraction: paiEngine (the core AI engine platform) and its external actors and systems. The engine provides flexible APIs that enable others to build custom user interfaces on top; the smartphone app (paiApp) is one primary interface for mobile/wearable form factors.

flowchart TD
  User(("👤 User<br/>[Person]"))

  PAI["📦 paiEngine<br/>[Software System]<br/>The Core AI Engine Platform<br/>Provides APIs: REST, gRPC<br/>MCP Server + MCP Client"]

  paiApp["📱 paiApp<br/>[External System]<br/>First-Party Companion App<br/>(Smartphone/Desktop)<br/>Primary interface for configuration<br/>& interaction with device"]

  World["🌍 Physical Environment<br/>[External System]<br/>Visual and auditory impressions<br/>of reality"]

  HostPC["💻 Host Computer & Clients<br/>[External System]<br/>Apps connecting to the AI: Obsidian, OpenWebUI,<br/>Cursor, Claude Desktop, OpenClaw<br/>Can build custom GUIs/HMIs"]

  CloudAI["☁️ Cloud AI Services<br/>[External System]<br/>Optional fallback AI (OpenAI, Anthropic)<br/>for highly complex tasks"]

  ExtMCP["🏠 External MCP Servers<br/>[External System]<br/>Home Assistant, Calendar,<br/>Web Search, SQLite Memory"]

  User -->|"Primary: Uses smartphone app<br/>for configuration & control"| paiApp
  User -->|"Secondary: Voice, buttons<br/>(direct hardware interaction)"| PAI
  paiApp -->|"Configures & controls<br/>via gRPC (UDS/TCP)"| PAI
  PAI -->|"Captures sensor data<br/>(image & sound) from"| World
  PAI -->|"Provides APIs<br/>(REST/gRPC + MCP Server)"| HostPC
  HostPC -->|"Configures & controls<br/>via USB/WiFi/Network"| PAI
  PAI -->|"Delegates tasks<br/>(Opt-In)"| CloudAI
  PAI -->|"MCP Client:<br/>Executes tools &<br/>retrieves data"| ExtMCP
Diagram (Expanded View)

The actors, systems, and containers in both diagrams are described in a single table: Actors and containers (after the Level 2 diagram).

Level 2: Container Diagram

Section titled “Level 2: Container Diagram”

Shows the main containers (deployable units) within the paiOS environment and how they interact.

flowchart TD
  User(("👤 User<br/>[Person]"))

  subgraph PAI_Boundary ["paiOS Environment (Local AI Device / Rockchip SoC)"]
      Engine["⚙️ paiEngine<br/>[Container: Rust]<br/>Core AI Engine. Coordinates hardware<br/>(NPU, Vision, Audio).<br/>MCP Server + MCP Client"]
      LocalDB[("🗄️ Local Storage<br/>[Container: SQLite]<br/>Stores permissions, user configs<br/>and medium-term memory")]
      LocalMCP["🔌 Local MCP Servers<br/>[Container: Subprocesses]<br/>Local system tools (e.g., Device Control,<br/>Local File Access)"]
      ThirdPartyApp["📱 3rd Party App<br/>[Container: Node/Python/Rust]<br/>Runs locally on the [AI device](/glossary/#a)"]
  end

  subgraph Host_Boundary ["Host Computer (PC / Mac)"]
      UI["🖥️ 3rd Party Clients<br/>[Container: Web/Desktop App]<br/>OpenWebUI, Obsidian, VSCode"]
      MCPClients["🤖 MCP Clients<br/>[Container: Desktop App]<br/>OpenClaw, Cursor, Claude Desktop"]
      paiApp["📱 paiApp<br/>[Container: Mobile/Desktop App]<br/>First-Party Companion App"]
  end

  Hardware["📷 Hardware & OS<br/>[Infrastructure]<br/>Rockchip NPU, Cameras, Microphones,<br/>USB-C Gadget, Network"]
  Cloud["☁️ Cloud APIs<br/>[External System]"]
  ExternalMCPServer["🏠 External MCP Servers<br/>[External System]<br/>e.g., Home Assistant"]

  User -->|"Primary: Uses smartphone app<br/>for configuration & control"| paiApp
  User -->|"Secondary: Hardware buttons / Voice<br/>(direct interaction)"| Engine
  User -->|"Uses"| UI
  User -->|"Uses"| MCPClients

  UI -->|"API Requests<br/>[REST: Ollama/OpenAI]"| Engine
  MCPClients -->|"MCP Server:<br/>Tool/sensor requests<br/>(MCP via SSE/stdio)"| Engine
  paiApp -->|"Local: gRPC over UDS<br/>Remote: gRPC over TCP/TLS"| Engine
  ThirdPartyApp -->|"IPC: gRPC over UDS"| Engine

  Engine -->|"Reads / Writes<br/>[SQL]"| LocalDB
  Engine -->|"Calls local tools<br/>[JSON-RPC 2.0]"| LocalMCP
  Engine -->|"Driver access<br/>[V4L2, ALSA, RKNN]"| Hardware
  Engine -->|"Fallback Inference<br/>[HTTPS]"| Cloud
  Engine -->|"MCP Client:<br/>Calls external tools<br/>(MCP)"| ExternalMCPServer
Diagram (Expanded View)

Actors and containers

Section titled “Actors and containers”

All actors, external systems, and containers shown in the Level 1 and Level 2 diagrams. Grouped by type for easier scanning.

Name Type Protocol / technology Role / responsibility
User Person - Primary: smartphone app (paiApp) for configuration and control. Secondary: voice, buttons for direct hardware interaction. Engine is flexible: others can build custom GUIs/HMIs on top.
paiEngine Container Rust (Tokio), REST, gRPC, MCP Core AI engine. Coordinates NPU, Vision, Audio, and all APIs. MCP Server (clients connect to use engine as tool/sensor) and MCP Client (engine calls external tools).
Local Storage Container SQLite Permissions, user config, medium-term memory.
Local MCP Servers Container Subprocesses, JSON-RPC 2.0 Local tool execution (device control, file access).
paiApp External system gRPC (UDS local, TCP/TLS remote) First-party companion app (smartphone/desktop). Primary interface for configuring and interacting with the AI device.
Physical Environment External system - Sensor capture: camera and microphone capture real-world data.
3rd Party Clients External system REST (Ollama/OpenAI), gRPC (UDS/TCP) OpenWebUI, Obsidian, VSCode. Developers can build custom GUIs/HMIs on top (local: gRPC/UDS; remote: gRPC/TCP or REST).
3rd Party Apps (Local) Container gRPC (UDS) Applications running directly on the AI device. Connects to the engine via Unix Domain Sockets for high-performance IPC.
MCP Clients External system MCP (SSE/stdio) OpenClaw, Cursor, Claude Desktop. Connect to engine (engine as MCP Server).
Cloud AI Services External system HTTPS (opt-in) Fallback inference (OpenAI, Anthropic) for highly complex tasks.
External MCP Servers External system MCP Home Assistant, Calendar, Web Search, SQLite Memory. Engine as MCP Client calls these to execute tools and retrieve data.
Hardware & OS Infrastructure V4L2, ALSA, RKNN Rockchip NPU, cameras, microphones, USB-C gadget, network.
Local applications (same hardware) Connection gRPC over UDS Primary IPC interface: comparable to Linux syscalls. For applications/services on the same hardware where paiEngine runs.
External clients (other PCs) Connection gRPC over TCP/TLS, REST, MCP Network communication with other PCs.

Level 3: Component Diagram (pai-engine)

Section titled “Level 3: Component Diagram (pai-engine)”

Zooms into the pai-engine container to show its internal components following Hexagonal Architecture (Ports and Adapters pattern). The diagram uses a Driving / Driven view: external actors and clients (left), engine domains in the center (Common, Peripherals, Core, Vision, Audio, Inference), and outputs or external systems (right). Protocols and data flows (e.g. gRPC/UDS, gRPC/TCP/TLS, REST, MCP) match the Level 1 and Level 2 descriptions earlier in this page.

Section titled “Related Documentation”