reference-architecture.md

Status: foundation context This document describes completed Phase 1 foundation work and architectural context. It is not the primary source of truth for the current release target. For the active MVP contract, see docs/product/current-product-contract.md and docs/vision/personal-operations-os-mvp.md. For the active architecture boundary, see docs/architecture/current-system-boundary.md.

Phase 1 Reference Architecture

Purpose

Capture the realistic Phase 1 system shape for a home-brew LifeOS server and route readers into the detailed subsystem documents.

System Overview

                AI LIFE OPERATING SYSTEM
                         |
         |---------------|---------------|
         |               |               |
   AI Reasoning     Event Bus       Life Graph
         |               |               |
         |---------------|---------------|
                         |
      Local Orchestration Mesh + Modules
                         |
      |------------|-------------|-------------|
      |            |             |             |
 Smart Home   Production    Personal Life   Communications
 Automation     Systems        Modules         Systems

The Personal AI Node is a local infrastructure platform. Everything meaningful flows through a shared event model and a shared life graph. The event bus carries change. The life graph carries durable context. The reasoning layer and local orchestration mesh decide what to do with both.

Mesh vocabulary in this document:

• local orchestration mesh: bounded runtime coordination in current local deployments
• node/federation mesh: optional/future cross-node delegation context
• mesh service: only when referring to a separately deployed runtime/service boundary

Reference Deployment Posture

• single-node home server first
• Docker Compose as the default deployment approach
• optional later move to Kubernetes only if complexity justifies it
• local processing preferred for language, voice, vision, and planning

Key Subsystems

• Hardware Profile: the home-server class machine this phase targets.
• Reference Stack: the open-source services and deployment posture.
• Architecture Overview: how the core components fit together.
• Voice and Media: room awareness, voice pipeline, receptionist, follow-me media, and displays.
• Security and Privacy: local-first protections for a highly personal system.
• User Interfaces: voice, mobile, dashboard, and terminal surfaces.

Reference Module Areas

• smart home and room awareness
• production systems such as hydroponics, mushroom growing, 3D printing, or crafts
• personal economic planning
• health and fitness
• communications and receptionist flows
• social and community coordination

Phase 1 Constraint

This reference architecture is detailed and ambitious, but it is still a single-node local system. Inter-node coordination, global agentic protocols, and large-scale collective intelligence remain outside current delivery scope.