# yanzai-4/yuzu architecture

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

- Interactive diagram: https://gitdiagram.com/yanzai-4/yuzu
- Repository: https://github.com/yanzai-4/yuzu

## Overview

Yuzu is a multi-agent workplace where people chat with role- and permission-scoped agents, coordinate work through tickets and task lists, and observe live activity. The principal workflow begins with a room message, passes through agent intake and decision-making, and may produce a reply or tool action; agent memory and supervision support that work. The README documents the major cognition, safety, behavior-review, and tool-calling capabilities, but most of their wiring was not sampled, so the graph shows those as distinct stages without asserting undocumented call links.

Main entry points: [`backend/src/main/java/ai/yuzu/chat/ChatService.java`](https://github.com/yanzai-4/yuzu/blob/main/backend/src/main/java/ai/yuzu/chat/ChatService.java) (Room chat), [`backend/src/main/java/ai/yuzu/tool/impl`](https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/tool/impl) (Agent tools), [`backend/src/main/java/ai/yuzu/llm`](https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/llm) (Model gateway), [`backend/src/main/java/ai/yuzu/realtime`](https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/realtime) (Realtime event stream)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workplace["Workplace"]
  node_chat["Room chat<br/>[ChatService.java]"]
  node_cards["Questions and approvals<br/>[CardService.java]"]
  node_room[("Rooms and membership")]
end

subgraph group_agent["Agent runtime"]
  node_agents[("Agent profiles<br/>[AgentService.java]")]
  node_runtime["Agent runtime"]
end

subgraph group_intelligence["Agent intelligence"]
  node_intake["Message intake"]
  node_triage["Chat triage"]
  node_safety["Safety review"]
  node_cognition["Planning and cognition"]
  node_consciousness["Main consciousness"]
  node_subconscious["Subconscious supervision"]
  node_memory[("Agent memory")]
  node_behavior["Behavior review"]
end

subgraph group_work["Work coordination"]
  node_tasks[("Tickets and task lists")]
  node_sim[("Simulated business")]
end

subgraph group_operations["Operations and integrations"]
  node_toolcalling["Tool calling"]
  node_tools["Agent tools"]
  node_llm["Model gateway"]
  node_settings[("Model settings")]
  node_monitor[("Live status and traces")]
  node_realtime["Realtime event stream"]
end

node_person(("Room participant"))
node_provider["OpenAI-compatible provider"]

node_person -->|"posts messages"| node_chat
node_chat -->|"checks membership"| node_room
node_chat -->|"dispatches messages"| node_intake
node_intake -->|"routes stimuli"| node_triage
node_person -->|"answers cards"| node_cards
node_runtime -->|"loads profiles"| node_agents
node_consciousness -->|"requests model output"| node_llm
node_llm -->|"sends completions"| node_provider
node_consciousness -->|"submits actions"| node_toolcalling
node_toolcalling -->|"dispatches calls"| node_tools
node_tools -->|"manages work"| node_tasks
node_tools -->|"uses simulations"| node_sim
node_chat -->|"publishes chat events"| node_realtime
node_monitor -->|"publishes status events"| node_realtime
node_realtime -->|"streams updates"| node_person
node_settings -->|"configures model access"| node_llm

click node_chat "https://github.com/yanzai-4/yuzu/blob/main/backend/src/main/java/ai/yuzu/chat/ChatService.java"
click node_cards "https://github.com/yanzai-4/yuzu/blob/main/backend/src/main/java/ai/yuzu/card/CardService.java"
click node_room "https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/room"
click node_agents "https://github.com/yanzai-4/yuzu/blob/main/backend/src/main/java/ai/yuzu/agent/AgentService.java"
click node_runtime "https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/agent/runtime"
click node_intake "https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/internal/intake"
click node_triage "https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/external/chat"
click node_safety "https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/external/safety"
click node_cognition "https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/internal"
click node_consciousness "https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/internal/consciousness"
click node_subconscious "https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/internal/subconscious"
click node_memory "https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/internal/memory"
click node_behavior "https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/external/behavior"
click node_toolcalling "https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/external/toolcall"
click node_tools "https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/tool/impl"
click node_tasks "https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/task"
click node_sim "https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/sim"
click node_llm "https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/llm"
click node_settings "https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/settings"
click node_monitor "https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/monitor"
click node_realtime "https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/realtime"

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_chat,node_cards,node_room toneBlue
class node_agents,node_runtime toneAmber
class node_intake,node_triage,node_safety,node_cognition,node_consciousness,node_subconscious,node_memory,node_behavior toneMint
class node_tasks,node_sim toneRose
class node_toolcalling,node_tools,node_llm,node_settings,node_monitor,node_realtime,node_person,node_provider toneIndigo
```

## Components

### Workplace

- [Room chat](https://github.com/yanzai-4/yuzu/blob/main/backend/src/main/java/ai/yuzu/chat/ChatService.java): `backend/src/main/java/ai/yuzu/chat/ChatService.java`
- [Questions and approvals](https://github.com/yanzai-4/yuzu/blob/main/backend/src/main/java/ai/yuzu/card/CardService.java): `backend/src/main/java/ai/yuzu/card/CardService.java`
- [Rooms and membership](https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/room): `backend/src/main/java/ai/yuzu/room`

### Agent runtime

- [Agent profiles](https://github.com/yanzai-4/yuzu/blob/main/backend/src/main/java/ai/yuzu/agent/AgentService.java): `backend/src/main/java/ai/yuzu/agent/AgentService.java`
- [Agent runtime](https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/agent/runtime): `backend/src/main/java/ai/yuzu/agent/runtime`

### Agent intelligence

- [Message intake](https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/internal/intake): `backend/src/main/java/ai/yuzu/internal/intake`
- [Chat triage](https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/external/chat): `backend/src/main/java/ai/yuzu/external/chat`
- [Safety review](https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/external/safety): `backend/src/main/java/ai/yuzu/external/safety`
- [Planning and cognition](https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/internal): `backend/src/main/java/ai/yuzu/internal`
- [Main consciousness](https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/internal/consciousness): `backend/src/main/java/ai/yuzu/internal/consciousness`
- [Subconscious supervision](https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/internal/subconscious): `backend/src/main/java/ai/yuzu/internal/subconscious`
- [Agent memory](https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/internal/memory): `backend/src/main/java/ai/yuzu/internal/memory`
- [Behavior review](https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/external/behavior): `backend/src/main/java/ai/yuzu/external/behavior`

### Work coordination

- [Tickets and task lists](https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/task): `backend/src/main/java/ai/yuzu/task`
- [Simulated business](https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/sim): `backend/src/main/java/ai/yuzu/sim`

### Operations and integrations

- [Tool calling](https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/external/toolcall): `backend/src/main/java/ai/yuzu/external/toolcall`
- [Agent tools](https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/tool/impl): `backend/src/main/java/ai/yuzu/tool/impl`
- [Model gateway](https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/llm): `backend/src/main/java/ai/yuzu/llm`
- [Model settings](https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/settings): `backend/src/main/java/ai/yuzu/settings`
- [Live status and traces](https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/monitor): `backend/src/main/java/ai/yuzu/monitor`
- [Realtime event stream](https://github.com/yanzai-4/yuzu/tree/main/backend/src/main/java/ai/yuzu/realtime): `backend/src/main/java/ai/yuzu/realtime`

### Other components

- **Room participant**
- **OpenAI-compatible provider**

## Connections

- Room participant → Room chat: posts messages
- Room chat → Rooms and membership: checks membership
- Room chat → Message intake: dispatches messages
- Message intake → Chat triage: routes stimuli
- Room participant → Questions and approvals: answers cards
- Agent runtime → Agent profiles: loads profiles
- Main consciousness → Model gateway: requests model output
- Model gateway → OpenAI-compatible provider: sends completions
- Main consciousness → Tool calling: submits actions
- Tool calling → Agent tools: dispatches calls
- Agent tools → Tickets and task lists: manages work
- Agent tools → Simulated business: uses simulations
- Room chat → Realtime event stream: publishes chat events
- Live status and traces → Realtime event stream: publishes status events
- Realtime event stream → Room participant: streams updates
- Model settings → Model gateway: configures model access