# chadowsaln/shadow-studio architecture

> Architecture diagram of the GitHub repository chadowsaln/shadow-studio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chadowsaln/shadow-studio
- Repository: https://github.com/chadowsaln/shadow-studio

## Overview

Shadow Studio is a local-first desktop video editor with an optional AI-agent workflow. A user edits a timeline and media through the desktop UI; editing commands update the project model, which can be saved locally or rendered through the render pipeline. The agent can plan and execute edits using tools, permissions, and optional provider access. The README documents these capabilities and boundaries, but most Dart implementation files were not sampled; edges below reflect documented relationships, not a source-level call trace. Desktop preview and export are described as simulated.

Main entry points: [`packages/agent_runtime/lib/src/agent_controller.dart`](https://github.com/chadowsaln/shadow-studio/blob/main/packages/agent_runtime/lib/src/agent_controller.dart) (Agent Controller), [`packages/tool_system/lib/src/tool_executor.dart`](https://github.com/chadowsaln/shadow-studio/blob/main/packages/tool_system/lib/src/tool_executor.dart) (Tool Executor), [`apps/desktop/lib/src/controller/editor_controller.dart`](https://github.com/chadowsaln/shadow-studio/blob/main/apps/desktop/lib/src/controller/editor_controller.dart) (Editor Controller), [`packages/editing_core/lib/src`](https://github.com/chadowsaln/shadow-studio/tree/main/packages/editing_core/lib/src) (Editing Core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop Editing"]
  node_desktop_app["Desktop App<br/>[app.dart]"]
  node_editor_ui["Editing UI"]
  node_editor_controller["Editor Controller"]
end

subgraph group_editing["Editing and Media"]
  node_editing_core["Editing Core"]
  node_project_model["Project Model"]
  node_media_library["Media Library"]
  node_media_worker["Media Worker"]
end

subgraph group_agent["Agent and Safety"]
  node_agent_controller["Agent Controller"]
  node_agent_context["Context Assembly"]
  node_agent_planner["Agent Planning<br/>[planner.dart]"]
  node_tool_registry["Tool Registry<br/>[tool_registry.dart]"]
  node_tool_executor["Tool Executor<br/>[tool_executor.dart]"]
  node_permissions["Permission Engine"]
  node_provider_gateway["Provider Gateway"]
  node_context_engine["Context Engine"]
end

subgraph group_render["Render and Storage"]
  node_render_pipeline["Render Pipeline<br/>[render_queue.dart]"]
  node_local_storage[("Local Storage")]
end

node_user(("Editor"))
node_external_provider(("AI Provider"))

node_user -->|"uses"| node_desktop_app
node_desktop_app -->|"presents"| node_editor_ui
node_editor_ui -->|"edits through"| node_editor_controller
node_editor_controller -->|"issues commands"| node_editing_core
node_editing_core -->|"updates"| node_project_model
node_media_library -->|"delegates media work"| node_media_worker
node_user -->|"imports media"| node_media_library
node_user -->|"requests assistance"| node_agent_controller
node_agent_controller -->|"assembles context"| node_agent_context
node_agent_controller -->|"plans tasks"| node_agent_planner
node_agent_controller -->|"runs tools"| node_tool_executor
node_tool_executor -->|"dispatches tools"| node_tool_registry
node_tool_executor -->|"checks permissions"| node_permissions
node_tool_executor -->|"applies edits"| node_editing_core
node_agent_controller -.->|"requests provider"| node_provider_gateway
node_provider_gateway -.->|"sends requests"| node_external_provider
node_agent_context -.->|"builds context"| node_context_engine
node_user -->|"exports project"| node_render_pipeline
node_render_pipeline -.->|"renders media"| node_media_worker
node_editor_controller -.->|"saves project"| node_local_storage
node_agent_controller -->|"stores checkpoints"| node_local_storage

click node_desktop_app "https://github.com/chadowsaln/shadow-studio/blob/main/apps/desktop/lib/src/app.dart"
click node_editor_ui "https://github.com/chadowsaln/shadow-studio/tree/main/apps/desktop/lib/src/ui"
click node_editor_controller "https://github.com/chadowsaln/shadow-studio/blob/main/apps/desktop/lib/src/controller/editor_controller.dart"
click node_editing_core "https://github.com/chadowsaln/shadow-studio/tree/main/packages/editing_core/lib/src"
click node_project_model "https://github.com/chadowsaln/shadow-studio/blob/main/packages/editing_core/lib/src/model/project_document.dart"
click node_media_library "https://github.com/chadowsaln/shadow-studio/blob/main/packages/media_core/lib/src/service/media_library_service.dart"
click node_media_worker "https://github.com/chadowsaln/shadow-studio/tree/main/packages/media_core/lib/src/worker"
click node_agent_controller "https://github.com/chadowsaln/shadow-studio/blob/main/packages/agent_runtime/lib/src/agent_controller.dart"
click node_agent_context "https://github.com/chadowsaln/shadow-studio/blob/main/packages/agent_runtime/lib/src/agent_context_assembler.dart"
click node_agent_planner "https://github.com/chadowsaln/shadow-studio/blob/main/packages/agent_runtime/lib/src/planner.dart"
click node_tool_registry "https://github.com/chadowsaln/shadow-studio/blob/main/packages/tool_system/lib/src/tool_registry.dart"
click node_tool_executor "https://github.com/chadowsaln/shadow-studio/blob/main/packages/tool_system/lib/src/tool_executor.dart"
click node_permissions "https://github.com/chadowsaln/shadow-studio/blob/main/packages/permissions/lib/src/permission_manager.dart"
click node_provider_gateway "https://github.com/chadowsaln/shadow-studio/blob/main/packages/provider_gateway/lib/src/provider_router.dart"
click node_render_pipeline "https://github.com/chadowsaln/shadow-studio/blob/main/packages/render_pipeline/lib/src/render_queue.dart"
click node_local_storage "https://github.com/chadowsaln/shadow-studio/tree/main/packages/local_storage/lib/src"
click node_context_engine "https://github.com/chadowsaln/shadow-studio/blob/main/packages/context_engine/lib/src/context_builder.dart"

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_desktop_app,node_editor_ui,node_editor_controller toneBlue
class node_editing_core,node_project_model,node_media_library,node_media_worker toneAmber
class node_agent_controller,node_agent_context,node_agent_planner,node_tool_registry,node_tool_executor,node_permissions,node_provider_gateway,node_context_engine toneMint
class node_render_pipeline,node_local_storage toneRose
class node_user,node_external_provider toneIndigo
```

## Components

### Desktop Editing

- [Desktop App](https://github.com/chadowsaln/shadow-studio/blob/main/apps/desktop/lib/src/app.dart): `apps/desktop/lib/src/app.dart`
- [Editing UI](https://github.com/chadowsaln/shadow-studio/tree/main/apps/desktop/lib/src/ui): `apps/desktop/lib/src/ui`
- [Editor Controller](https://github.com/chadowsaln/shadow-studio/blob/main/apps/desktop/lib/src/controller/editor_controller.dart): `apps/desktop/lib/src/controller/editor_controller.dart`

### Editing and Media

- [Editing Core](https://github.com/chadowsaln/shadow-studio/tree/main/packages/editing_core/lib/src): `packages/editing_core/lib/src`
- [Project Model](https://github.com/chadowsaln/shadow-studio/blob/main/packages/editing_core/lib/src/model/project_document.dart): `packages/editing_core/lib/src/model/project_document.dart`
- [Media Library](https://github.com/chadowsaln/shadow-studio/blob/main/packages/media_core/lib/src/service/media_library_service.dart): `packages/media_core/lib/src/service/media_library_service.dart`
- [Media Worker](https://github.com/chadowsaln/shadow-studio/tree/main/packages/media_core/lib/src/worker): `packages/media_core/lib/src/worker`

### Agent and Safety

- [Agent Controller](https://github.com/chadowsaln/shadow-studio/blob/main/packages/agent_runtime/lib/src/agent_controller.dart): `packages/agent_runtime/lib/src/agent_controller.dart`
- [Context Assembly](https://github.com/chadowsaln/shadow-studio/blob/main/packages/agent_runtime/lib/src/agent_context_assembler.dart): `packages/agent_runtime/lib/src/agent_context_assembler.dart`
- [Agent Planning](https://github.com/chadowsaln/shadow-studio/blob/main/packages/agent_runtime/lib/src/planner.dart): `packages/agent_runtime/lib/src/planner.dart`
- [Tool Registry](https://github.com/chadowsaln/shadow-studio/blob/main/packages/tool_system/lib/src/tool_registry.dart): `packages/tool_system/lib/src/tool_registry.dart`
- [Tool Executor](https://github.com/chadowsaln/shadow-studio/blob/main/packages/tool_system/lib/src/tool_executor.dart): `packages/tool_system/lib/src/tool_executor.dart`
- [Permission Engine](https://github.com/chadowsaln/shadow-studio/blob/main/packages/permissions/lib/src/permission_manager.dart): `packages/permissions/lib/src/permission_manager.dart`
- [Provider Gateway](https://github.com/chadowsaln/shadow-studio/blob/main/packages/provider_gateway/lib/src/provider_router.dart): `packages/provider_gateway/lib/src/provider_router.dart`
- [Context Engine](https://github.com/chadowsaln/shadow-studio/blob/main/packages/context_engine/lib/src/context_builder.dart): `packages/context_engine/lib/src/context_builder.dart`

### Render and Storage

- [Render Pipeline](https://github.com/chadowsaln/shadow-studio/blob/main/packages/render_pipeline/lib/src/render_queue.dart): `packages/render_pipeline/lib/src/render_queue.dart`
- [Local Storage](https://github.com/chadowsaln/shadow-studio/tree/main/packages/local_storage/lib/src): `packages/local_storage/lib/src`

### Other components

- **Editor**
- **AI Provider**

## Connections

- Editor → Desktop App: uses
- Desktop App → Editing UI: presents
- Editing UI → Editor Controller: edits through
- Editor Controller → Editing Core: issues commands
- Editing Core → Project Model: updates
- Media Library → Media Worker: delegates media work
- Editor → Media Library: imports media
- Editor → Agent Controller: requests assistance
- Agent Controller → Context Assembly: assembles context
- Agent Controller → Agent Planning: plans tasks
- Agent Controller → Tool Executor: runs tools
- Tool Executor → Tool Registry: dispatches tools
- Tool Executor → Permission Engine: checks permissions
- Tool Executor → Editing Core: applies edits
- Agent Controller → Provider Gateway: requests provider
- Provider Gateway → AI Provider: sends requests
- Context Assembly → Context Engine: builds context
- Editor → Render Pipeline: exports project
- Render Pipeline → Media Worker: renders media
- Editor Controller → Local Storage: saves project
- Agent Controller → Local Storage: stores checkpoints
