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

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

⛶ Fullscreen

Diagram (Expanded View) ✕ Close (ESC)

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

Note

paiEngine is a platform: The engine provides flexible APIs. gRPC over Unix Domain Sockets (UDS) is the primary IPC interface for applications/services running on the same hardware: similar to how Linux syscalls provide the primary interface for applications to interact with the kernel. For communicating with other PCs over the network, the engine provides gRPC over TCP/TLS. This enables third-party developers to build custom user interfaces, GUIs, HMIs, and applications both locally (via UDS) and remotely (via TCP/TLS). REST (Ollama/OpenAI compatibility) and MCP are also supported for specific integration scenarios. The smartphone app (paiApp) is the first-party reference implementation, but the engine itself is designed to be extended.

---

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

⛶ Fullscreen

Diagram (Expanded View) ✕ Close (ESC)

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)

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.

Loading diagram…

Full detail in ADR-004

This is the canonical L3 view. For the full rationale behind each component, dependency rules, and the sys-crate pattern, see ADR-004: Engine Architecture.

---

Related Documentation

• OS & Infrastructure: Full layer stack with technology table
• Hexagonal Architecture: Dependency direction and module roles
• Architecture Decision Records: Key architectural decisions