title: Architecture description: Follow AIRI from application shells through shared stage state, generation, audio, and separate service boundaries.

Architecture

AIRI is a pnpm monorepo, not one server with several skins. Application shells share packages, but each shell has different platform capabilities.

See setup for commands and capability-boundaries for the difference between source support and runtime proof.

Application shells and shared pages

The browser application lives in apps/stage-web. Its Vite configuration combines local pages with packages/stage-pages/src/pages and loads shared layouts.

The desktop application lives in apps/stage-tamagotchi. Its package entrypoint is out/main/index.js, and its development command uses Electron Vite.

The mobile application lives in apps/stage-pocket. Its manifest declares Capacitor Android and iOS targets. A browser preview does not prove native-device behavior.

All three application manifests depend on packages/stage-ui, packages/stage-pages, and shared rendering or audio packages. Shared dependencies do not imply identical feature availability.

The main ownership boundaries

Layer	Owner	Responsibility
Routes and layouts	Application directories, `packages/stage-pages`, `packages/stage-layouts`	Navigation and platform-specific screens
Product state	`packages/stage-ui`	Character selections, provider state, chat sessions, and UI lifecycle
Conversation execution	`packages/core-agent`	Scheduling, context composition, tool rounds, and generation events
Provider definitions	`packages/provider-inference`	Provider registration, configuration schemas, instance creation, and generation protocols
Audio policies	`packages/pipelines-audio`	Playback scheduling, text chunks, and transcript buffering
Audio utilities	`packages/audio`	Low-level audio functions, separate from product state

flowchart TD
    Web[Browser shell] --> UI[Shared stage UI and state]
    Desktop[Electron shell] --> UI
    Mobile[Capacitor shell] --> UI
    UI --> Agent[Core-agent conversation execution]
    Agent --> Providers[Provider-inference definitions]
    Providers --> Endpoint[Configured endpoint or subsystem]
    UI --> Audio[Audio pipelines]
    UI --> Display[Display model and renderer]
    UI -. optional .-> Hosted[Hosted API and Auth]
    UI -. optional .-> Channel[Server channel]

This diagram shows responsibility, not a claim that every branch runs in every session.

A text turn through the source

The stage chat store connects application state to createChatOrchestratorRuntime. Core-agent owns the conversation execution contract. The application supplies persistence and UI through its ports.

The Consciousness module owns the selected generation provider and model. Provider-inference owns protocol selection and provider construction. It does not own Vue state, saved credentials, authentication, or Electron-native providers.

This split matters during changes. A provider protocol change belongs at the provider boundary. A saved selection or settings-page change belongs in the stage application layer.

See modules for the product modules and providers-and-models for configuration identity.

Two different server systems

The hosted backend under server/ contains the resource API and standalone Auth service. Its local Compose stack also contains PostgreSQL, Redis, and Caddy.

The server channel under packages/server-runtime is a separate H3-based WebSocket runtime. Its SDK and shared protocol packages remain under packages/ for cross-runtime use.

pnpm dev:backend and pnpm dev:server select different systems. Neither command is a substitute for the other. Read services-and-integrations before adding service dependencies.

Source context

All references use the upstream revision recorded in provenance.

apps/stage-web/vite.config.ts, lines 150–171: shared routes, layouts, and UnoCSS.
packages/stage-ui/src/stores/chat.ts, lines 1–41: conversation runtime and stage-state dependencies.
packages/core-agent/README.md, lines 1–47: conversation ownership and protocol limits.
packages/provider-inference/README.md, lines 1–20: portable provider boundary.
packages/pipelines-audio/README.md, lines 1–15: audio-policy ownership.
packages/server-runtime/src/server/index.ts, lines 1–35: H3 server controller.

Navigation: index · modules · services-and-integrations

Project AIRI

Explorer