# lrj021029/audio-book architecture

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

- Interactive diagram: https://gitdiagram.com/lrj021029/audio-book
- Repository: https://github.com/lrj021029/audio-book

## Overview

This is a Chinese audiobook customer-service platform: an agent uses the workbench to manage a session and ask about a user’s orders, listening, membership, refunds, or support; the service plans and validates a dialogue turn, executes business actions through the AudioData API, and persists customer-service state separately. FAQ answers use SAG-Wiki or local retrieval, with optional LLM assistance. The graph also shows the documented AudioData API and its layered data generator. Unsampled router details are grouped by their existing directory; links between components are limited to documented or indexed relationships.

Main entry points: [`audio-data/generate/main.py`](https://github.com/lrj021029/audio-book/blob/main/audio-data/generate/main.py) (Generator entry points), [`app/engine/business.py`](https://github.com/lrj021029/audio-book/blob/main/app/engine/business.py) (Business actions), [`audio-data/generate`](https://github.com/lrj021029/audio-book/tree/main/audio-data/generate) (Generation framework), [`app/main.py`](https://github.com/lrj021029/audio-book/blob/main/app/main.py) (Session and chat API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workbench["Customer workbench"]
  node_ui["React workbench<br/>[main.jsx]"]
end

subgraph group_service["Customer service"]
  node_session_api["Session and chat API<br/>[main.py]"]
  node_turn_engine["Turn executor<br/>[executor.py]"]
  node_planner["Turn planner<br/>[planner.py]"]
  node_validator["Plan validator<br/>[validator.py]"]
  node_business_actions["Business actions<br/>[business.py]"]
  node_audio_client["AudioData client<br/>[audio_client.py]"]
  node_cs_store[("Session state store<br/>[db.py]")]
  node_faq["FAQ retrieval<br/>[retrieval.py]"]
  node_llm["LLM assistance<br/>[llm.py]"]
end

subgraph group_business["AudioData service"]
  node_audio_api["Business API<br/>[main.py]"]
  node_routers["Business route handlers"]
  node_api_db["Business database access<br/>[database.py]"]
  node_audio_store[("AudioData database")]
end

subgraph group_generation["Data generation"]
  node_generator_entry["Generator entry points<br/>[main.py]"]
  node_generation_framework["Generation framework"]
  node_foundation["Foundation data<br/>[layer1.py]"]
  node_content["Content supply<br/>[layer2.py]"]
  node_user_data["User membership<br/>[layer3.py]"]
  node_trade["Trade and wallet<br/>[layer4.py]"]
  node_listening["Listening and service<br/>[layer5.py]"]
  node_discovery["Recommendations and search<br/>[layer6.py]"]
end

node_agent(("Support agent"))
node_sag["SAG CLI"]
node_knowledge["Knowledge documents"]

node_agent -->|"uses"| node_ui
node_ui -->|"calls"| node_session_api
node_session_api -->|"executes turns"| node_turn_engine
node_turn_engine -->|"requests plans"| node_planner
node_planner -->|"validates plan"| node_validator
node_turn_engine -->|"runs actions"| node_business_actions
node_business_actions -->|"calls"| node_audio_client
node_audio_client -->|"HTTP requests"| node_audio_api
node_session_api -->|"persists sessions"| node_cs_store
node_business_actions -->|"retrieves answers"| node_faq
node_faq -->|"tries CLI"| node_sag
node_faq -->|"searches fallback"| node_knowledge
node_business_actions -.->|"may polish replies"| node_llm
node_audio_api -->|"routes requests"| node_routers
node_routers -->|"queries and writes"| node_api_db
node_api_db -->|"reads and writes"| node_audio_store
node_generator_entry -->|"runs layer"| node_foundation
node_generator_entry -->|"runs layer"| node_content
node_generator_entry -->|"runs layer"| node_user_data
node_generator_entry -->|"runs layer"| node_trade
node_generator_entry -->|"runs layer"| node_listening
node_generator_entry -->|"runs layer"| node_discovery
node_foundation -->|"uses helpers"| node_generation_framework
node_content -->|"uses helpers"| node_generation_framework
node_trade -->|"uses helpers"| node_generation_framework
node_listening -->|"uses helpers"| node_generation_framework

click node_ui "https://github.com/lrj021029/audio-book/blob/main/frontend/src/main.jsx"
click node_session_api "https://github.com/lrj021029/audio-book/blob/main/app/main.py"
click node_turn_engine "https://github.com/lrj021029/audio-book/blob/main/app/engine/executor.py"
click node_planner "https://github.com/lrj021029/audio-book/blob/main/app/engine/planner.py"
click node_validator "https://github.com/lrj021029/audio-book/blob/main/app/engine/validator.py"
click node_business_actions "https://github.com/lrj021029/audio-book/blob/main/app/engine/business.py"
click node_audio_client "https://github.com/lrj021029/audio-book/blob/main/app/audio_client.py"
click node_cs_store "https://github.com/lrj021029/audio-book/blob/main/app/db.py"
click node_faq "https://github.com/lrj021029/audio-book/blob/main/app/retrieval.py"
click node_llm "https://github.com/lrj021029/audio-book/blob/main/app/llm.py"
click node_knowledge "https://github.com/lrj021029/audio-book/tree/main/knowledge"
click node_audio_api "https://github.com/lrj021029/audio-book/blob/main/audio-data/app/main.py"
click node_routers "https://github.com/lrj021029/audio-book/tree/main/audio-data/app/routers"
click node_api_db "https://github.com/lrj021029/audio-book/blob/main/audio-data/app/database.py"
click node_generator_entry "https://github.com/lrj021029/audio-book/blob/main/audio-data/generate/main.py"
click node_generation_framework "https://github.com/lrj021029/audio-book/tree/main/audio-data/generate"
click node_foundation "https://github.com/lrj021029/audio-book/blob/main/audio-data/generate/layers/layer1.py"
click node_content "https://github.com/lrj021029/audio-book/blob/main/audio-data/generate/layers/layer2.py"
click node_user_data "https://github.com/lrj021029/audio-book/blob/main/audio-data/generate/layers/layer3.py"
click node_trade "https://github.com/lrj021029/audio-book/blob/main/audio-data/generate/layers/layer4.py"
click node_listening "https://github.com/lrj021029/audio-book/blob/main/audio-data/generate/layers/layer5.py"
click node_discovery "https://github.com/lrj021029/audio-book/blob/main/audio-data/generate/layers/layer6.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_ui toneBlue
class node_session_api,node_turn_engine,node_planner,node_validator,node_business_actions,node_audio_client,node_cs_store,node_faq,node_llm toneAmber
class node_audio_api,node_routers,node_api_db,node_audio_store toneMint
class node_generator_entry,node_generation_framework,node_foundation,node_content,node_user_data,node_trade,node_listening,node_discovery toneRose
class node_agent,node_sag toneIndigo
class node_knowledge toneTeal
```

## Components

### Customer workbench

- [React workbench](https://github.com/lrj021029/audio-book/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`

### Customer service

- [Session and chat API](https://github.com/lrj021029/audio-book/blob/main/app/main.py): `app/main.py`
- [Turn executor](https://github.com/lrj021029/audio-book/blob/main/app/engine/executor.py): `app/engine/executor.py`
- [Turn planner](https://github.com/lrj021029/audio-book/blob/main/app/engine/planner.py): `app/engine/planner.py`
- [Plan validator](https://github.com/lrj021029/audio-book/blob/main/app/engine/validator.py): `app/engine/validator.py`
- [Business actions](https://github.com/lrj021029/audio-book/blob/main/app/engine/business.py): `app/engine/business.py`
- [AudioData client](https://github.com/lrj021029/audio-book/blob/main/app/audio_client.py): `app/audio_client.py`
- [Session state store](https://github.com/lrj021029/audio-book/blob/main/app/db.py): `app/db.py`
- [FAQ retrieval](https://github.com/lrj021029/audio-book/blob/main/app/retrieval.py): `app/retrieval.py`
- [LLM assistance](https://github.com/lrj021029/audio-book/blob/main/app/llm.py): `app/llm.py`

### AudioData service

- [Business API](https://github.com/lrj021029/audio-book/blob/main/audio-data/app/main.py): `audio-data/app/main.py`
- [Business route handlers](https://github.com/lrj021029/audio-book/tree/main/audio-data/app/routers): `audio-data/app/routers`
- [Business database access](https://github.com/lrj021029/audio-book/blob/main/audio-data/app/database.py): `audio-data/app/database.py`
- **AudioData database**

### Data generation

- [Generator entry points](https://github.com/lrj021029/audio-book/blob/main/audio-data/generate/main.py): `audio-data/generate/main.py`
- [Generation framework](https://github.com/lrj021029/audio-book/tree/main/audio-data/generate): `audio-data/generate`
- [Foundation data](https://github.com/lrj021029/audio-book/blob/main/audio-data/generate/layers/layer1.py): `audio-data/generate/layers/layer1.py`
- [Content supply](https://github.com/lrj021029/audio-book/blob/main/audio-data/generate/layers/layer2.py): `audio-data/generate/layers/layer2.py`
- [User membership](https://github.com/lrj021029/audio-book/blob/main/audio-data/generate/layers/layer3.py): `audio-data/generate/layers/layer3.py`
- [Trade and wallet](https://github.com/lrj021029/audio-book/blob/main/audio-data/generate/layers/layer4.py): `audio-data/generate/layers/layer4.py`
- [Listening and service](https://github.com/lrj021029/audio-book/blob/main/audio-data/generate/layers/layer5.py): `audio-data/generate/layers/layer5.py`
- [Recommendations and search](https://github.com/lrj021029/audio-book/blob/main/audio-data/generate/layers/layer6.py): `audio-data/generate/layers/layer6.py`

### Other components

- **Support agent**
- **SAG CLI**
- [Knowledge documents](https://github.com/lrj021029/audio-book/tree/main/knowledge): `knowledge`

## Connections

- Support agent → React workbench: uses
- React workbench → Session and chat API: calls
- Session and chat API → Turn executor: executes turns (evidence: `app/main.py`)
- Turn executor → Turn planner: requests plans (evidence: `app/engine/executor.py`)
- Turn planner → Plan validator: validates plan
- Turn executor → Business actions: runs actions (evidence: `app/engine/executor.py`)
- Business actions → AudioData client: calls (evidence: `app/engine/business.py`)
- AudioData client → Business API: HTTP requests
- Session and chat API → Session state store: persists sessions (evidence: `app/main.py`)
- Business actions → FAQ retrieval: retrieves answers (evidence: `app/engine/business.py`)
- FAQ retrieval → SAG CLI: tries CLI
- FAQ retrieval → Knowledge documents: searches fallback
- Business actions → LLM assistance: may polish replies (evidence: `app/engine/business.py`)
- Business API → Business route handlers: routes requests (evidence: `audio-data/app/main.py`)
- Business route handlers → Business database access: queries and writes (evidence: `audio-data/app/routers/search.py`)
- Business database access → AudioData database: reads and writes (evidence: `audio-data/app/database.py`)
- Generator entry points → Foundation data: runs layer (evidence: `audio-data/generate/main.py`)
- Generator entry points → Content supply: runs layer (evidence: `audio-data/generate/main.py`)
- Generator entry points → User membership: runs layer (evidence: `audio-data/generate/main.py`)
- Generator entry points → Trade and wallet: runs layer (evidence: `audio-data/generate/main.py`)
- Generator entry points → Listening and service: runs layer (evidence: `audio-data/generate/main.py`)
- Generator entry points → Recommendations and search: runs layer (evidence: `audio-data/generate/main.py`)
- Foundation data → Generation framework: uses helpers (evidence: `audio-data/generate/layers/layer1.py`)
- Content supply → Generation framework: uses helpers (evidence: `audio-data/generate/layers/layer2.py`)
- Trade and wallet → Generation framework: uses helpers (evidence: `audio-data/generate/layers/layer4.py`)
- Listening and service → Generation framework: uses helpers (evidence: `audio-data/generate/layers/layer5.py`)