# yuyuanweb/ai-retouch-agent architecture

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

- Interactive diagram: https://gitdiagram.com/yuyuanweb/ai-retouch-agent
- Repository: https://github.com/yuyuanweb/ai-retouch-agent

## Overview

AI Retouch Agent is a full-stack image-generation and editing product. The main workflow runs from a user prompt in the React app through API routes to agent planning and tool execution; results update an editable session and are shown on the canvas. Other major capabilities include image generation, selection and local edits, layers, batch processing, marketing assets, export, and progress streaming. The README documents the broad architecture; source excerpts confirm several session, storage, and tool-registry links. Unsampled implementation details are represented at their existing directory paths.

Main entry points: [`backend/app/routers/sessions.py`](https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/routers/sessions.py) (Session routes), [`backend/app/worker.py`](https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/worker.py) (Task worker), [`backend/app/tools`](https://github.com/yuyuanweb/ai-retouch-agent/tree/main/backend/app/tools) (Editing tools), [`frontend/src/api/client.ts`](https://github.com/yuyuanweb/ai-retouch-agent/blob/main/frontend/src/api/client.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web app"]
  node_web["React app<br/>[App.tsx]"]
  node_create["Create and batches<br/>[CreatePage.tsx]"]
  node_editor["Canvas editor<br/>[CanvasStage.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_api["API and sessions"]
  node_api_routes["API routes<br/>[main.py]"]
  node_session_routes["Session routes<br/>[sessions.py]"]
  node_auth_routes["Authentication<br/>[auth.py]"]
  node_session_service["Session history<br/>[sessions.py]"]
end

subgraph group_editing["AI and editing"]
  node_agent_service["Agent service<br/>[agent.py]"]
  node_agent_graph["Agent planning<br/>[graph.py]"]
  node_plan_validation["Plan validation<br/>[plan.py]"]
  node_registry["Tool registry<br/>[__init__.py]"]
  node_tool_impl["Editing tools"]
  node_selection["Object selection<br/>[selections.py]"]
  node_layer_doc["Layer documents<br/>[layers.py]"]
  node_render["Image rendering<br/>[render.py]"]
  node_batch["Batch processing<br/>[batch.py]"]
end

subgraph group_runtime["Async and persistence"]
  node_events["Progress events<br/>[events.py]"]
  node_queue["Task queue<br/>[queue.py]"]
  node_worker["Task worker<br/>[worker.py]"]
  node_database[("PostgreSQL")]
  node_redis[("Redis")]
  node_object_store[("S3 storage<br/>[storage.py]")]
end

node_user(("User"))
node_provider{{"DashScope AI"}}

node_user -->|"uses"| node_web
node_web -->|"opens creation"| node_create
node_web -->|"opens editor"| node_editor
node_create -.->|"requests generation"| node_api_client
node_editor -.->|"requests edits"| node_api_client
node_api_client -->|"calls REST"| node_api_routes
node_api_routes -->|"routes requests"| node_session_routes
node_api_routes -->|"routes auth"| node_auth_routes
node_session_routes -->|"manages sessions"| node_session_service
node_session_routes -->|"handles messages"| node_agent_service
node_session_routes -->|"handles selection"| node_selection
node_agent_service -->|"orchestrates agent"| node_agent_graph
node_agent_graph -->|"validates plan"| node_plan_validation
node_agent_graph -->|"dispatches tools"| node_registry
node_registry -->|"registers tools"| node_tool_impl
node_tool_impl -->|"updates layers"| node_layer_doc
node_layer_doc -->|"provides composition"| node_render
node_selection -.->|"segments image"| node_provider
node_create -->|"submits batches"| node_batch
node_batch -->|"enqueues work"| node_queue
node_queue -->|"dispatches tasks"| node_worker
node_worker -->|"executes tools"| node_tool_impl
node_worker -->|"publishes progress"| node_events
node_events -->|"streams via pubsub"| node_redis
node_events -->|"streams SSE"| node_api_client
node_session_service -->|"persists history"| node_database
node_session_service -->|"stores document"| node_layer_doc
node_tool_impl -.->|"stores image assets"| node_object_store
node_worker -.->|"calls image models"| node_provider

click node_web "https://github.com/yuyuanweb/ai-retouch-agent/blob/main/frontend/src/App.tsx"
click node_create "https://github.com/yuyuanweb/ai-retouch-agent/blob/main/frontend/src/pages/CreatePage.tsx"
click node_editor "https://github.com/yuyuanweb/ai-retouch-agent/blob/main/frontend/src/components/editor/CanvasStage.tsx"
click node_api_client "https://github.com/yuyuanweb/ai-retouch-agent/blob/main/frontend/src/api/client.ts"
click node_api_routes "https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/main.py"
click node_session_routes "https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/routers/sessions.py"
click node_auth_routes "https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/routers/auth.py"
click node_session_service "https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/services/sessions.py"
click node_agent_service "https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/services/agent.py"
click node_agent_graph "https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/agent/graph.py"
click node_plan_validation "https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/agent/plan.py"
click node_registry "https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/tools/__init__.py"
click node_tool_impl "https://github.com/yuyuanweb/ai-retouch-agent/tree/main/backend/app/tools"
click node_selection "https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/services/selections.py"
click node_layer_doc "https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/layers.py"
click node_render "https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/edits/render.py"
click node_batch "https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/services/batch.py"
click node_events "https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/routers/events.py"
click node_queue "https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/queue.py"
click node_worker "https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/worker.py"
click node_object_store "https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/storage.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_web,node_create,node_editor,node_api_client,node_user toneBlue
class node_api_routes,node_session_routes,node_auth_routes,node_session_service toneAmber
class node_agent_service,node_agent_graph,node_plan_validation,node_registry,node_tool_impl,node_selection,node_layer_doc,node_render,node_batch toneMint
class node_events,node_queue,node_worker,node_database,node_redis,node_object_store toneRose
class node_provider toneIndigo
```

## Components

### Web app

- [React app](https://github.com/yuyuanweb/ai-retouch-agent/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Create and batches](https://github.com/yuyuanweb/ai-retouch-agent/blob/main/frontend/src/pages/CreatePage.tsx): `frontend/src/pages/CreatePage.tsx`
- [Canvas editor](https://github.com/yuyuanweb/ai-retouch-agent/blob/main/frontend/src/components/editor/CanvasStage.tsx): `frontend/src/components/editor/CanvasStage.tsx`
- [API client](https://github.com/yuyuanweb/ai-retouch-agent/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### API and sessions

- [API routes](https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/main.py): `backend/app/main.py`
- [Session routes](https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/routers/sessions.py): `backend/app/routers/sessions.py`
- [Authentication](https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Session history](https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/services/sessions.py): `backend/app/services/sessions.py`

### AI and editing

- [Agent service](https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/services/agent.py): `backend/app/services/agent.py`
- [Agent planning](https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/agent/graph.py): `backend/app/agent/graph.py`
- [Plan validation](https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/agent/plan.py): `backend/app/agent/plan.py`
- [Tool registry](https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/tools/__init__.py): `backend/app/tools/__init__.py`
- [Editing tools](https://github.com/yuyuanweb/ai-retouch-agent/tree/main/backend/app/tools): `backend/app/tools`
- [Object selection](https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/services/selections.py): `backend/app/services/selections.py`
- [Layer documents](https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/layers.py): `backend/app/layers.py`
- [Image rendering](https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/edits/render.py): `backend/app/edits/render.py`
- [Batch processing](https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/services/batch.py): `backend/app/services/batch.py`

### Async and persistence

- [Progress events](https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/routers/events.py): `backend/app/routers/events.py`
- [Task queue](https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/queue.py): `backend/app/queue.py`
- [Task worker](https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/worker.py): `backend/app/worker.py`
- **PostgreSQL**
- **Redis**
- [S3 storage](https://github.com/yuyuanweb/ai-retouch-agent/blob/main/backend/app/storage.py): `backend/app/storage.py`

### Other components

- **User**
- **DashScope AI**

## Connections

- User → React app: uses (evidence: `README.md`)
- React app → Create and batches: opens creation (evidence: `README.md`)
- React app → Canvas editor: opens editor (evidence: `README.md`)
- Create and batches → API client: requests generation
- Canvas editor → API client: requests edits
- API client → API routes: calls REST (evidence: `README.md`)
- API routes → Session routes: routes requests (evidence: `backend/app/main.py`)
- API routes → Authentication: routes auth (evidence: `backend/app/main.py`)
- Session routes → Session history: manages sessions (evidence: `backend/app/routers/sessions.py`)
- Session routes → Agent service: handles messages (evidence: `backend/app/routers/sessions.py`)
- Session routes → Object selection: handles selection (evidence: `backend/app/routers/sessions.py`)
- Agent service → Agent planning: orchestrates agent (evidence: `README.md`)
- Agent planning → Plan validation: validates plan (evidence: `README.md`)
- Agent planning → Tool registry: dispatches tools (evidence: `README.md`)
- Tool registry → Editing tools: registers tools (evidence: `backend/app/tools/__init__.py`)
- Editing tools → Layer documents: updates layers (evidence: `README.md`)
- Layer documents → Image rendering: provides composition (evidence: `backend/app/edits/render.py`)
- Object selection → DashScope AI: segments image
- Create and batches → Batch processing: submits batches (evidence: `README.md`)
- Batch processing → Task queue: enqueues work (evidence: `README.md`)
- Task queue → Task worker: dispatches tasks (evidence: `README.md`)
- Task worker → Editing tools: executes tools (evidence: `README.md`)
- Task worker → Progress events: publishes progress (evidence: `README.md`)
- Progress events → Redis: streams via pubsub (evidence: `README.md`)
- Progress events → API client: streams SSE (evidence: `README.md`)
- Session history → PostgreSQL: persists history (evidence: `README.md`)
- Session history → Layer documents: stores document (evidence: `backend/app/services/sessions.py`)
- Editing tools → S3 storage: stores image assets (evidence: `backend/app/tools/context.py`)
- Task worker → DashScope AI: calls image models
