# moeru-ai/airi architecture

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

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

## Overview

AIRI is a multi-platform, LLM-powered virtual-character project. Users interact with a character through desktop, browser, or mobile experiences; the broader product includes conversational AI, speech, animated avatars, and integrations. The graph highlights the sampled agent and speech internals, plus major product branches visible in the README and tree. Source evidence is uneven: several platform and integration branches are represented by their exact directories, but their internal call paths were not sampled, so no speculative connections are drawn for them.

Main entry points: [`packages/core-agent/src/runtime/llm-service.ts`](https://github.com/moeru-ai/airi/blob/main/packages/core-agent/src/runtime/llm-service.ts) (LLM service), [`apps/stage-tamagotchi`](https://github.com/moeru-ai/airi/tree/main/apps/stage-tamagotchi) (Desktop character), [`integrations/minecraft/src/cognitive/perception/pipeline.ts`](https://github.com/moeru-ai/airi/blob/main/integrations/minecraft/src/cognitive/perception/pipeline.ts) (Perception pipeline), [`packages/stage-ui/src/libs/speech/streaming-pipeline.ts`](https://github.com/moeru-ai/airi/blob/main/packages/stage-ui/src/libs/speech/streaming-pipeline.ts) (Streaming TTS client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User experiences"]
  node_desktop["Desktop character"]
  node_mobile["Mobile companion"]
  node_web["Web stage"]
  node_renderer["Desktop renderer"]
end

subgraph group_agent["Conversation runtime"]
  node_core["LLM service<br/>[llm-service.ts]"]
  node_chatstream["Chat completion stream"]
  node_responses["Responses stream<br/>[responses.ts]"]
  node_requestctx["Request context<br/>[request-context.ts]"]
end

subgraph group_voice["Speech and inference"]
  node_audioengine["Speech pipeline<br/>[speech-pipeline.ts]"]
  node_uitts["Streaming TTS client"]
  node_voicevox["VOICEVOX engine<br/>[engine.ts]"]
  node_ttsadapter["Volcengine TTS adapter<br/>[volcengine.ts]"]
end

subgraph group_characters["Character rendering"]
  node_mediapipe["Motion capture engine<br/>[engine.ts]"]
  node_live2d["Live2D motion manager<br/>[motion-manager.ts]"]
  node_mmd["MMD animation manager"]
end

subgraph group_integrations["Integrations"]
  node_minecraft["Minecraft integration"]
  node_perception["Perception pipeline<br/>[pipeline.ts]"]
  node_rules["Perception rule engine<br/>[engine.ts]"]
  node_satori["Satori bot planner<br/>[llm-client.ts]"]
  node_computeruse["Computer-use workflows<br/>[engine.ts]"]
  node_telegram["Telegram bot"]
  node_twitter["Twitter services"]
end

node_user(("User"))

node_user -->|"uses"| node_desktop
node_user -->|"uses"| node_mobile
node_user -->|"uses"| node_web
node_user -.->|"interacts"| node_renderer
node_core -->|"dispatches"| node_chatstream
node_core -->|"dispatches"| node_responses
node_core -->|"checks compatibility"| node_requestctx
node_uitts -->|"uses audio stream"| node_audioengine
node_ttsadapter -.->|"optional provider"| node_voicevox
node_perception -.->|"feeds events"| node_rules
node_minecraft -.->|"uses"| node_perception
node_satori -.->|"requests generation"| node_core
node_computeruse -.->|"optional agent use"| node_core
node_desktop -.->|"renders character"| node_live2d
node_desktop -.->|"renders character"| node_mmd
node_desktop -.->|"optional motion input"| node_mediapipe

click node_desktop "https://github.com/moeru-ai/airi/tree/main/apps/stage-tamagotchi"
click node_mobile "https://github.com/moeru-ai/airi/tree/main/apps/stage-pocket"
click node_web "https://github.com/moeru-ai/airi/tree/main/apps/stage-web/src"
click node_renderer "https://github.com/moeru-ai/airi/tree/main/apps/stage-tamagotchi-kirie/src-web/src/renderer"
click node_core "https://github.com/moeru-ai/airi/blob/main/packages/core-agent/src/runtime/llm-service.ts"
click node_chatstream "https://github.com/moeru-ai/airi/blob/main/packages/core-agent/src/runtime/chat-completions.ts"
click node_responses "https://github.com/moeru-ai/airi/blob/main/packages/core-agent/src/runtime/responses.ts"
click node_requestctx "https://github.com/moeru-ai/airi/blob/main/packages/core-agent/src/runtime/request-context.ts"
click node_audioengine "https://github.com/moeru-ai/airi/blob/main/packages/pipelines-audio/src/speech-pipeline.ts"
click node_uitts "https://github.com/moeru-ai/airi/blob/main/packages/stage-ui/src/libs/speech/streaming-pipeline.ts"
click node_voicevox "https://github.com/moeru-ai/airi/blob/main/packages/provider-inference/src/providers/local/voicevox/engine.ts"
click node_ttsadapter "https://github.com/moeru-ai/airi/blob/main/server/apps/api/src/services/adapters/tts/volcengine.ts"
click node_mediapipe "https://github.com/moeru-ai/airi/blob/main/packages/model-driver-mediapipe/src/engine.ts"
click node_live2d "https://github.com/moeru-ai/airi/blob/main/packages/stage-ui-live2d/src/composables/live2d/motion-manager.ts"
click node_mmd "https://github.com/moeru-ai/airi/blob/main/packages/stage-ui-mmd/src/composables/mmd/animation-manager.ts"
click node_minecraft "https://github.com/moeru-ai/airi/tree/main/integrations/minecraft/src"
click node_perception "https://github.com/moeru-ai/airi/blob/main/integrations/minecraft/src/cognitive/perception/pipeline.ts"
click node_rules "https://github.com/moeru-ai/airi/blob/main/integrations/minecraft/src/cognitive/perception/rules/engine.ts"
click node_satori "https://github.com/moeru-ai/airi/blob/main/integrations/satori-bot/src/core/planner/llm-client.ts"
click node_computeruse "https://github.com/moeru-ai/airi/blob/main/services/computer-use-mcp/src/workflows/engine.ts"
click node_telegram "https://github.com/moeru-ai/airi/tree/main/integrations/telegram-bot/src"
click node_twitter "https://github.com/moeru-ai/airi/tree/main/integrations/twitter-services/src"

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_mobile,node_web,node_renderer,node_user toneBlue
class node_core,node_chatstream,node_responses,node_requestctx toneAmber
class node_audioengine,node_uitts,node_voicevox,node_ttsadapter toneMint
class node_mediapipe,node_live2d,node_mmd toneRose
class node_minecraft,node_perception,node_rules,node_satori,node_computeruse,node_telegram,node_twitter toneIndigo
```

## Components

### User experiences

- [Desktop character](https://github.com/moeru-ai/airi/tree/main/apps/stage-tamagotchi): `apps/stage-tamagotchi`
- [Mobile companion](https://github.com/moeru-ai/airi/tree/main/apps/stage-pocket): `apps/stage-pocket`
- [Web stage](https://github.com/moeru-ai/airi/tree/main/apps/stage-web/src): `apps/stage-web/src`
- [Desktop renderer](https://github.com/moeru-ai/airi/tree/main/apps/stage-tamagotchi-kirie/src-web/src/renderer): `apps/stage-tamagotchi-kirie/src-web/src/renderer`

### Conversation runtime

- [LLM service](https://github.com/moeru-ai/airi/blob/main/packages/core-agent/src/runtime/llm-service.ts): `packages/core-agent/src/runtime/llm-service.ts`
- [Chat completion stream](https://github.com/moeru-ai/airi/blob/main/packages/core-agent/src/runtime/chat-completions.ts): `packages/core-agent/src/runtime/chat-completions.ts`
- [Responses stream](https://github.com/moeru-ai/airi/blob/main/packages/core-agent/src/runtime/responses.ts): `packages/core-agent/src/runtime/responses.ts`
- [Request context](https://github.com/moeru-ai/airi/blob/main/packages/core-agent/src/runtime/request-context.ts): `packages/core-agent/src/runtime/request-context.ts`

### Speech and inference

- [Speech pipeline](https://github.com/moeru-ai/airi/blob/main/packages/pipelines-audio/src/speech-pipeline.ts): `packages/pipelines-audio/src/speech-pipeline.ts`
- [Streaming TTS client](https://github.com/moeru-ai/airi/blob/main/packages/stage-ui/src/libs/speech/streaming-pipeline.ts): `packages/stage-ui/src/libs/speech/streaming-pipeline.ts`
- [VOICEVOX engine](https://github.com/moeru-ai/airi/blob/main/packages/provider-inference/src/providers/local/voicevox/engine.ts): `packages/provider-inference/src/providers/local/voicevox/engine.ts`
- [Volcengine TTS adapter](https://github.com/moeru-ai/airi/blob/main/server/apps/api/src/services/adapters/tts/volcengine.ts): `server/apps/api/src/services/adapters/tts/volcengine.ts`

### Character rendering

- [Motion capture engine](https://github.com/moeru-ai/airi/blob/main/packages/model-driver-mediapipe/src/engine.ts): `packages/model-driver-mediapipe/src/engine.ts`
- [Live2D motion manager](https://github.com/moeru-ai/airi/blob/main/packages/stage-ui-live2d/src/composables/live2d/motion-manager.ts): `packages/stage-ui-live2d/src/composables/live2d/motion-manager.ts`
- [MMD animation manager](https://github.com/moeru-ai/airi/blob/main/packages/stage-ui-mmd/src/composables/mmd/animation-manager.ts): `packages/stage-ui-mmd/src/composables/mmd/animation-manager.ts`

### Integrations

- [Minecraft integration](https://github.com/moeru-ai/airi/tree/main/integrations/minecraft/src): `integrations/minecraft/src`
- [Perception pipeline](https://github.com/moeru-ai/airi/blob/main/integrations/minecraft/src/cognitive/perception/pipeline.ts): `integrations/minecraft/src/cognitive/perception/pipeline.ts`
- [Perception rule engine](https://github.com/moeru-ai/airi/blob/main/integrations/minecraft/src/cognitive/perception/rules/engine.ts): `integrations/minecraft/src/cognitive/perception/rules/engine.ts`
- [Satori bot planner](https://github.com/moeru-ai/airi/blob/main/integrations/satori-bot/src/core/planner/llm-client.ts): `integrations/satori-bot/src/core/planner/llm-client.ts`
- [Computer-use workflows](https://github.com/moeru-ai/airi/blob/main/services/computer-use-mcp/src/workflows/engine.ts): `services/computer-use-mcp/src/workflows/engine.ts`
- [Telegram bot](https://github.com/moeru-ai/airi/tree/main/integrations/telegram-bot/src): `integrations/telegram-bot/src`
- [Twitter services](https://github.com/moeru-ai/airi/tree/main/integrations/twitter-services/src): `integrations/twitter-services/src`

### Other components

- **User**

## Connections

- User → Desktop character: uses (evidence: `README.md`)
- User → Mobile companion: uses (evidence: `README.md`)
- User → Web stage: uses (evidence: `README.md`)
- User → Desktop renderer: interacts
- LLM service → Chat completion stream: dispatches (evidence: `packages/core-agent/src/runtime/llm-service.ts`)
- LLM service → Responses stream: dispatches (evidence: `packages/core-agent/src/runtime/llm-service.ts`)
- LLM service → Request context: checks compatibility (evidence: `packages/core-agent/src/runtime/llm-service.ts`)
- Streaming TTS client → Speech pipeline: uses audio stream (evidence: `packages/stage-ui/src/libs/speech/streaming-pipeline.ts`)
- Volcengine TTS adapter → VOICEVOX engine: optional provider
- Perception pipeline → Perception rule engine: feeds events
- Minecraft integration → Perception pipeline: uses (evidence: `integrations/minecraft/src/cognitive/perception/pipeline.ts`)
- Satori bot planner → LLM service: requests generation
- Computer-use workflows → LLM service: optional agent use
- Desktop character → Live2D motion manager: renders character
- Desktop character → MMD animation manager: renders character
- Desktop character → Motion capture engine: optional motion input
