How renhao-wan/craftflow works
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: CraftFlowApplication.java Server app · services Task services · craftflow-web Web app · main.py API entry
Components 22
Client surfaces
User-facing entry points for browser, desktop, and landing pages.
- Web app · Main browser client for chat, creation, polishing, settings, and task history.
craftflow-web - Desktop app · Packaged desktop experience with local runtime configuration.
craftflow-desktop - Landing site · Public site for docs, screenshots, and product discovery.
craftflow-landing
Python engine
FastAPI app and LangGraph workflow runtime for content generation.
- API entry · Python backend startup and top-level wiring.
craftflow-backend/app/main.py - REST API · HTTP surface for chat, creation, polishing, tasks, settings, and internal endpoints.
craftflow-backend/app/api/v1/router.py - Realtime API · Streaming and resumable execution channels for task status and token events.
craftflow-backend/app/api/v1/ws_handler.py - Creation flow · Outline planning, confirmation pause, parallel section writing, and reduction.
craftflow-backend/app/graph/creation/builder.py - Polishing flow · Fast correction and deeper debate/reflexion polishing paths.
craftflow-backend/app/graph/polishing/builder.py - Graph common · Shared model factory, prompt helpers, and cross-graph utilities.
craftflow-backend/app/graph/common/llm_factory.py - Toolchain · External capability layer for search, sandboxed execution, retrieval, and validation.
craftflow-backend/app/graph/tools - Task services · Creation, polishing, chat, broadcasting, persistence, and checkpoint coordination.
craftflow-backend/app/services - Task store · Deployment-dependent persistence for tasks and resumable workflow state.
craftflow-backend/app/services/task_store.py - Checkpointer · 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 · Centralized deployment backend and public server-mode runtime.
java-backend/src/main/java/com/craftflow/CraftFlowApplication.java - Auth · Authentication boundary with JWT and certificate-based login flows.
java-backend/src/main/java/com/craftflow/auth - Chat · Chat persistence and messaging endpoints.
java-backend/src/main/java/com/craftflow/chat - Task svc · Task persistence, status handling, and timeout management.
java-backend/src/main/java/com/craftflow/task - Quota svc · Per-user quota tracking and enforcement.
java-backend/src/main/java/com/craftflow/quota - Python gateway · Calls into the Python AI backend from server mode.
java-backend/src/main/java/com/craftflow/infrastructure/gateway/PythonGateway.java - WebSocket hub · WebSocket session management and client event delivery.
java-backend/src/main/java/com/craftflow/infrastructure/websocket - DB listeners · 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 · Container, reverse-proxy, database init, and workflow automation assets.
docker-compose.yml
Connections 29
- 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.