# zhx47/ppt-agent architecture

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

- Interactive diagram: https://gitdiagram.com/zhx47/ppt-agent
- Repository: https://github.com/zhx47/ppt-agent

## Overview

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: [`src/App.tsx`](https://github.com/zhx47/ppt-agent/blob/main/src/App.tsx) (App shell), [`backend/app/services/orchestrator.py`](https://github.com/zhx47/ppt-agent/blob/main/backend/app/services/orchestrator.py) (Orchestrator), [`src/components/Editor.tsx`](https://github.com/zhx47/ppt-agent/blob/main/src/components/Editor.tsx) (Editor), [`backend/app/services/generation.py`](https://github.com/zhx47/ppt-agent/blob/main/backend/app/services/generation.py) (Generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_src_app["App shell<br/>React entry<br/>[App.tsx]"]
  node_src_home["Home<br/>workspace page<br/>[Home.tsx]"]
  node_src_start["Project start<br/>onboarding page<br/>[ProjectStart.tsx]"]
  node_src_activity["Agent activity<br/>workflow view<br/>[AgentActivity.tsx]"]
  node_src_editor["Editor<br/>[Editor.tsx]"]
  node_src_storyboard["Storyboard<br/>editor panel"]
  node_src_player["Playback<br/>editor panel"]
  node_src_bits["Editor bits<br/>editor primitives<br/>[EditorBits.tsx]"]
  node_src_api["PPT API<br/>api client<br/>[ppt-api.ts]"]
  node_src_workflow["Workflow state<br/>ui helpers<br/>[workflow-ui.ts]"]
  node_src_singleflight["Single-flight<br/>request dedupe<br/>[single-flight.ts]"]
end

subgraph group_backend_api["Backend API"]
  node_backend_main["FastAPI app<br/>server entry<br/>[main.py]"]
  node_backend_router["API router<br/>HTTP surface<br/>[router.py]"]
  node_backend_routes["Domain routes<br/>route modules<br/>[projects.py]"]
  node_backend_deps["Dependencies<br/>wiring<br/>[deps.py]"]
end

subgraph group_backend_core["Backend core"]
  node_backend_config["Config<br/>[config.py]"]
  node_backend_db[("DB boundary<br/>persistence<br/>[db.py]")]
  node_backend_models["Domain models<br/>ORM entities<br/>[entities.py]"]
  node_backend_schemas["API schemas<br/>transport contracts<br/>[api.py]"]
end

subgraph group_backend_services["Workflow services"]
  node_backend_orch["Orchestrator<br/>workflow engine<br/>[orchestrator.py]"]
  node_backend_research["Research<br/>retrieval stage<br/>[research.py]"]
  node_backend_generation["Generation<br/>render stage<br/>[generation.py]"]
  node_backend_events["Event stream<br/>SSE/events<br/>[events.py]"]
  node_backend_model["Model gateway<br/>LLM integration<br/>[model_gateway.py]"]
  node_backend_mcp["MCP gateway<br/>retrieval integration<br/>[mcp_gateway.py]"]
  node_backend_background["Background jobs<br/>async execution<br/>[background.py]"]
end

subgraph group_external["External systems"]
  node_backend_export["PPTX export<br/>artifact sink"]
  node_backend_storage[("File storage<br/>artifact store")]
  node_backend_search["Retrieval services<br/>external knowledge"]
  node_backend_llm["Model provider<br/>external LLM"]
  node_backend_database[("Database<br/>postgres/sqlite")]
end

node_src_app -->|"renders"| node_src_home
node_src_app -->|"routes to"| node_src_start
node_src_app -->|"shows"| node_src_activity
node_src_app -->|"opens"| node_src_editor
node_src_editor -->|"contains"| node_src_storyboard
node_src_editor -->|"contains"| node_src_player
node_src_editor -.->|"uses"| node_src_bits
node_src_app -->|"calls"| node_src_api
node_src_app -.->|"derives UI"| node_src_workflow
node_src_app -.->|"dedupes"| node_src_singleflight
node_src_api -->|"HTTP"| node_backend_router
node_backend_main -->|"mounts"| node_backend_router
node_backend_router -->|"dispatches"| node_backend_routes
node_backend_router -.->|"injects"| node_backend_deps
node_backend_routes -->|"triggers"| node_backend_orch
node_backend_orch -->|"schedules"| node_backend_background
node_backend_orch -->|"requests"| node_backend_research
node_backend_orch -->|"drives"| node_backend_generation
node_backend_orch -->|"publishes"| node_backend_events
node_backend_orch -->|"reads/writes"| node_backend_db
node_backend_research -->|"retrieves"| node_backend_mcp
node_backend_mcp -->|"queries"| node_backend_search
node_backend_generation -->|"invokes"| node_backend_model
node_backend_model -->|"calls"| node_backend_llm
node_backend_generation -->|"writes assets"| node_backend_storage
node_backend_generation -->|"assembles"| node_backend_export
node_backend_db -->|"persists"| node_backend_database
node_backend_routes -.->|"serializes"| node_backend_schemas
node_backend_db -.->|"maps"| node_backend_models
node_backend_config -.->|"configures"| node_backend_db

click node_src_app "https://github.com/zhx47/ppt-agent/blob/main/src/App.tsx"
click node_src_home "https://github.com/zhx47/ppt-agent/blob/main/src/components/Home.tsx"
click node_src_start "https://github.com/zhx47/ppt-agent/blob/main/src/components/ProjectStart.tsx"
click node_src_activity "https://github.com/zhx47/ppt-agent/blob/main/src/components/AgentActivity.tsx"
click node_src_editor "https://github.com/zhx47/ppt-agent/blob/main/src/components/Editor.tsx"
click node_src_storyboard "https://github.com/zhx47/ppt-agent/blob/main/src/components/editor/StoryboardPanel.tsx"
click node_src_player "https://github.com/zhx47/ppt-agent/blob/main/src/components/editor/PresentationPlayer.tsx"
click node_src_bits "https://github.com/zhx47/ppt-agent/blob/main/src/components/editor/EditorBits.tsx"
click node_src_api "https://github.com/zhx47/ppt-agent/blob/main/src/lib/ppt-api.ts"
click node_src_workflow "https://github.com/zhx47/ppt-agent/blob/main/src/lib/workflow-ui.ts"
click node_src_singleflight "https://github.com/zhx47/ppt-agent/blob/main/src/lib/single-flight.ts"
click node_backend_main "https://github.com/zhx47/ppt-agent/blob/main/backend/app/main.py"
click node_backend_router "https://github.com/zhx47/ppt-agent/blob/main/backend/app/api/router.py"
click node_backend_routes "https://github.com/zhx47/ppt-agent/blob/main/backend/app/api/routes/projects.py"
click node_backend_deps "https://github.com/zhx47/ppt-agent/blob/main/backend/app/api/deps.py"
click node_backend_config "https://github.com/zhx47/ppt-agent/blob/main/backend/app/core/config.py"
click node_backend_db "https://github.com/zhx47/ppt-agent/blob/main/backend/app/core/db.py"
click node_backend_models "https://github.com/zhx47/ppt-agent/blob/main/backend/app/models/entities.py"
click node_backend_schemas "https://github.com/zhx47/ppt-agent/blob/main/backend/app/schemas/api.py"
click node_backend_orch "https://github.com/zhx47/ppt-agent/blob/main/backend/app/services/orchestrator.py"
click node_backend_research "https://github.com/zhx47/ppt-agent/blob/main/backend/app/services/research.py"
click node_backend_generation "https://github.com/zhx47/ppt-agent/blob/main/backend/app/services/generation.py"
click node_backend_events "https://github.com/zhx47/ppt-agent/blob/main/backend/app/services/events.py"
click node_backend_model "https://github.com/zhx47/ppt-agent/blob/main/backend/app/services/model_gateway.py"
click node_backend_mcp "https://github.com/zhx47/ppt-agent/blob/main/backend/app/services/mcp_gateway.py"
click node_backend_background "https://github.com/zhx47/ppt-agent/blob/main/backend/app/services/background.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_src_app,node_src_home,node_src_start,node_src_activity,node_src_editor,node_src_storyboard,node_src_player,node_src_bits,node_src_api,node_src_workflow,node_src_singleflight toneBlue
class node_backend_main,node_backend_router,node_backend_routes,node_backend_deps toneAmber
class node_backend_config,node_backend_db,node_backend_models,node_backend_schemas toneMint
class node_backend_orch,node_backend_research,node_backend_generation,node_backend_events,node_backend_model,node_backend_mcp,node_backend_background toneRose
class node_backend_export,node_backend_storage,node_backend_search,node_backend_llm,node_backend_database toneIndigo
```

## Components

### Frontend

React + Vite control plane for project setup, workflow visibility, and editing.

- [App shell](https://github.com/zhx47/ppt-agent/blob/main/src/App.tsx): React entry · Main frontend entry and workspace composition. · `src/App.tsx`
- [Home](https://github.com/zhx47/ppt-agent/blob/main/src/components/Home.tsx): workspace page · Landing and project entry surface. · `src/components/Home.tsx`
- [Project start](https://github.com/zhx47/ppt-agent/blob/main/src/components/ProjectStart.tsx): onboarding page · Project creation and initial setup flow. · `src/components/ProjectStart.tsx`
- [Agent activity](https://github.com/zhx47/ppt-agent/blob/main/src/components/AgentActivity.tsx): workflow view · Live visibility into orchestration and step state. · `src/components/AgentActivity.tsx`
- [Editor](https://github.com/zhx47/ppt-agent/blob/main/src/components/Editor.tsx): workspace editor · Primary page-level editing and presentation workspace. · `src/components/Editor.tsx`
- [Storyboard](https://github.com/zhx47/ppt-agent/blob/main/src/components/editor/StoryboardPanel.tsx): editor panel · Page sequencing and narrative structure controls. · `src/components/editor/StoryboardPanel.tsx`
- [Playback](https://github.com/zhx47/ppt-agent/blob/main/src/components/editor/PresentationPlayer.tsx): editor panel · Presentation preview and playback surface. · `src/components/editor/PresentationPlayer.tsx`
- [Editor bits](https://github.com/zhx47/ppt-agent/blob/main/src/components/editor/EditorBits.tsx): editor primitives · Shared editor UI fragments and controls. · `src/components/editor/EditorBits.tsx`
- [PPT API](https://github.com/zhx47/ppt-agent/blob/main/src/lib/ppt-api.ts): api client · Frontend boundary for backend CRUD, generation, and workflow calls. · `src/lib/ppt-api.ts`
- [Workflow state](https://github.com/zhx47/ppt-agent/blob/main/src/lib/workflow-ui.ts): ui helpers · Client-side helpers for workflow state and UI coordination. · `src/lib/workflow-ui.ts`
- [Single-flight](https://github.com/zhx47/ppt-agent/blob/main/src/lib/single-flight.ts): request dedupe · Client-side de-duplication for repeated requests. · `src/lib/single-flight.ts`

### Backend API

FastAPI request boundary and route dispatch.

- [FastAPI app](https://github.com/zhx47/ppt-agent/blob/main/backend/app/main.py): server entry · Backend entrypoint and application bootstrap. · `backend/app/main.py`
- [API router](https://github.com/zhx47/ppt-agent/blob/main/backend/app/api/router.py): HTTP surface · Aggregates the domain route modules for the HTTP API. · `backend/app/api/router.py`
- [Domain routes](https://github.com/zhx47/ppt-agent/blob/main/backend/app/api/routes/projects.py): route modules · Project, requirements, outline, and page endpoints. · `backend/app/api/routes/projects.py`
- [Dependencies](https://github.com/zhx47/ppt-agent/blob/main/backend/app/api/deps.py): wiring · Shared request-time dependency setup. · `backend/app/api/deps.py`

### Backend core

Configuration, database wiring, and shared runtime foundations.

- [Config](https://github.com/zhx47/ppt-agent/blob/main/backend/app/core/config.py): runtime config · Environment-driven settings for models, retrieval, and database access. · `backend/app/core/config.py`
- [DB boundary](https://github.com/zhx47/ppt-agent/blob/main/backend/app/core/db.py): persistence · Database access and ORM session boundary. · `backend/app/core/db.py`
- [Domain models](https://github.com/zhx47/ppt-agent/blob/main/backend/app/models/entities.py): ORM entities · Persistent project, page, asset, and workflow entities. · `backend/app/models/entities.py`
- [API schemas](https://github.com/zhx47/ppt-agent/blob/main/backend/app/schemas/api.py): transport contracts · Request and response shapes exposed by the API. · `backend/app/schemas/api.py`

### Workflow services

Orchestration, research, generation, events, and integrations.

- [Orchestrator](https://github.com/zhx47/ppt-agent/blob/main/backend/app/services/orchestrator.py): workflow engine · Coordinates staged agent execution and next-step decisions. · `backend/app/services/orchestrator.py`
- [Research](https://github.com/zhx47/ppt-agent/blob/main/backend/app/services/research.py): retrieval stage · Gathers context for initialization and page-level research. · `backend/app/services/research.py`
- [Generation](https://github.com/zhx47/ppt-agent/blob/main/backend/app/services/generation.py): render stage · Produces draft and design SVG artifacts from page content. · `backend/app/services/generation.py`
- [Event stream](https://github.com/zhx47/ppt-agent/blob/main/backend/app/services/events.py): SSE/events · Publishes live workflow updates to the frontend. · `backend/app/services/events.py`
- [Model gateway](https://github.com/zhx47/ppt-agent/blob/main/backend/app/services/model_gateway.py): LLM integration · OpenAI-compatible model access boundary. · `backend/app/services/model_gateway.py`
- [MCP gateway](https://github.com/zhx47/ppt-agent/blob/main/backend/app/services/mcp_gateway.py): retrieval integration · Retrieval/search integration boundary for external knowledge sources. · `backend/app/services/mcp_gateway.py`
- [Background jobs](https://github.com/zhx47/ppt-agent/blob/main/backend/app/services/background.py): async execution · 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**: artifact sink · Final presentation output generated by the backend.
- **File storage**: artifact store · Uploads, backgrounds, and generated assets stored on disk.
- **Retrieval services**: external knowledge · Search and retrieval providers used during research.
- **Model provider**: external LLM · Upstream model endpoint used for drafting and reasoning.
- **Database**: postgres/sqlite · Primary persistence layer for project state and workflow records.

## Connections

- 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.