# bycyrus/airi architecture

> Architecture diagram of the GitHub repository bycyrus/airi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bycyrus/airi
- Repository: https://github.com/bycyrus/airi

## Overview

AIRI is a multi-platform AI virtual-character project, with desktop, browser, and mobile applications supported by shared agent, speech, and character-rendering packages. The principal product workflow is user interaction with a character, followed by LLM response generation and spoken, animated output; the repository also includes Minecraft perception and computer-use capabilities. The tree and excerpts show selected internal links, but not enough to establish a complete app-to-package runtime chain, so those connections are omitted.

Main entry points: [`services/computer-use-mcp/src/workflows/engine.ts`](https://github.com/bycyrus/airi/blob/main/services/computer-use-mcp/src/workflows/engine.ts) (Computer-use workflow), [`integrations/minecraft/src/cognitive/perception/rules/engine.ts`](https://github.com/bycyrus/airi/blob/main/integrations/minecraft/src/cognitive/perception/rules/engine.ts) (Perception rules), [`packages/core-agent/src/runtime/llm-service.ts`](https://github.com/bycyrus/airi/blob/main/packages/core-agent/src/runtime/llm-service.ts) (LLM service), [`packages/stage-ui-live2d/src/composables/live2d/motion-manager.ts`](https://github.com/bycyrus/airi/blob/main/packages/stage-ui-live2d/src/composables/live2d/motion-manager.ts) (Live2D motion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["AIRI clients"]
  node_desktop["Desktop client"]
  node_browser["Browser client"]
  node_pocket["Pocket client"]
end

subgraph group_agent["Agent and tools"]
  node_llm["LLM service<br/>[llm-service.ts]"]
  node_responses["Responses stream<br/>[responses.ts]"]
  node_inference["Inference providers"]
  node_computer["Computer-use workflow<br/>[engine.ts]"]
  node_action["Action executor<br/>[action-executor.ts]"]
  node_workflow_state["Workflow state<br/>[state.ts]"]
  node_strategy["Action strategy<br/>[strategy.ts]"]
  node_transparency["Action transparency<br/>[transparency.ts]"]
end

subgraph group_speech["Speech and character"]
  node_audio_pipeline["Speech pipeline<br/>[speech-pipeline.ts]"]
  node_tts_chunker["TTS chunker<br/>[tts-chunker.ts]"]
  node_speech_runtime["Speech runtime"]
  node_streaming_tts["Streaming TTS"]
  node_motion["Live2D motion<br/>[motion-manager.ts]"]
  node_expressions["Expression control"]
  node_motion_state["Motion control state<br/>[motion-control.ts]"]
end

subgraph group_integrations["External integrations"]
  node_minecraft_pipeline["Minecraft perception<br/>[pipeline.ts]"]
  node_event_bus["Perception event bus<br/>[event-bus.ts]"]
  node_rule_engine["Perception rules<br/>[engine.ts]"]
  node_rule_matcher["Rule matcher<br/>[matcher.ts]"]
  node_temporal_detector["Temporal detector"]
  node_fall_tracker["Fall event<br/>[fall-tracker.ts]"]
end

subgraph group_mobile["Mobile bridges"]
  node_pocket_websocket["iOS WebSocket session"]
  node_pocket_bridge["iOS WebSocket bridge"]
  node_dualshock["DualSense controller<br/>[controller.ts]"]
  node_input_report["Controller input report<br/>[input-report.ts]"]
end

node_user(("User"))

node_user -.->|"interacts with"| node_desktop
node_user -.->|"interacts with"| node_browser
node_user -.->|"interacts with"| node_pocket
node_llm -->|"streams responses"| node_responses
node_llm -->|"uses provider"| node_inference
node_computer -->|"executes actions"| node_action
node_computer -->|"reads state"| node_workflow_state
node_computer -->|"evaluates strategy"| node_strategy
node_computer -->|"explains intent"| node_transparency
node_audio_pipeline -->|"segments speech"| node_tts_chunker
node_speech_runtime -->|"uses pipeline"| node_audio_pipeline
node_streaming_tts -.->|"delivers audio"| node_user
node_motion -->|"samples motion"| node_motion_state
node_motion -->|"applies expressions"| node_expressions
node_minecraft_pipeline -->|"uses event bus"| node_event_bus
node_minecraft_pipeline -->|"registers definitions"| node_fall_tracker
node_rule_engine -->|"emits signals"| node_event_bus
node_rule_engine -->|"renders matches"| node_rule_matcher
node_rule_engine -->|"processes windows"| node_temporal_detector
node_pocket_bridge -->|"uses session"| node_pocket_websocket
node_dualshock -->|"parses reports"| node_input_report

click node_desktop "https://github.com/bycyrus/airi/tree/main/apps/stage-tamagotchi/src/renderer"
click node_browser "https://github.com/bycyrus/airi/tree/main/apps/stage-web/src"
click node_pocket "https://github.com/bycyrus/airi/tree/main/apps/stage-pocket/src"
click node_llm "https://github.com/bycyrus/airi/blob/main/packages/core-agent/src/runtime/llm-service.ts"
click node_responses "https://github.com/bycyrus/airi/blob/main/packages/core-agent/src/runtime/responses.ts"
click node_inference "https://github.com/bycyrus/airi/tree/main/packages/provider-inference"
click node_computer "https://github.com/bycyrus/airi/blob/main/services/computer-use-mcp/src/workflows/engine.ts"
click node_action "https://github.com/bycyrus/airi/blob/main/services/computer-use-mcp/src/server/action-executor.ts"
click node_workflow_state "https://github.com/bycyrus/airi/blob/main/services/computer-use-mcp/src/state.ts"
click node_strategy "https://github.com/bycyrus/airi/blob/main/services/computer-use-mcp/src/strategy.ts"
click node_transparency "https://github.com/bycyrus/airi/blob/main/services/computer-use-mcp/src/transparency.ts"
click node_audio_pipeline "https://github.com/bycyrus/airi/blob/main/packages/pipelines-audio/src/speech-pipeline.ts"
click node_tts_chunker "https://github.com/bycyrus/airi/blob/main/packages/pipelines-audio/src/processors/tts-chunker.ts"
click node_speech_runtime "https://github.com/bycyrus/airi/blob/main/packages/stage-ui/src/services/speech/pipeline-runtime.ts"
click node_streaming_tts "https://github.com/bycyrus/airi/blob/main/packages/stage-ui/src/libs/speech/streaming-pipeline.ts"
click node_motion "https://github.com/bycyrus/airi/blob/main/packages/stage-ui-live2d/src/composables/live2d/motion-manager.ts"
click node_expressions "https://github.com/bycyrus/airi/blob/main/packages/stage-ui-live2d/src/composables/live2d/expression-controller.ts"
click node_motion_state "https://github.com/bycyrus/airi/blob/main/packages/stage-ui-live2d/src/stores/motion-control.ts"
click node_minecraft_pipeline "https://github.com/bycyrus/airi/blob/main/integrations/minecraft/src/cognitive/perception/pipeline.ts"
click node_event_bus "https://github.com/bycyrus/airi/blob/main/integrations/minecraft/src/cognitive/event-bus.ts"
click node_rule_engine "https://github.com/bycyrus/airi/blob/main/integrations/minecraft/src/cognitive/perception/rules/engine.ts"
click node_rule_matcher "https://github.com/bycyrus/airi/blob/main/integrations/minecraft/src/cognitive/perception/rules/matcher.ts"
click node_temporal_detector "https://github.com/bycyrus/airi/blob/main/integrations/minecraft/src/cognitive/perception/rules/temporal-detector.ts"
click node_fall_tracker "https://github.com/bycyrus/airi/blob/main/integrations/minecraft/src/cognitive/perception/events/definitions/fall-tracker.ts"
click node_pocket_websocket "https://github.com/bycyrus/airi/blob/main/apps/stage-pocket/ios/App/App/URLSessionHostWebSocketSession.swift"
click node_pocket_bridge "https://github.com/bycyrus/airi/blob/main/apps/stage-pocket/ios/App/App/HostWebSocketBridge.swift"
click node_dualshock "https://github.com/bycyrus/airi/blob/main/packages/input-playstation-dualsense-5/src/controller.ts"
click node_input_report "https://github.com/bycyrus/airi/blob/main/packages/input-playstation-dualsense-5/src/input-report.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_desktop,node_browser,node_pocket,node_user toneBlue
class node_llm,node_responses,node_inference,node_computer,node_action,node_workflow_state,node_strategy,node_transparency toneAmber
class node_audio_pipeline,node_tts_chunker,node_speech_runtime,node_streaming_tts,node_motion,node_expressions,node_motion_state toneMint
class node_minecraft_pipeline,node_event_bus,node_rule_engine,node_rule_matcher,node_temporal_detector,node_fall_tracker toneRose
class node_pocket_websocket,node_pocket_bridge,node_dualshock,node_input_report toneIndigo
```

## Components

### AIRI clients

- [Desktop client](https://github.com/bycyrus/airi/tree/main/apps/stage-tamagotchi/src/renderer): `apps/stage-tamagotchi/src/renderer`
- [Browser client](https://github.com/bycyrus/airi/tree/main/apps/stage-web/src): `apps/stage-web/src`
- [Pocket client](https://github.com/bycyrus/airi/tree/main/apps/stage-pocket/src): `apps/stage-pocket/src`

### Agent and tools

- [LLM service](https://github.com/bycyrus/airi/blob/main/packages/core-agent/src/runtime/llm-service.ts): `packages/core-agent/src/runtime/llm-service.ts`
- [Responses stream](https://github.com/bycyrus/airi/blob/main/packages/core-agent/src/runtime/responses.ts): `packages/core-agent/src/runtime/responses.ts`
- [Inference providers](https://github.com/bycyrus/airi/tree/main/packages/provider-inference): `packages/provider-inference`
- [Computer-use workflow](https://github.com/bycyrus/airi/blob/main/services/computer-use-mcp/src/workflows/engine.ts): `services/computer-use-mcp/src/workflows/engine.ts`
- [Action executor](https://github.com/bycyrus/airi/blob/main/services/computer-use-mcp/src/server/action-executor.ts): `services/computer-use-mcp/src/server/action-executor.ts`
- [Workflow state](https://github.com/bycyrus/airi/blob/main/services/computer-use-mcp/src/state.ts): `services/computer-use-mcp/src/state.ts`
- [Action strategy](https://github.com/bycyrus/airi/blob/main/services/computer-use-mcp/src/strategy.ts): `services/computer-use-mcp/src/strategy.ts`
- [Action transparency](https://github.com/bycyrus/airi/blob/main/services/computer-use-mcp/src/transparency.ts): `services/computer-use-mcp/src/transparency.ts`

### Speech and character

- [Speech pipeline](https://github.com/bycyrus/airi/blob/main/packages/pipelines-audio/src/speech-pipeline.ts): `packages/pipelines-audio/src/speech-pipeline.ts`
- [TTS chunker](https://github.com/bycyrus/airi/blob/main/packages/pipelines-audio/src/processors/tts-chunker.ts): `packages/pipelines-audio/src/processors/tts-chunker.ts`
- [Speech runtime](https://github.com/bycyrus/airi/blob/main/packages/stage-ui/src/services/speech/pipeline-runtime.ts): `packages/stage-ui/src/services/speech/pipeline-runtime.ts`
- [Streaming TTS](https://github.com/bycyrus/airi/blob/main/packages/stage-ui/src/libs/speech/streaming-pipeline.ts): `packages/stage-ui/src/libs/speech/streaming-pipeline.ts`
- [Live2D motion](https://github.com/bycyrus/airi/blob/main/packages/stage-ui-live2d/src/composables/live2d/motion-manager.ts): `packages/stage-ui-live2d/src/composables/live2d/motion-manager.ts`
- [Expression control](https://github.com/bycyrus/airi/blob/main/packages/stage-ui-live2d/src/composables/live2d/expression-controller.ts): `packages/stage-ui-live2d/src/composables/live2d/expression-controller.ts`
- [Motion control state](https://github.com/bycyrus/airi/blob/main/packages/stage-ui-live2d/src/stores/motion-control.ts): `packages/stage-ui-live2d/src/stores/motion-control.ts`

### External integrations

- [Minecraft perception](https://github.com/bycyrus/airi/blob/main/integrations/minecraft/src/cognitive/perception/pipeline.ts): `integrations/minecraft/src/cognitive/perception/pipeline.ts`
- [Perception event bus](https://github.com/bycyrus/airi/blob/main/integrations/minecraft/src/cognitive/event-bus.ts): `integrations/minecraft/src/cognitive/event-bus.ts`
- [Perception rules](https://github.com/bycyrus/airi/blob/main/integrations/minecraft/src/cognitive/perception/rules/engine.ts): `integrations/minecraft/src/cognitive/perception/rules/engine.ts`
- [Rule matcher](https://github.com/bycyrus/airi/blob/main/integrations/minecraft/src/cognitive/perception/rules/matcher.ts): `integrations/minecraft/src/cognitive/perception/rules/matcher.ts`
- [Temporal detector](https://github.com/bycyrus/airi/blob/main/integrations/minecraft/src/cognitive/perception/rules/temporal-detector.ts): `integrations/minecraft/src/cognitive/perception/rules/temporal-detector.ts`
- [Fall event](https://github.com/bycyrus/airi/blob/main/integrations/minecraft/src/cognitive/perception/events/definitions/fall-tracker.ts): `integrations/minecraft/src/cognitive/perception/events/definitions/fall-tracker.ts`

### Mobile bridges

- [iOS WebSocket session](https://github.com/bycyrus/airi/blob/main/apps/stage-pocket/ios/App/App/URLSessionHostWebSocketSession.swift): `apps/stage-pocket/ios/App/App/URLSessionHostWebSocketSession.swift`
- [iOS WebSocket bridge](https://github.com/bycyrus/airi/blob/main/apps/stage-pocket/ios/App/App/HostWebSocketBridge.swift): `apps/stage-pocket/ios/App/App/HostWebSocketBridge.swift`
- [DualSense controller](https://github.com/bycyrus/airi/blob/main/packages/input-playstation-dualsense-5/src/controller.ts): `packages/input-playstation-dualsense-5/src/controller.ts`
- [Controller input report](https://github.com/bycyrus/airi/blob/main/packages/input-playstation-dualsense-5/src/input-report.ts): `packages/input-playstation-dualsense-5/src/input-report.ts`

### Other components

- **User**

## Connections

- User → Desktop client: interacts with (evidence: `README.md`)
- User → Browser client: interacts with (evidence: `README.md`)
- User → Pocket client: interacts with (evidence: `README.md`)
- LLM service → Responses stream: streams responses (evidence: `packages/core-agent/src/runtime/llm-service.ts`)
- LLM service → Inference providers: uses provider (evidence: `packages/core-agent/src/runtime/llm-service.ts`)
- Computer-use workflow → Action executor: executes actions (evidence: `services/computer-use-mcp/src/workflows/engine.ts`)
- Computer-use workflow → Workflow state: reads state (evidence: `services/computer-use-mcp/src/workflows/engine.ts`)
- Computer-use workflow → Action strategy: evaluates strategy (evidence: `services/computer-use-mcp/src/workflows/engine.ts`)
- Computer-use workflow → Action transparency: explains intent (evidence: `services/computer-use-mcp/src/workflows/engine.ts`)
- Speech pipeline → TTS chunker: segments speech (evidence: `packages/pipelines-audio/src/speech-pipeline.ts`)
- Speech runtime → Speech pipeline: uses pipeline (evidence: `packages/stage-ui/src/services/speech/pipeline-runtime.ts`)
- Streaming TTS → User: delivers audio
- Live2D motion → Motion control state: samples motion (evidence: `packages/stage-ui-live2d/src/composables/live2d/motion-manager.ts`)
- Live2D motion → Expression control: applies expressions (evidence: `packages/stage-ui-live2d/src/composables/live2d/motion-manager.ts`)
- Minecraft perception → Perception event bus: uses event bus (evidence: `integrations/minecraft/src/cognitive/perception/pipeline.ts`)
- Minecraft perception → Fall event: registers definitions (evidence: `integrations/minecraft/src/cognitive/perception/pipeline.ts`)
- Perception rules → Perception event bus: emits signals (evidence: `integrations/minecraft/src/cognitive/perception/rules/engine.ts`)
- Perception rules → Rule matcher: renders matches (evidence: `integrations/minecraft/src/cognitive/perception/rules/engine.ts`)
- Perception rules → Temporal detector: processes windows (evidence: `integrations/minecraft/src/cognitive/perception/rules/engine.ts`)
- iOS WebSocket bridge → iOS WebSocket session: uses session (evidence: `apps/stage-pocket/ios/App/App/DevBridgeViewController.swift`)
- DualSense controller → Controller input report: parses reports (evidence: `packages/input-playstation-dualsense-5/src/controller.ts`)
