# renhao-wan/craftflow architecture

> Architecture diagram of the GitHub repository renhao-wan/craftflow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/renhao-wan/craftflow
- Repository: https://github.com/renhao-wan/craftflow

## Overview

1. **Repository shape**
   - This is a monorepo with three user-facing surfaces and two backend runtimes:
     - `craftflow-web`: Vue 3 SPA.
     - `craftflow-desktop`: Electron shell that packages a frontend plus local backend config.
     - `craftflow-backend`: Python AI/workflow backend.
     - `java-backend`: Spring Boot server-mode backend for centralized deployment.
   - The architecture is not “one app”; it is a split between **AI workflow execution** and **product/API delivery**.

2. **Primary system boundary: AI engine vs. product backends**
   - The Python backend is the core intelligence layer. It owns LangGraph-based generation, polishing, tool use, and streaming.
   - The Java backend is a separate service boundary for server mode: auth, quotas, task/session management, WebSocket handling, and a gateway to the Python process.
   - The desktop app can run in a more self-contained mode, while the web app generally targets the server mode.

3. **Python backend as the workflow engine**
   - `craftflow-backend/app/main.py` and `app/api/v1/*` expose the public API.
   - `app/graph/*` contains the LangGraph workflows:
     - `creation`: outline planning, HITL confirmation, parallel writing, reduction.
     - `polishing`: fast rule-based correction and deeper debate/reflexion polishing.
     - `common`: shared LLM factory, prompt helpers, utilities.
   - This backend is the place where long-running content-generation logic lives.

4. **Two main generation pipelines**
   - **Creation pipeline**: user topic/requirements enter, an outline is generated, the flow can pause for human confirmation, then multiple section writers run and a reducer merges outputs.
   - **Polishing pipeline**: content enters, then either a lightweight correction path or a deeper author/editor debate path is chosen.
   - These pipelines are stateful rather than stateless request/response handlers, which is why task storage and checkpointing are first-class parts of the design.

5. **Task lifecycle and state management**
   - The backend has dedicated services for task orchestration: `creation_svc`, `polishing_svc`, `task_store`, `task_broadcaster`, and `checkpointer`.
   - Tasks are persisted in either SQLite or PostgreSQL depending on deployment mode, with separate implementations for each.
   - Checkpointing is used to pause, resume, and recover graph execution, which is essential for “interruptible” creation flows.

6. **API surface and communication patterns**
   - The Python backend exposes multiple protocols:
     - **REST** for CRUD-style actions like settings, task history, and lifecycle commands.
     - **WebSocket** for task status, resumable workflows, and token/event streaming.
     - **SSE** for chat token streaming.
   - The API is split by use case: `creation`, `polishing`, `chat`, `tasks`, `settings`, `ws`, and `internal`.

7. **External integrations and tool chain**
   - The graph layer can call external tools through `app/graph/tools/*`.
   - Important tool categories include search, sandboxed code execution, retriever utilities, and validators.
   - The README indicates integration points for LLM APIs, Tavily search, and E2B sandboxing; these are architectural dependencies because they extend the model’s capabilities beyond pure text generation.

8. **Persistence and infrastructure in the Python layer**
   - The Python backend includes a PostgreSQL pool service and distinct task-store implementations, indicating it supports both local and server storage backends.
   - Logs, environment files, Dockerfile, and deployment docs show it is meant to run as a containerized service as well as a local dev process.
   - The presence of `standalone` and `server` adapters suggests a runtime switch in how the Python engine is wired into the rest of the system.

9. **Java backend as server-mode orchestration**
   - `java-backend` is a separate Spring Boot application with modules for auth, chat, task management, quota control, WebSocket delivery, and Python gateway integration.
   - Notable boundaries:
     - `auth`: JWT and certificate-based login.
     - `task`: task persistence and timeout handling.
     - `chat`: conversation storage and messaging.
     - `infrastructure.gateway.PythonGateway`: bridge to the Python AI backend.
     - `infrastructure.websocket` and `listener`: push state updates to clients and react to database/task events.
   - This layer is the likely public-facing server in centralized deployments.

10. **Web client architecture**
   - `craftflow-web` is a Vue 3 + TypeScript SPA using Pinia, Vue Router, and Axios.
   - It is organized by feature slices: chat, creation, polishing, settings, task history, and common UI components.
   - Data flow is mostly client-to-backend API calls plus WebSocket/SSE streams; the frontend does not contain business logic for generation itself.

11. **Desktop client architecture**
   - `craftflow-desktop` wraps the app in Electron and includes backend-side desktop config plus build/release tooling.
   - This implies a packaged local experience where the desktop shell controls startup, windowing, and mode-specific configuration.
   - The desktop build is an integration artifact around the same logical product, not a separate domain implementation.

12. **Operational boundaries and deployment model**
   - The repo supports multiple deployment modes: local standalone, server-hosted, and packaged desktop.
   - Docker, nginx, PostgreSQL init scripts, and CI workflows indicate production deployment is container-oriented.
   - For an architecture diagram, the key edges are:
     - user UI surfaces to API backend,
     - API backend to persistent task/state stores,
     - workflow engine to LLM/tools,
     - server-mode Java backend to Python gateway and clients,
     - WebSocket/SSE channels for long-running execution feedback.

Main entry points: [`java-backend/src/main/java/com/craftflow/CraftFlowApplication.java`](https://github.com/renhao-wan/craftflow/blob/master/java-backend/src/main/java/com/craftflow/CraftFlowApplication.java) (Server app), [`craftflow-backend/app/services`](https://github.com/renhao-wan/craftflow/tree/master/craftflow-backend/app/services) (Task services), [`craftflow-web`](https://github.com/renhao-wan/craftflow/tree/master/craftflow-web) (Web app), [`craftflow-backend/app/main.py`](https://github.com/renhao-wan/craftflow/blob/master/craftflow-backend/app/main.py) (API entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client_surfaces["Client surfaces"]
  node_craftflow_web["Web app<br/>Vue 3 SPA"]
  node_craftflow_desktop["Desktop app<br/>Electron shell"]
  node_craftflow_landing["Landing site<br/>Vite marketing"]
end

subgraph group_python_engine["Python engine"]
  node_python_main["API entry<br/>FastAPI app<br/>[main.py]"]
  node_python_api["REST API<br/>v1 routers<br/>[router.py]"]
  node_python_ws["Realtime API<br/>WS/SSE handlers<br/>[ws_handler.py]"]
  node_python_creation_graph["Creation flow<br/>LangGraph pipeline<br/>[builder.py]"]
  node_python_polishing_graph["Polishing flow<br/>LangGraph pipeline<br/>[builder.py]"]
  node_python_graph_common["Graph common<br/>LLM helpers<br/>[llm_factory.py]"]
  node_python_tools["Toolchain<br/>Search/code tools"]
  node_python_services["Task services<br/>Orchestration svc"]
  node_python_task_store[("Task store<br/>SQLite/Postgres<br/>[task_store.py]")]
  node_python_checkpointer["Checkpointer<br/>Resume state<br/>[checkpointer.py]"]
end

subgraph group_java_server["Java server"]
  node_java_app["Server app<br/>Spring Boot"]
  node_java_auth["Auth<br/>JWT/cert login"]
  node_java_chat["Chat<br/>Conversation svc"]
  node_java_tasks["Task svc<br/>Task lifecycle"]
  node_java_quota["Quota svc<br/>Usage limits"]
  node_java_gateway["Python gateway<br/>Bridge client<br/>[PythonGateway.java]"]
  node_java_ws["WebSocket hub<br/>Push channel"]
  node_java_listeners["DB listeners<br/>Event listener"]
end

subgraph group_ops_delivery["Ops & delivery"]
  node_deploy_assets["Deployment<br/>Docker/nginx/CI<br/>[docker-compose.yml]"]
end

node_craftflow_web -->|"server mode"| node_java_app
node_craftflow_web -->|"standalone mode"| node_python_main
node_craftflow_web -->|"streaming"| node_python_ws
node_craftflow_desktop -->|"bundled runtime"| node_python_main
node_craftflow_desktop -->|"server mode"| node_java_app
node_craftflow_landing -.->|"product entry"| node_craftflow_web
node_python_main -->|"exposes"| node_python_api
node_python_main -->|"exposes"| node_python_ws
node_python_api -->|"delegates"| node_python_services
node_python_ws -->|"streams state"| node_python_services
node_python_services -->|"persists"| node_python_task_store
node_python_services -->|"checkpoints"| node_python_checkpointer
node_python_services -->|"runs"| node_python_creation_graph
node_python_services -->|"runs"| node_python_polishing_graph
node_python_creation_graph -->|"shared LLM"| node_python_graph_common
node_python_polishing_graph -->|"shared LLM"| node_python_graph_common
node_python_creation_graph -->|"tool use"| node_python_tools
node_python_polishing_graph -->|"tool use"| node_python_tools
node_java_app -->|"owns"| node_java_auth
node_java_app -->|"owns"| node_java_chat
node_java_app -->|"owns"| node_java_tasks
node_java_app -->|"owns"| node_java_quota
node_java_app -->|"delegates AI"| node_java_gateway
node_java_app -->|"push updates"| node_java_ws
node_java_listeners -->|"events"| node_java_ws
node_java_tasks -->|"start/track"| node_java_gateway
node_deploy_assets -.->|"build/deploy"| node_craftflow_web
node_deploy_assets -.->|"build/deploy"| node_python_main
node_deploy_assets -.->|"build/deploy"| node_java_app

click node_craftflow_web "https://github.com/renhao-wan/craftflow/tree/master/craftflow-web"
click node_craftflow_desktop "https://github.com/renhao-wan/craftflow/tree/master/craftflow-desktop"
click node_craftflow_landing "https://github.com/renhao-wan/craftflow/tree/master/craftflow-landing"
click node_python_main "https://github.com/renhao-wan/craftflow/blob/master/craftflow-backend/app/main.py"
click node_python_api "https://github.com/renhao-wan/craftflow/blob/master/craftflow-backend/app/api/v1/router.py"
click node_python_ws "https://github.com/renhao-wan/craftflow/blob/master/craftflow-backend/app/api/v1/ws_handler.py"
click node_python_creation_graph "https://github.com/renhao-wan/craftflow/blob/master/craftflow-backend/app/graph/creation/builder.py"
click node_python_polishing_graph "https://github.com/renhao-wan/craftflow/blob/master/craftflow-backend/app/graph/polishing/builder.py"
click node_python_graph_common "https://github.com/renhao-wan/craftflow/blob/master/craftflow-backend/app/graph/common/llm_factory.py"
click node_python_tools "https://github.com/renhao-wan/craftflow/tree/master/craftflow-backend/app/graph/tools"
click node_python_services "https://github.com/renhao-wan/craftflow/tree/master/craftflow-backend/app/services"
click node_python_task_store "https://github.com/renhao-wan/craftflow/blob/master/craftflow-backend/app/services/task_store.py"
click node_python_checkpointer "https://github.com/renhao-wan/craftflow/blob/master/craftflow-backend/app/services/checkpointer.py"
click node_java_app "https://github.com/renhao-wan/craftflow/blob/master/java-backend/src/main/java/com/craftflow/CraftFlowApplication.java"
click node_java_auth "https://github.com/renhao-wan/craftflow/tree/master/java-backend/src/main/java/com/craftflow/auth"
click node_java_chat "https://github.com/renhao-wan/craftflow/tree/master/java-backend/src/main/java/com/craftflow/chat"
click node_java_tasks "https://github.com/renhao-wan/craftflow/tree/master/java-backend/src/main/java/com/craftflow/task"
click node_java_quota "https://github.com/renhao-wan/craftflow/tree/master/java-backend/src/main/java/com/craftflow/quota"
click node_java_gateway "https://github.com/renhao-wan/craftflow/blob/master/java-backend/src/main/java/com/craftflow/infrastructure/gateway/PythonGateway.java"
click node_java_ws "https://github.com/renhao-wan/craftflow/tree/master/java-backend/src/main/java/com/craftflow/infrastructure/websocket"
click node_java_listeners "https://github.com/renhao-wan/craftflow/blob/master/java-backend/src/main/java/com/craftflow/infrastructure/listener/PgTaskListener.java"
click node_deploy_assets "https://github.com/renhao-wan/craftflow/blob/master/docker-compose.yml"

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_craftflow_web,node_craftflow_desktop,node_craftflow_landing toneBlue
class node_python_main,node_python_api,node_python_ws,node_python_creation_graph,node_python_polishing_graph,node_python_graph_common,node_python_tools,node_python_services,node_python_task_store,node_python_checkpointer toneAmber
class node_java_app,node_java_auth,node_java_chat,node_java_tasks,node_java_quota,node_java_gateway,node_java_ws,node_java_listeners toneMint
class node_deploy_assets toneRose
```

## Components

### Client surfaces

User-facing entry points for browser, desktop, and landing pages.

- [Web app](https://github.com/renhao-wan/craftflow/tree/master/craftflow-web): Vue 3 SPA · Main browser client for chat, creation, polishing, settings, and task history. · `craftflow-web`
- [Desktop app](https://github.com/renhao-wan/craftflow/tree/master/craftflow-desktop): Electron shell · Packaged desktop experience with local runtime configuration. · `craftflow-desktop`
- [Landing site](https://github.com/renhao-wan/craftflow/tree/master/craftflow-landing): Vite marketing · Public site for docs, screenshots, and product discovery. · `craftflow-landing`

### Python engine

FastAPI app and LangGraph workflow runtime for content generation.

- [API entry](https://github.com/renhao-wan/craftflow/blob/master/craftflow-backend/app/main.py): FastAPI app · Python backend startup and top-level wiring. · `craftflow-backend/app/main.py`
- [REST API](https://github.com/renhao-wan/craftflow/blob/master/craftflow-backend/app/api/v1/router.py): v1 routers · HTTP surface for chat, creation, polishing, tasks, settings, and internal endpoints. · `craftflow-backend/app/api/v1/router.py`
- [Realtime API](https://github.com/renhao-wan/craftflow/blob/master/craftflow-backend/app/api/v1/ws_handler.py): WS/SSE handlers · Streaming and resumable execution channels for task status and token events. · `craftflow-backend/app/api/v1/ws_handler.py`
- [Creation flow](https://github.com/renhao-wan/craftflow/blob/master/craftflow-backend/app/graph/creation/builder.py): LangGraph pipeline · Outline planning, confirmation pause, parallel section writing, and reduction. · `craftflow-backend/app/graph/creation/builder.py`
- [Polishing flow](https://github.com/renhao-wan/craftflow/blob/master/craftflow-backend/app/graph/polishing/builder.py): LangGraph pipeline · Fast correction and deeper debate/reflexion polishing paths. · `craftflow-backend/app/graph/polishing/builder.py`
- [Graph common](https://github.com/renhao-wan/craftflow/blob/master/craftflow-backend/app/graph/common/llm_factory.py): LLM helpers · Shared model factory, prompt helpers, and cross-graph utilities. · `craftflow-backend/app/graph/common/llm_factory.py`
- [Toolchain](https://github.com/renhao-wan/craftflow/tree/master/craftflow-backend/app/graph/tools): Search/code tools · External capability layer for search, sandboxed execution, retrieval, and validation. · `craftflow-backend/app/graph/tools`
- [Task services](https://github.com/renhao-wan/craftflow/tree/master/craftflow-backend/app/services): Orchestration svc · Creation, polishing, chat, broadcasting, persistence, and checkpoint coordination. · `craftflow-backend/app/services`
- [Task store](https://github.com/renhao-wan/craftflow/blob/master/craftflow-backend/app/services/task_store.py): SQLite/Postgres · Deployment-dependent persistence for tasks and resumable workflow state. · `craftflow-backend/app/services/task_store.py`
- [Checkpointer](https://github.com/renhao-wan/craftflow/blob/master/craftflow-backend/app/services/checkpointer.py): Resume state · Graph checkpointing for pause, recovery, and resumable execution. · `craftflow-backend/app/services/checkpointer.py`

### Java server

Spring Boot server-mode backend for auth, quotas, tasks, and push delivery.

- [Server app](https://github.com/renhao-wan/craftflow/blob/master/java-backend/src/main/java/com/craftflow/CraftFlowApplication.java): Spring Boot · Centralized deployment backend and public server-mode runtime. · `java-backend/src/main/java/com/craftflow/CraftFlowApplication.java`
- [Auth](https://github.com/renhao-wan/craftflow/tree/master/java-backend/src/main/java/com/craftflow/auth): JWT/cert login · Authentication boundary with JWT and certificate-based login flows. · `java-backend/src/main/java/com/craftflow/auth`
- [Chat](https://github.com/renhao-wan/craftflow/tree/master/java-backend/src/main/java/com/craftflow/chat): Conversation svc · Chat persistence and messaging endpoints. · `java-backend/src/main/java/com/craftflow/chat`
- [Task svc](https://github.com/renhao-wan/craftflow/tree/master/java-backend/src/main/java/com/craftflow/task): Task lifecycle · Task persistence, status handling, and timeout management. · `java-backend/src/main/java/com/craftflow/task`
- [Quota svc](https://github.com/renhao-wan/craftflow/tree/master/java-backend/src/main/java/com/craftflow/quota): Usage limits · Per-user quota tracking and enforcement. · `java-backend/src/main/java/com/craftflow/quota`
- [Python gateway](https://github.com/renhao-wan/craftflow/blob/master/java-backend/src/main/java/com/craftflow/infrastructure/gateway/PythonGateway.java): Bridge client · Calls into the Python AI backend from server mode. · `java-backend/src/main/java/com/craftflow/infrastructure/gateway/PythonGateway.java`
- [WebSocket hub](https://github.com/renhao-wan/craftflow/tree/master/java-backend/src/main/java/com/craftflow/infrastructure/websocket): Push channel · WebSocket session management and client event delivery. · `java-backend/src/main/java/com/craftflow/infrastructure/websocket`
- [DB listeners](https://github.com/renhao-wan/craftflow/blob/master/java-backend/src/main/java/com/craftflow/infrastructure/listener/PgTaskListener.java): Event listener · Database and task event listeners that feed push updates. · `java-backend/src/main/java/com/craftflow/infrastructure/listener/PgTaskListener.java`

### Ops & delivery

Container, proxy, and CI assets for deployment.

- [Deployment](https://github.com/renhao-wan/craftflow/blob/master/docker-compose.yml): Docker/nginx/CI · Container, reverse-proxy, database init, and workflow automation assets. · `docker-compose.yml`

## Connections

- Web app → Server app: server mode · Browser client talks to the centralized Java backend for authentication, chat, and task APIs.
- Web app → API entry: standalone mode · Browser client can target the Python service directly in local deployments.
- Web app → Realtime API: streaming · Receives task progress and token streaming over realtime channels.
- Desktop app → API entry: bundled runtime · Desktop shell wraps the app and can run with local backend configuration.
- Desktop app → Server app: server mode · Desktop client can connect to the centralized server backend.
- Landing site → Web app: product entry · Marketing site points users toward the main application surface.
- API entry → REST API: exposes · Bootstraps the REST API surface.
- API entry → Realtime API: exposes · Bootstraps WebSocket and SSE streaming endpoints.
- REST API → Task services: delegates · HTTP routes hand off to task and chat services.
- Realtime API → Task services: streams state · Realtime handlers subscribe to task execution and broadcaster state.
- Task services → Task store: persists · Task orchestration stores and loads workflow state.
- Task services → Checkpointer: checkpoints · Interruptible flows pause and resume through checkpoint state.
- Task services → Creation flow: runs · Creation service drives the creation workflow graph.
- Task services → Polishing flow: runs · Polishing service drives the polishing workflow graph.
- Creation flow → Graph common: shared LLM · Creation flow uses shared model and prompt utilities.
- Polishing flow → Graph common: shared LLM · Polishing flow uses shared model and prompt utilities.
- Creation flow → Toolchain: tool use · Creation flow can call search, retrieval, sandbox, and validators.
- Polishing flow → Toolchain: tool use · Polishing flow can call tools where deeper reasoning needs external capability.
- Server app → Auth: owns · Server backend exposes auth as a first-class boundary.
- Server app → Chat: owns · Server backend exposes chat persistence and messaging.
- Server app → Task svc: owns · Server backend exposes task lifecycle management.
- Server app → Quota svc: owns · Server backend enforces user usage limits.
- Server app → Python gateway: delegates AI · Server backend forwards generation work to the Python engine.
- Server app → WebSocket hub: push updates · Server backend delivers realtime state to clients.
- DB listeners → WebSocket hub: events · Task and database listeners publish updates into the websocket hub.
- Task svc → Python gateway: start/track · Task service coordinates AI execution through the Python bridge.
- Deployment → Web app: build/deploy · Container and CI assets package the web client.
- Deployment → API entry: build/deploy · Container and CI assets package the Python backend.
- Deployment → Server app: build/deploy · Container and CI assets package the Java server backend.
