# pollen-robotics/reachy_mini_conversation_app architecture

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

- Interactive diagram: https://gitdiagram.com/pollen-robotics/reachy_mini_conversation_app
- Repository: https://github.com/pollen-robotics/reachy_mini_conversation_app

## Overview

Reachy Mini Conversation App connects a user’s realtime voice conversation to an assistant backend and the robot’s audio, camera, and motion capabilities. The main runtime initializes the robot and streaming services; conversation handling coordinates assistant turns and tool calls, while motion and memory provide distinct robot-action and personalization stages. An optional web UI manages conversations, personalities, tools, and settings. The README documents these capabilities, but several runtime modules were not sampled, so their internal call wiring is shown only where documented or directly evidenced.

Main entry points: [`src/reachy_mini_conversation_app/conversation_handler.py`](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/conversation_handler.py) (Conversation handler), [`src/reachy_mini_conversation_app/streaming.py`](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/streaming.py) (Audio streaming), [`src/reachy_mini_conversation_app/daemon_api.py`](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/daemon_api.py) (App JSON-RPC), [`src/reachy_mini_conversation_app/tools`](https://github.com/pollen-robotics/reachy_mini_conversation_app/tree/main/src/reachy_mini_conversation_app/tools) (Robot action tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Conversation runtime"]
  node_main["App runtime<br/>[main.py]"]
  node_stream["Audio streaming<br/>[streaming.py]"]
  node_handler["Conversation handler"]
  node_memory["Conversation memory<br/>[memory.py]"]
  node_rpc["App JSON-RPC<br/>[daemon_api.py]"]
end

subgraph group_robot["Robot capabilities"]
  node_robottools["Robot action tools"]
  node_camera["Camera capture<br/>[camera.py]"]
  node_motion["Motion manager<br/>[moves.py]"]
end

subgraph group_profiles["Profiles and tools"]
  node_prompts["Prompt and personality<br/>[prompts.py]"]
  node_tools["Tool dispatch<br/>[core_tools.py]"]
  node_background["Background tool manager"]
  node_profile_routes["Personality routes"]
  node_profile_store[("Profile storage<br/>[profile_store.py]")]
  node_tool_routes["Tool settings routes"]
  node_toolspaces["Tool Space management"]
end

subgraph group_web["Web interface"]
  node_ui["Web UI shell<br/>[main.js]"]
  node_router["UI router<br/>[router.js]"]
  node_views["UI views"]
  node_api["UI API client<br/>[api.js]"]
end

subgraph group_integrations["External services"]
  node_realtime["Realtime backend"]
  node_daemon["Reachy Mini daemon"]
  node_mcp["Remote MCP client<br/>[mcp_client.py]"]
  node_vision_backend["Realtime vision"]
  node_tool_spaces_service["Hugging Face Tool Spaces"]
end

node_user(("User"))

node_user -->|"speaks to"| node_stream
node_main -->|"launches"| node_stream
node_stream -->|"streams audio"| node_realtime
node_realtime -->|"returns audio"| node_stream
node_stream -->|"delivers turns"| node_handler
node_handler -->|"requests responses"| node_realtime
node_handler -->|"loads guidance"| node_prompts
node_handler -->|"dispatches calls"| node_tools
node_tools -->|"starts long tasks"| node_background
node_tools -->|"invokes actions"| node_robottools
node_robottools -->|"queues movement"| node_motion
node_motion -->|"controls robot"| node_daemon
node_robottools -->|"captures frames"| node_camera
node_camera -->|"reads camera"| node_daemon
node_camera -->|"provides image"| node_vision_backend
node_robottools -->|"reads and writes facts"| node_memory
node_main -->|"initializes"| node_handler
node_main -->|"connects robot"| node_daemon
node_ui -->|"configures routes"| node_router
node_router -->|"mounts views"| node_views
node_views -->|"requests data"| node_api
node_api -->|"calls methods"| node_rpc
node_rpc -->|"dispatches personality calls"| node_profile_routes
node_profile_routes -->|"applies personality"| node_handler
node_profile_routes -->|"saves profiles"| node_profile_store
node_rpc -->|"dispatches tool settings"| node_tool_routes
node_tool_routes -->|"reads and writes overrides"| node_profile_store
node_rpc -->|"dispatches Space management"| node_toolspaces
node_toolspaces -.->|"installs and removes"| node_tool_spaces_service
node_tools -.->|"calls remote tools"| node_mcp

click node_main "https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/main.py"
click node_stream "https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/streaming.py"
click node_realtime "https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/huggingface_realtime.py"
click node_handler "https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/conversation_handler.py"
click node_prompts "https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/prompts.py"
click node_tools "https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/tools/core_tools.py"
click node_background "https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/tools/background_tool_manager.py"
click node_robottools "https://github.com/pollen-robotics/reachy_mini_conversation_app/tree/main/src/reachy_mini_conversation_app/tools"
click node_camera "https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/tools/camera.py"
click node_motion "https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/moves.py"
click node_memory "https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/memory.py"
click node_profile_routes "https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/personality_routes.py"
click node_profile_store "https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/profile_store.py"
click node_tool_routes "https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/profile_tool_routes.py"
click node_toolspaces "https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/tool_space_routes.py"
click node_mcp "https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/mcp_client.py"
click node_ui "https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/static/js/main.js"
click node_router "https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/static/js/router.js"
click node_views "https://github.com/pollen-robotics/reachy_mini_conversation_app/tree/main/src/reachy_mini_conversation_app/static/js/views"
click node_api "https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/static/js/api.js"
click node_rpc "https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/daemon_api.py"

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_main,node_stream,node_handler,node_memory,node_rpc,node_user toneBlue
class node_robottools,node_camera,node_motion toneAmber
class node_prompts,node_tools,node_background,node_profile_routes,node_profile_store,node_tool_routes,node_toolspaces toneMint
class node_ui,node_router,node_views,node_api toneRose
class node_realtime,node_daemon,node_mcp,node_vision_backend,node_tool_spaces_service toneIndigo
```

## Components

### Conversation runtime

- [App runtime](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/main.py): `src/reachy_mini_conversation_app/main.py`
- [Audio streaming](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/streaming.py): `src/reachy_mini_conversation_app/streaming.py`
- [Conversation handler](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/conversation_handler.py): `src/reachy_mini_conversation_app/conversation_handler.py`
- [Conversation memory](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/memory.py): `src/reachy_mini_conversation_app/memory.py`
- [App JSON-RPC](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/daemon_api.py): `src/reachy_mini_conversation_app/daemon_api.py`

### Robot capabilities

- [Robot action tools](https://github.com/pollen-robotics/reachy_mini_conversation_app/tree/main/src/reachy_mini_conversation_app/tools): `src/reachy_mini_conversation_app/tools`
- [Camera capture](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/tools/camera.py): `src/reachy_mini_conversation_app/tools/camera.py`
- [Motion manager](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/moves.py): `src/reachy_mini_conversation_app/moves.py`

### Profiles and tools

- [Prompt and personality](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/prompts.py): `src/reachy_mini_conversation_app/prompts.py`
- [Tool dispatch](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/tools/core_tools.py): `src/reachy_mini_conversation_app/tools/core_tools.py`
- [Background tool manager](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/tools/background_tool_manager.py): `src/reachy_mini_conversation_app/tools/background_tool_manager.py`
- [Personality routes](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/personality_routes.py): `src/reachy_mini_conversation_app/personality_routes.py`
- [Profile storage](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/profile_store.py): `src/reachy_mini_conversation_app/profile_store.py`
- [Tool settings routes](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/profile_tool_routes.py): `src/reachy_mini_conversation_app/profile_tool_routes.py`
- [Tool Space management](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/tool_space_routes.py): `src/reachy_mini_conversation_app/tool_space_routes.py`

### Web interface

- [Web UI shell](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/static/js/main.js): `src/reachy_mini_conversation_app/static/js/main.js`
- [UI router](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/static/js/router.js): `src/reachy_mini_conversation_app/static/js/router.js`
- [UI views](https://github.com/pollen-robotics/reachy_mini_conversation_app/tree/main/src/reachy_mini_conversation_app/static/js/views): `src/reachy_mini_conversation_app/static/js/views`
- [UI API client](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/static/js/api.js): `src/reachy_mini_conversation_app/static/js/api.js`

### External services

- [Realtime backend](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/huggingface_realtime.py): `src/reachy_mini_conversation_app/huggingface_realtime.py`
- **Reachy Mini daemon**
- [Remote MCP client](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/main/src/reachy_mini_conversation_app/mcp_client.py): `src/reachy_mini_conversation_app/mcp_client.py`
- **Realtime vision**
- **Hugging Face Tool Spaces**

### Other components

- **User**

## Connections

- User → Audio streaming: speaks to
- App runtime → Audio streaming: launches
- Audio streaming → Realtime backend: streams audio
- Realtime backend → Audio streaming: returns audio
- Audio streaming → Conversation handler: delivers turns
- Conversation handler → Realtime backend: requests responses
- Conversation handler → Prompt and personality: loads guidance
- Conversation handler → Tool dispatch: dispatches calls
- Tool dispatch → Background tool manager: starts long tasks
- Tool dispatch → Robot action tools: invokes actions
- Robot action tools → Motion manager: queues movement
- Motion manager → Reachy Mini daemon: controls robot
- Robot action tools → Camera capture: captures frames
- Camera capture → Reachy Mini daemon: reads camera
- Camera capture → Realtime vision: provides image
- Robot action tools → Conversation memory: reads and writes facts
- App runtime → Conversation handler: initializes
- App runtime → Reachy Mini daemon: connects robot
- Web UI shell → UI router: configures routes
- UI router → UI views: mounts views
- UI views → UI API client: requests data
- UI API client → App JSON-RPC: calls methods
- App JSON-RPC → Personality routes: dispatches personality calls
- Personality routes → Conversation handler: applies personality
- Personality routes → Profile storage: saves profiles
- App JSON-RPC → Tool settings routes: dispatches tool settings
- Tool settings routes → Profile storage: reads and writes overrides
- App JSON-RPC → Tool Space management: dispatches Space management
- Tool Space management → Hugging Face Tool Spaces: installs and removes
- Tool dispatch → Remote MCP client: calls remote tools