Architecture Overview

Architecture Documentation

paiOS architecture documentation falls into three categories:

📐 Architecture Views

High-level visualizations of the system from different perspectives:

• C4 Architecture: System Context, Container, and Component diagrams (C4 model)
• OS and Infrastructure: OS, Hardware, and Deployment context

🧩 Engine Domains

Detailed documentation for each domain crate, covering ports, adapters, feature flags, and data flow:

• Domains Overview: Index of all domain crates
• Common: Shared foundation (logging, config, permissions)
• Core: Orchestrator, SessionManager, FlowRunner
• Inference: AI backends, resource management, MCP client
• Audio: Audio capture, playback, signal conditioning
• Vision: Camera, frame processing, motion gating
• API: API Gateway, protocol adapters, routing
• Peripherals: HMI, buttons, LEDs, haptics

🔧 Cross-Cutting Concerns

Topics that span multiple domains:

• Workspace and Build: Feature flags, sys-crate pattern, default profiles, build configuration, and platform support (multi-platform engine, Linux desktop for development, contributor welcome for other OS)
• Composition Root (main.rs): The only place that knows which adapters exist; bootstrap, init, and dependency injection
• Security Architecture: Permission system, port isolation, HITL workflow

📋 Architecture Decision Records (ADRs)

ADRs document the “why” behind key decisions. They capture context, alternatives considered, and consequences; not implementation details:

• ADR Index: All Architecture Decision Records
• ADR-004: Engine Architecture: Core Engine architectural decisions (Hexagonal Architecture, Modular Monolith, Hybrid Inference)

Hexagonal Architecture

paiOS uses Hexagonal Architecture (Ports and Adapters). Rust traits map to Ports; feature-gated structs map to Adapters. Dependencies point inward; pai-engine/src/main.rs is the Composition Root.

Vendor Flexibility and Rapid Porting: While the Rockchip RK3588 is the initial deployment target, this architecture ensures the engine is completely vendor-agnostic. Hardware-specific SDKs are isolated in adapters, meaning the system can be rapidly ported to new SoCs (e.g., from NVIDIA, Qualcomm, or Apple) without rewriting any core business logic.

paiEngine is a flexible platform: The engine provides multiple APIs. gRPC over Unix Domain Sockets (UDS) is the primary IPC interface for applications/services running on the same hardware: comparable to Linux syscalls. For communicating with external clients on other machines, the engine provides gRPC over TCP/TLS. REST (Ollama/OpenAI compatibility) and MCP are also supported for specific use cases. For mobile/wearable form factors, a smartphone companion app can serve as a user interface for configuration and interaction; the engine itself is designed to be extended for any AI device.

                    ┌─────────────────────────────┐
  Driving           │         Domain              │         Driven
  Adapters ──────►  │  (Ports = Rust Traits)      │  ──────► Adapters
  (API, HMI)        │  (Pure business logic)      │  (Camera, NPU, Mic)
                    └─────────────────────────────┘

Code Layout

Package by Feature: Each domain crate contains its own domain logic, ports (traits), and feature-gated adapters. See Workspace and Build for the full workspace structure.

ADRs vs. Module Documentation

Documentation Type	Purpose	Example
ADRs	Document decisions and their rationale	”Why Hexagonal Architecture?”
Module docs	Document current state implementation	”How inference manages resources”
Cross-cutting docs	Document shared concerns across modules	”Feature flag conventions”