Layer Architecture

This page presents the paiOS architecture as a layered stack, similar to how Android documentation visualizes its system architecture.

System Layers Overview

graph TB
  subgraph Layer5["📱 Application Layer"]
      App1["First Party Apps"]
      App2["Third Party Apps"]
      App3["Intelligence Packs"]
  end

  subgraph Layer4["🔌 API Layer"]
      gRPC["gRPC API - UDS"]
      Proto["Protobuf - MIT"]
  end

  subgraph Layer3["🧠 Core Engine Layer"]
      RPC["rpc/"]
      Core["core/"]
      Orch["orchestrator/"]
  end

  subgraph Layer2["⚙️ HAL Layer"]
      AudioHAL["Audio"]
      NPUHAL["NPU"]
      GPUHAL["GPU"]
      HIDHAL["HID"]
      CameraHAL["Camera"]
      LEDHAL["LED"]
  end

  subgraph Layer1["💾 OS Layer"]
      Kernel["Linux Kernel"]
      Drivers["Device Drivers"]
      Systemd["systemd"]
      RAUC["RAUC"]
  end

  subgraph Layer0["🔧 Hardware Layer"]
      SoC["RK3588S2 - 6 TOPS NPU"]
      Mic["Microphone Array"]
      USB["USB-C"]
      Camera["Camera Module"]
      Battery["Battery"]
  end

  Layer5 --> Layer4
  Layer4 --> Layer3
  Layer3 --> Layer2
  Layer2 --> Layer1
  Layer1 --> Layer0

Layer Descriptions

🔧 Layer 0: Hardware

The physical components of the paiOS device.

Component	Description	Version
SoC	Rockchip RK3588S2 with 6 TOPS NPU + Mali-G610 GPU	V1.0+
Microphone	USB mic (Dev) / 3-mic beamforming array (Pro)	V1.0+
USB-C	Composite device (HID + UAC + Mass Storage)	V1.0+
Camera	UVC camera module for Vision models	V2.0+
Battery	Integrated battery for standalone operation	V2.0+

💾 Layer 1: Operating System

Custom Debian-based OS built with Debos.

Component	Technology	Purpose
Kernel	Radxa Vendor Kernel (via APT)	Hardware support for RK3588S2
Drivers	NPU, GPU, USB Gadget, i2s	Hardware access
systemd	Service Manager	Manages pai-daemon lifecycle
RAUC	A/B Update System	Atomic, reliable OTA updates

⚙️ Layer 2: Hardware Abstraction Layer (HAL)

Abstracts hardware details from the core engine.

HAL Module	Technology	Responsibility
Audio HAL	`cpal`	Cross-platform audio capture, VAD
NPU HAL	`rknn-sys`	Rockchip NPU inference via bindgen
GPU HAL	OpenCL	Mali-G610 fallback inference
HID HAL	`usb-gadget`	USB keyboard emulation
Camera HAL	V4L2	Video capture (V2.0+)
LED HAL	GPIO	Status indicators

🧠 Layer 3: Core Engine

The “brain” of paiOS – pure Rust following Clean Architecture.

Module	Role	Responsibility
`rpc/`	Interface Adapter	gRPC/UDS communication, Protobuf conversion
`core/`	Domain Layer	SystemController, state machine, business logic
`orchestrator/`	Application Logic	InferenceOrchestrator, NPU/GPU/CPU routing

Dependency Direction:

rpc/ → core/ ← orchestrator/ → hal/

The domain layer (core/) has no dependencies on other modules.

🔌 Layer 4: API Layer

The interface between Engine and Apps.

Component	License	Description
gRPC API	MIT	Unix Domain Socket communication
Protobuf	MIT	Type-safe message definitions

📱 Layer 5: Application Layer

User-facing apps and Intelligence Packs.

Component	License	Description
First Party Apps	MIT	Reference implementations in `apps/`
Third Party Apps	Varies	Built with `pai-builder` SDK
Intelligence Packs	Proprietary	Encrypted models + workflows for B2B

Form Factor Evolution

The same software stack runs on evolving hardware:

timeline
  title paiOS Product Evolution
  
  section V1.0 paiLink Dev
      Radxa Rock 5C : USB HID
      Whisper NPU : gRPC Core
      
  section V1.5 paiLink Pro
      CNC Case : Secure Boot
      Mic Array : Intelligence Packs
      
  section V2.0 Power Stick
      Custom PCB : Battery
      Camera : Vision Inference
      
  section V3.0 paiGo
      paiGo Form : Always-On AI
      Multi-Modal : Context Awareness

Technology Stack

Layer	Technology	License
OS Build	Debos	AGPL-3.0
OS Updates	RAUC	LGPL-2.1
Core Engine	Rust (2021)	AGPL-3.0
Async Runtime	Tokio	MIT
IPC	gRPC (Tonic + Prost)	MIT
NPU Bindings	rknn-sys (bindgen)	AGPL-3.0
Audio	cpal	Apache-2.0
HID	usb-gadget	MIT
Client Apps	Flutter (optional)	BSD-3
API Definitions	Protobuf	MIT
Documentation	Starlight (Astro)	MIT

C4 Architecture – System Context and Container diagrams
Clean Architecture – Dependency direction and module roles
Architecture Decision Records – Key architectural decisions