# gml-mmgroup/adcraft architecture

> Architecture diagram of the GitHub repository gml-mmgroup/adcraft, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gml-mmgroup/adcraft
- Repository: https://github.com/gml-mmgroup/adcraft

## Overview

AdCraft turns a marketing brief into an editable advertising-production workflow: creative planning and script, product/character/scene design, storyboard, media generation, and final composition. Users can refine work through canvas operations or conversation, while the asset library supports reuse. The graph combines README-documented capabilities with paths in the supplied tree; several feature paths were not sampled, so uncertain internal call wiring is omitted. The shown generation and persistence layers reflect sampled source responsibilities, not a complete call trace.

Main entry points: [`apps/api/app/api/v2/endpoints/agent_canvas.py`](https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/api/v2/endpoints/agent_canvas.py) (Workflow API), [`apps/api/app/services/v2_generation_pipeline.py`](https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/services/v2_generation_pipeline.py) (Generation Pipeline), [`apps/api/app/services/agent_canvas_production_journey.py`](https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/services/agent_canvas_production_journey.py) (Creative Planning), [`apps/api/app/api/v1/endpoints/canvas_runtime.py`](https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/api/v1/endpoints/canvas_runtime.py) (Canvas API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Creation Experience"]
  node_canvas_ui["Agent Canvas"]
  node_conversation_ui["Conversation"]
  node_canvas_api["Canvas API<br/>[canvas_runtime.py]"]
  node_workflow_api["Workflow API<br/>[agent_canvas.py]"]
end

subgraph group_workflow["Creative Workflow"]
  node_planning["Creative Planning"]
  node_script_visuals["Script and Designs"]
  node_storyboard["Storyboard"]
  node_editable_flow["Editable Workflow"]
  node_specialist_llm["Specialist Prompts"]
end

subgraph group_generation["Media Generation"]
  node_generation_pipeline["Generation Pipeline"]
  node_image_provider["Image Provider"]
  node_music_provider["Music Provider"]
  node_composition["Final Composition"]
end

subgraph group_assets["Assets and State"]
  node_asset_library["Asset Library<br/>[asset_library.py]"]
  node_media_storage[("Media Storage")]
  node_database[("Application State<br/>[database.py]")]
  node_browser_storage[("Browser Storage<br/>[hybridStorage.ts]")]
end

subgraph group_runtime["Agent Runtime"]
  node_api_app["HTTP Application<br/>[main.py]"]
  node_agent_service["Agent Service<br/>[server.ts]"]
end

node_marketer(("Marketer"))

node_marketer -->|"describes and edits"| node_canvas_ui
node_marketer -->|"requests changes"| node_conversation_ui
node_canvas_ui -->|"submits canvas actions"| node_canvas_api
node_conversation_ui -->|"sends creative context"| node_workflow_api
node_canvas_api -->|"starts guided creation"| node_planning
node_workflow_api -->|"requests workflow work"| node_planning
node_planning -->|"plans creative stages"| node_script_visuals
node_planning -->|"plans shots"| node_storyboard
node_planning -->|"creates editable flow"| node_editable_flow
node_editable_flow -->|"returns workflow state"| node_workflow_api
node_workflow_api -->|"requests structured prompts"| node_specialist_llm
node_generation_pipeline -.->|"submits image work"| node_image_provider
node_generation_pipeline -.->|"submits music work"| node_music_provider
node_generation_pipeline -->|"publishes media"| node_media_storage
node_generation_pipeline -->|"publishes generated assets"| node_asset_library
node_generation_pipeline -->|"prepares composition"| node_composition
node_asset_library -->|"stores media objects"| node_media_storage
node_canvas_api -->|"persists workflow state"| node_database
node_workflow_api -->|"persists workflow state"| node_database
node_canvas_ui -->|"caches project state"| node_browser_storage
node_api_app -->|"routes requests"| node_canvas_api
node_api_app -->|"routes requests"| node_workflow_api
node_agent_service -.->|"serves internal agent runs"| node_api_app

click node_canvas_ui "https://github.com/gml-mmgroup/adcraft/blob/main/apps/web/src/features/agent-canvas/session/useAgentCanvasSession.ts"
click node_conversation_ui "https://github.com/gml-mmgroup/adcraft/blob/main/apps/web/src/features/agent-canvas/chat/useComposerContext.ts"
click node_canvas_api "https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/api/v1/endpoints/canvas_runtime.py"
click node_workflow_api "https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/api/v2/endpoints/agent_canvas.py"
click node_planning "https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/services/agent_canvas_production_journey.py"
click node_script_visuals "https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/services/agent_canvas_nodes.py"
click node_storyboard "https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/services/agent_canvas_storyboard_sequences.py"
click node_editable_flow "https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/services/agent_canvas_commands.py"
click node_specialist_llm "https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/services/v2_specialist_llm_client.py"
click node_generation_pipeline "https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/services/v2_generation_pipeline.py"
click node_image_provider "https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/tools/volcengine_image_generations.py"
click node_music_provider "https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/tools/volcengine_pure_music.py"
click node_composition "https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/services/final_composition_timeline.py"
click node_asset_library "https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/services/asset_library.py"
click node_media_storage "https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/services/v2_storage_adapter.py"
click node_database "https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/persistence/database.py"
click node_browser_storage "https://github.com/gml-mmgroup/adcraft/blob/main/apps/web/src/storage/hybridStorage.ts"
click node_api_app "https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/main.py"
click node_agent_service "https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/agent/src/server.ts"

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_canvas_ui,node_conversation_ui,node_canvas_api,node_workflow_api toneBlue
class node_planning,node_script_visuals,node_storyboard,node_editable_flow,node_specialist_llm toneAmber
class node_generation_pipeline,node_image_provider,node_music_provider,node_composition toneMint
class node_asset_library,node_media_storage,node_database,node_browser_storage toneRose
class node_api_app,node_agent_service,node_marketer toneIndigo
```

## Components

### Creation Experience

- [Agent Canvas](https://github.com/gml-mmgroup/adcraft/blob/main/apps/web/src/features/agent-canvas/session/useAgentCanvasSession.ts): `apps/web/src/features/agent-canvas/session/useAgentCanvasSession.ts`
- [Conversation](https://github.com/gml-mmgroup/adcraft/blob/main/apps/web/src/features/agent-canvas/chat/useComposerContext.ts): `apps/web/src/features/agent-canvas/chat/useComposerContext.ts`
- [Canvas API](https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/api/v1/endpoints/canvas_runtime.py): `apps/api/app/api/v1/endpoints/canvas_runtime.py`
- [Workflow API](https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/api/v2/endpoints/agent_canvas.py): `apps/api/app/api/v2/endpoints/agent_canvas.py`

### Creative Workflow

- [Creative Planning](https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/services/agent_canvas_production_journey.py): `apps/api/app/services/agent_canvas_production_journey.py`
- [Script and Designs](https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/services/agent_canvas_nodes.py): `apps/api/app/services/agent_canvas_nodes.py`
- [Storyboard](https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/services/agent_canvas_storyboard_sequences.py): `apps/api/app/services/agent_canvas_storyboard_sequences.py`
- [Editable Workflow](https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/services/agent_canvas_commands.py): `apps/api/app/services/agent_canvas_commands.py`
- [Specialist Prompts](https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/services/v2_specialist_llm_client.py): `apps/api/app/services/v2_specialist_llm_client.py`

### Media Generation

- [Generation Pipeline](https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/services/v2_generation_pipeline.py): `apps/api/app/services/v2_generation_pipeline.py`
- [Image Provider](https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/tools/volcengine_image_generations.py): `apps/api/app/tools/volcengine_image_generations.py`
- [Music Provider](https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/tools/volcengine_pure_music.py): `apps/api/app/tools/volcengine_pure_music.py`
- [Final Composition](https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/services/final_composition_timeline.py): `apps/api/app/services/final_composition_timeline.py`

### Assets and State

- [Asset Library](https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/services/asset_library.py): `apps/api/app/services/asset_library.py`
- [Media Storage](https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/services/v2_storage_adapter.py): `apps/api/app/services/v2_storage_adapter.py`
- [Application State](https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/persistence/database.py): `apps/api/app/persistence/database.py`
- [Browser Storage](https://github.com/gml-mmgroup/adcraft/blob/main/apps/web/src/storage/hybridStorage.ts): `apps/web/src/storage/hybridStorage.ts`

### Agent Runtime

- [HTTP Application](https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/app/main.py): `apps/api/app/main.py`
- [Agent Service](https://github.com/gml-mmgroup/adcraft/blob/main/apps/api/agent/src/server.ts): `apps/api/agent/src/server.ts`

### Other components

- **Marketer**

## Connections

- Marketer → Agent Canvas: describes and edits
- Marketer → Conversation: requests changes
- Agent Canvas → Canvas API: submits canvas actions
- Conversation → Workflow API: sends creative context
- Canvas API → Creative Planning: starts guided creation
- Workflow API → Creative Planning: requests workflow work
- Creative Planning → Script and Designs: plans creative stages
- Creative Planning → Storyboard: plans shots
- Creative Planning → Editable Workflow: creates editable flow
- Editable Workflow → Workflow API: returns workflow state
- Workflow API → Specialist Prompts: requests structured prompts
- Generation Pipeline → Image Provider: submits image work
- Generation Pipeline → Music Provider: submits music work
- Generation Pipeline → Media Storage: publishes media
- Generation Pipeline → Asset Library: publishes generated assets
- Generation Pipeline → Final Composition: prepares composition
- Asset Library → Media Storage: stores media objects
- Canvas API → Application State: persists workflow state
- Workflow API → Application State: persists workflow state
- Agent Canvas → Browser Storage: caches project state
- HTTP Application → Canvas API: routes requests
- HTTP Application → Workflow API: routes requests
- Agent Service → HTTP Application: serves internal agent runs