How zhx47/ppt-agent works
1. Repository shape
- This repo is split into two primary runtime surfaces:
- src/: the main React + Vite frontend workspace
- backend/: a FastAPI service that owns project state, workflow execution, event streaming, and export
- static/ is an older POC/UI reference, not the main application entrypoint.
2. Product boundary
- The system is not a generic document editor; it is a workflow engine for AI-generated PPTs.
- The backend orchestrates a staged pipeline: project initialization → research → outline → per-page drafting → design rendering → PPTX export.
- The frontend is a control plane for observing and intervening in that pipeline, rather than doing the generation itself.
3. Frontend architecture
- src/App.tsx and the components under src/components/ form a page-based workspace:
- Home, ProjectStart for project creation/onboarding
- AgentActivity for workflow visibility
- Editor plus editor/* for page-level editing, storyboard, draft/design switching, and presentation playback
- src/lib/ppt-api.ts is the client boundary to backend APIs.
- src/lib/single-flight.ts and src/lib/workflow-ui.ts suggest client-side request de-duplication and workflow-state helpers.
4. Frontend-to-backend interaction
- The frontend talks to the backend over HTTP for CRUD and generation actions, and over SSE for live agent events.
- The Vite dev setup proxies /api and /storage to the backend, which makes the backend the single origin for both data and file assets.
- The UI is therefore driven by backend state changes, not by local-only state.
5. Backend entry and API boundary
- backend/app/main.py is the FastAPI entrypoint.
- backend/app/api/router.py and backend/app/api/routes/* define the HTTP surface, organized by domain:
- projects.py
- requirements.py
- outline.py
- pages.py
- backend/app/api/deps.py centralizes dependency wiring for request handlers.
6. Core domain model
- backend/app/models/entities.py, types.py, and base.py define the persistent domain objects and shared ORM foundations.
- The domain is centered on project records, requirement artifacts, outline/page entities, generated assets, and workflow status.
- backend/app/schemas/api.py provides the request/response shapes exposed by the API, separating transport contracts from ORM models.
7. Persistence and runtime state
- backend/app/core/db.py is the database boundary.
- The README indicates a dual persistence strategy:
- PostgreSQL + pgvector for the full vector/retrieval workflow
- SQLite for local lightweight startup
- storage/ is used for files such as uploads, background images, and export artifacts, and the backend auto-creates these directories.
8. Workflow orchestration layer
- backend/app/services/orchestrator.py is the center of the agent workflow.
- background.py indicates that long-running work is executed asynchronously in background threads rather than blocking request handlers.
- events.py and the SSE mention in the README imply a live event stream that publishes router decisions, step transitions, status updates, and next-step suggestions back to the frontend.
9. Generation pipeline
- backend/app/services/generation.py is the content/rendering generation layer.
- prompt_contracts.py likely standardizes prompts and output shapes between stages.
- The workflow produces at least two SVG artifacts per page:
- a draft SVG based on page summary
- a design SVG that incorporates style presets and optional background resources
- This makes SVG a core intermediate artifact, not just a display format.
10. Research and retrieval
- backend/app/services/research.py handles information gathering for the initialization and page-level research stages.
- mcp_gateway.py and model_gateway.py show two external integration boundaries:
- retrieval/search services such as Bocha and Jina through MCP-style gateways
- model calls through an OpenAI-compatible interface
- backend/app/services/mcp_gateway.py is important because the repo explicitly mentions chained retrieval via Bocha/Jina/MCP.
11. Export path
- The final delivery format is PPTX, generated through the backend using python-pptx per the README.
- Export is part of the backend pipeline, not a frontend responsibility.
- This keeps the document assembly logic close to the generated design assets and persisted project/page state.
12. Operational and integration considerations
- backend/app/core/config.py and logging.py suggest centralized runtime configuration and structured logging.
- The repo expects environment-driven setup for model keys, retrieval endpoints, and database connection strings.
- docs/ is a large architectural companion set that documents the intended workflow, project workspace, outline stage, research stage, and backend roadmap; it is useful for understanding the intended boundaries when drawing the system diagram.
13. How to draw the architecture
- Treat the frontend as the interactive orchestration console.
- Treat the backend as a stateful workflow engine with three major internal bands:
- API layer
- domain/persistence layer
- services/orchestration layer
- External systems to show on the diagram:
- database
- file storage
- search/retrieval services
- LLM/model providers
- PPTX export artifact sink
Main entry points: App.tsx App shell · orchestrator.py Orchestrator · Editor.tsx Editor · generation.py Generation
Components 31
Frontend
React + Vite control plane for project setup, workflow visibility, and editing.
- App shell · Main frontend entry and workspace composition.
src/App.tsx - Home · Landing and project entry surface.
src/components/Home.tsx - Project start · Project creation and initial setup flow.
src/components/ProjectStart.tsx - Agent activity · Live visibility into orchestration and step state.
src/components/AgentActivity.tsx - Editor · Primary page-level editing and presentation workspace.
src/components/Editor.tsx - Storyboard · Page sequencing and narrative structure controls.
src/components/editor/StoryboardPanel.tsx - Playback · Presentation preview and playback surface.
src/components/editor/PresentationPlayer.tsx - Editor bits · Shared editor UI fragments and controls.
src/components/editor/EditorBits.tsx - PPT API · Frontend boundary for backend CRUD, generation, and workflow calls.
src/lib/ppt-api.ts - Workflow state · Client-side helpers for workflow state and UI coordination.
src/lib/workflow-ui.ts - Single-flight · Client-side de-duplication for repeated requests.
src/lib/single-flight.ts
Backend API
FastAPI request boundary and route dispatch.
- FastAPI app · Backend entrypoint and application bootstrap.
backend/app/main.py - API router · Aggregates the domain route modules for the HTTP API.
backend/app/api/router.py - Domain routes · Project, requirements, outline, and page endpoints.
backend/app/api/routes/projects.py - Dependencies · Shared request-time dependency setup.
backend/app/api/deps.py
Backend core
Configuration, database wiring, and shared runtime foundations.
- Config · Environment-driven settings for models, retrieval, and database access.
backend/app/core/config.py - DB boundary · Database access and ORM session boundary.
backend/app/core/db.py - Domain models · Persistent project, page, asset, and workflow entities.
backend/app/models/entities.py - API schemas · Request and response shapes exposed by the API.
backend/app/schemas/api.py
Workflow services
Orchestration, research, generation, events, and integrations.
- Orchestrator · Coordinates staged agent execution and next-step decisions.
backend/app/services/orchestrator.py - Research · Gathers context for initialization and page-level research.
backend/app/services/research.py - Generation · Produces draft and design SVG artifacts from page content.
backend/app/services/generation.py - Event stream · Publishes live workflow updates to the frontend.
backend/app/services/events.py - Model gateway · OpenAI-compatible model access boundary.
backend/app/services/model_gateway.py - MCP gateway · Retrieval/search integration boundary for external knowledge sources.
backend/app/services/mcp_gateway.py - Background jobs · Runs long-lived workflow work off the request thread.
backend/app/services/background.py
External systems
Persistence, retrieval, model providers, and output artifacts outside the app runtime.
- PPTX export · Final presentation output generated by the backend.
- File storage · Uploads, backgrounds, and generated assets stored on disk.
- Retrieval services · Search and retrieval providers used during research.
- Model provider · Upstream model endpoint used for drafting and reasoning.
- Database · Primary persistence layer for project state and workflow records.
Connections 30
- App shell → Home: renders · The app shell composes the home workspace.
- App shell → Project start: routes to · Project creation flow is a top-level screen.
- App shell → Agent activity: shows · Workflow visibility is embedded in the workspace.
- App shell → Editor: opens · Primary editing surface is part of the main app.
- Editor → Storyboard: contains · Editor includes storyboard and structure controls.
- Editor → Playback: contains · Editor includes presentation playback.
- Editor → Editor bits: uses · Editor shares reusable UI fragments.
- App shell → PPT API: calls · Frontend issues backend requests through the API client.
- App shell → Workflow state: derives UI · Frontend workflow state is adapted for rendering.
- App shell → Single-flight: dedupes · Repeated requests are coalesced client-side.
- PPT API → API router: HTTP · Client communicates with backend routes over HTTP.
- FastAPI app → API router: mounts · FastAPI entrypoint wires the API router.
- API router → Domain routes: dispatches · Router fans out to domain route modules.
- API router → Dependencies: injects · Handlers receive shared dependencies.
- Domain routes → Orchestrator: triggers · Domain endpoints initiate workflow operations.
- Orchestrator → Background jobs: schedules · Long-running work is offloaded asynchronously.
- Orchestrator → Research: requests · Workflow starts by gathering context and evidence.
- Orchestrator → Generation: drives · Workflow advances through draft and design generation.
- Orchestrator → Event stream: publishes · State transitions and suggestions are streamed to clients.
- Orchestrator → DB boundary: reads/writes · Project and workflow state is persisted.
- Research → MCP gateway: retrieves · Research uses external retrieval/search integrations.
- MCP gateway → Retrieval services: queries · Retrieval gateway reaches search and knowledge services.
- Generation → Model gateway: invokes · Generation relies on model provider calls.
- Model gateway → Model provider: calls · Model gateway delegates to an external LLM endpoint.
- Generation → File storage: writes assets · Generated SVGs and related files are stored.
- Generation → PPTX export: assembles · Final presentation output is exported as PPTX.
- DB boundary → Database: persists · ORM state is stored in the configured database.
- Domain routes → API schemas: serializes · API handlers exchange typed transport objects.
- DB boundary → Domain models: maps · Database state is represented by domain entities.
- Config → DB boundary: configures · Runtime settings determine persistence behavior.