# plantingflowersrabbit/shuyi-agent architecture

> Architecture diagram of the GitHub repository plantingflowersrabbit/shuyi-agent, 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/plantingflowersrabbit/shuyi-agent
- Repository: https://github.com/plantingflowersrabbit/shuyi-agent

## Overview

ShuYi Agent is a Chinese-novel audiobook dubbing workbench. The principal workflow runs from project and text intake through chapter selection, role and utterance preparation, voice assignment, audio generation, review, and delivery export. The frontend drives the API; the API coordinates domain services and persisted state. README-documented planner, memory, tool-calling, and trace capabilities are included, though their detailed wiring is not established by the sampled excerpts.

Main entry points: [`backend/app/api/app.py`](https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/api/app.py) (HTTP API), [`backend/app/domain/dubbing_workflow.py`](https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/domain/dubbing_workflow.py) (Dubbing workflow), [`frontend/src/App.tsx`](https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/frontend/src/App.tsx) (Web workbench), [`backend/app/domain/audio.py`](https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/domain/audio.py) (Audio jobs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workbench["Workbench"]
  node_frontend["Web workbench<br/>[App.tsx]"]
  node_workflow["Workflow state<br/>[workflowMachine.ts]"]
end

subgraph group_production["Dubbing production"]
  node_chapter["Novel and chapters<br/>[novel.py]"]
  node_dubbing["Dubbing workflow"]
  node_segmentation["Utterance segmentation<br/>[segmentation.py]"]
  node_roles["Roles and voices<br/>[roles.py]"]
  node_voice_resources["Voice resources<br/>[voices.py]"]
  node_audio["Audio jobs<br/>[audio.py]"]
  node_delivery["Audio and export<br/>[novel_files.py]"]
end

subgraph group_intelligence["Agent services"]
  node_chapter_agent["Chapter parsing"]
  node_role_analysis["Role analysis"]
  node_tools["Tool registry<br/>[tool_registry.py]"]
  node_trace["Agent traces<br/>[agent_trace.py]"]
end

subgraph group_project["Project services"]
  node_workspace["Project workspace"]
  node_quality["Production planning"]
  node_memory["Story memory<br/>[story_memory.py]"]
end

subgraph group_runtime["Runtime and storage"]
  node_api["HTTP API<br/>[app.py]"]
  node_repository[("SQLite repository<br/>[sqlite.py]")]
  node_runtime_state["Runtime state<br/>[runtime_state.py]"]
end

node_user(("Producer"))
node_tts["Qwen3 TTS service"]
node_text_model["Text model provider"]

node_user -->|"operates"| node_frontend
node_frontend -->|"updates state"| node_workflow
node_frontend -->|"sends requests"| node_api
node_api -->|"manages projects"| node_workspace
node_api -->|"loads text"| node_chapter
node_api -->|"requests parsing"| node_chapter_agent
node_chapter_agent -.->|"requests completion"| node_text_model
node_api -->|"runs workflow"| node_dubbing
node_dubbing -->|"analyzes roles"| node_role_analysis
node_dubbing -->|"segments utterances"| node_segmentation
node_dubbing -->|"matches roles"| node_roles
node_api -->|"manages voices"| node_voice_resources
node_api -->|"generates audio"| node_audio
node_audio -->|"requests speech"| node_tts
node_api -->|"exports package"| node_delivery
node_api -->|"plans and reviews"| node_quality
node_api -->|"indexes and searches"| node_memory
node_api -->|"executes tools"| node_tools
node_api -->|"records runs"| node_trace
node_api -->|"restores and saves"| node_runtime_state
node_runtime_state -->|"persists snapshot"| node_repository
node_api -->|"reads and writes"| node_repository

click node_frontend "https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/frontend/src/App.tsx"
click node_workflow "https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/frontend/src/features/agent-workflow/workflowMachine.ts"
click node_api "https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/api/app.py"
click node_chapter "https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/domain/novel.py"
click node_chapter_agent "https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/domain/ai_chapter_agent.py"
click node_role_analysis "https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/domain/ai_segmentation_agent.py"
click node_dubbing "https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/domain/dubbing_workflow.py"
click node_segmentation "https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/domain/segmentation.py"
click node_roles "https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/domain/roles.py"
click node_voice_resources "https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/domain/voices.py"
click node_audio "https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/domain/audio.py"
click node_tts "https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/tts/qwen3_tts_server.py"
click node_delivery "https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/domain/novel_files.py"
click node_workspace "https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/domain/project_workspace.py"
click node_quality "https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/domain/production_planner.py"
click node_memory "https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/domain/story_memory.py"
click node_tools "https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/domain/tool_registry.py"
click node_trace "https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/domain/agent_trace.py"
click node_repository "https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/repositories/sqlite.py"
click node_runtime_state "https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/application/runtime_state.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_frontend,node_workflow toneBlue
class node_chapter,node_dubbing,node_segmentation,node_roles,node_voice_resources,node_audio,node_delivery toneAmber
class node_chapter_agent,node_role_analysis,node_tools,node_trace toneMint
class node_workspace,node_quality,node_memory toneRose
class node_api,node_repository,node_runtime_state,node_user,node_text_model toneIndigo
class node_tts toneTeal
```

## Components

### Workbench

- [Web workbench](https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Workflow state](https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/frontend/src/features/agent-workflow/workflowMachine.ts): `frontend/src/features/agent-workflow/workflowMachine.ts`

### Dubbing production

- [Novel and chapters](https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/domain/novel.py): `backend/app/domain/novel.py`
- [Dubbing workflow](https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/domain/dubbing_workflow.py): `backend/app/domain/dubbing_workflow.py`
- [Utterance segmentation](https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/domain/segmentation.py): `backend/app/domain/segmentation.py`
- [Roles and voices](https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/domain/roles.py): `backend/app/domain/roles.py`
- [Voice resources](https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/domain/voices.py): `backend/app/domain/voices.py`
- [Audio jobs](https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/domain/audio.py): `backend/app/domain/audio.py`
- [Audio and export](https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/domain/novel_files.py): `backend/app/domain/novel_files.py`

### Agent services

- [Chapter parsing](https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/domain/ai_chapter_agent.py): `backend/app/domain/ai_chapter_agent.py`
- [Role analysis](https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/domain/ai_segmentation_agent.py): `backend/app/domain/ai_segmentation_agent.py`
- [Tool registry](https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/domain/tool_registry.py): `backend/app/domain/tool_registry.py`
- [Agent traces](https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/domain/agent_trace.py): `backend/app/domain/agent_trace.py`

### Project services

- [Project workspace](https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/domain/project_workspace.py): `backend/app/domain/project_workspace.py`
- [Production planning](https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/domain/production_planner.py): `backend/app/domain/production_planner.py`
- [Story memory](https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/domain/story_memory.py): `backend/app/domain/story_memory.py`

### Runtime and storage

- [HTTP API](https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/api/app.py): `backend/app/api/app.py`
- [SQLite repository](https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/repositories/sqlite.py): `backend/app/repositories/sqlite.py`
- [Runtime state](https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/app/application/runtime_state.py): `backend/app/application/runtime_state.py`

### Other components

- **Producer**
- [Qwen3 TTS service](https://github.com/plantingflowersrabbit/shuyi-agent/blob/main/backend/tts/qwen3_tts_server.py): `backend/tts/qwen3_tts_server.py`
- **Text model provider**

## Connections

- Producer → Web workbench: operates
- Web workbench → Workflow state: updates state
- Web workbench → HTTP API: sends requests
- HTTP API → Project workspace: manages projects
- HTTP API → Novel and chapters: loads text
- HTTP API → Chapter parsing: requests parsing
- Chapter parsing → Text model provider: requests completion
- HTTP API → Dubbing workflow: runs workflow
- Dubbing workflow → Role analysis: analyzes roles
- Dubbing workflow → Utterance segmentation: segments utterances
- Dubbing workflow → Roles and voices: matches roles
- HTTP API → Voice resources: manages voices
- HTTP API → Audio jobs: generates audio
- Audio jobs → Qwen3 TTS service: requests speech
- HTTP API → Audio and export: exports package
- HTTP API → Production planning: plans and reviews
- HTTP API → Story memory: indexes and searches
- HTTP API → Tool registry: executes tools
- HTTP API → Agent traces: records runs
- HTTP API → Runtime state: restores and saves
- Runtime state → SQLite repository: persists snapshot
- HTTP API → SQLite repository: reads and writes