# shumaione/shumai architecture

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

- Interactive diagram: https://gitdiagram.com/shumaione/shumai
- Repository: https://github.com/shumaione/shumai

## Overview

Shumai is a creative-team media review and collaboration platform, with a web UI, API and core domain services, plus an experimental Premiere Pro plugin and optional AI capabilities. The main workflow is browsing or uploading project media, reviewing it with comments and annotations, and sharing or organizing it with a team. README-described capabilities include transcoding and previews, metadata, search, Kanban, and integrations. Some subsystems are represented from the README and tree; their internal wiring is not inferred where source was not sampled.

Main entry points: [`packages/api/src/index.ts`](https://github.com/shumaione/shumai/blob/main/packages/api/src/index.ts) (HTTP API), [`packages/db/src/index.ts`](https://github.com/shumaione/shumai/blob/main/packages/db/src/index.ts) (Application database), [`packages/agent/src/workflows/agent-chat.ts`](https://github.com/shumaione/shumai/blob/main/packages/agent/src/workflows/agent-chat.ts) (Agent workflows), [`packages/core/src/asset/asset.ts`](https://github.com/shumaione/shumai/blob/main/packages/core/src/asset/asset.ts) (Assets and folders)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experiences"]
  node_web["Web application<br/>[index.tsx]"]
  node_browser["File browser and review"]
  node_publicshare["Public share viewer"]
  node_plugin["Premiere Pro plugin<br/>[App.tsx]"]
  node_cli["CLI<br/>[index.ts]"]
end

subgraph group_domain["Collaboration domain"]
  node_api["HTTP API<br/>[index.ts]"]
  node_projects["Projects and teams<br/>[project.ts]"]
  node_assets["Assets and folders<br/>[asset.ts]"]
  node_comments["Comments and annotations<br/>[chat.ts]"]
  node_sharing["Shares and collections<br/>[share.ts]"]
  node_access["Access control<br/>[authz.ts]"]
  node_metadata["Custom metadata<br/>[metadata.ts]"]
  node_kanban["Kanban tasks<br/>[kanban.ts]"]
  node_search["Semantic search<br/>[search.ts]"]
  node_db[("Application database<br/>[index.ts]")]
end

subgraph group_media["Media handling"]
  node_storage["Asset storage<br/>[s3.ts]"]
  node_transcode["Media transcode workflows<br/>[transcode.ts]"]
  node_preview["Preview conversion"]
end

subgraph group_intelligence["AI capabilities"]
  node_agent["Agent workflows<br/>[agent-chat.ts]"]
  node_agenttools["Agent tools<br/>[list-assets.ts]"]
  node_mcp["MCP connections"]
  node_sandbox["Sandbox execution<br/>[sandbox-service.ts]"]
end

subgraph group_integrations["External integrations"]
  node_premiere["Premiere Pro"]
  node_s3service[("S3-compatible storage")]
  node_temporal["Temporal workers"]
  node_gotenberg["Gotenberg"]
  node_mcpservers["Remote MCP servers"]
end

node_member(("Creative team member"))

node_member -->|"uses"| node_web
node_web -->|"opens media"| node_browser
node_browser -->|"requests files"| node_api
node_publicshare -->|"fetches shared media"| node_api
node_plugin -->|"reads sequences"| node_premiere
node_plugin -->|"fetches comments"| node_api
node_cli -->|"manages assets"| node_api
node_api -->|"serves project operations"| node_projects
node_api -->|"serves asset operations"| node_assets
node_api -->|"serves share operations"| node_sharing
node_api -->|"serves review operations"| node_comments
node_api -->|"serves task operations"| node_kanban
node_api -->|"serves metadata operations"| node_metadata
node_api -->|"serves search requests"| node_search
node_assets -->|"stores media"| node_storage
node_storage -->|"reads and writes"| node_s3service
node_transcode -.->|"runs workflows"| node_temporal
node_transcode -->|"processes media"| node_storage
node_preview -.->|"converts documents"| node_gotenberg
node_agent -->|"dispatches tools"| node_agenttools
node_agent -.->|"uses configured tools"| node_mcp
node_mcp -.->|"connects to"| node_mcpservers
node_agent -.->|"runs scripts"| node_sandbox
node_agent -.->|"supports asset discovery"| node_search
node_assets -->|"persists asset records"| node_db
node_projects -->|"persists project data"| node_db
node_comments -->|"persists review data"| node_db
node_access -->|"reads access data"| node_db
node_metadata -->|"persists field values"| node_db
node_kanban -->|"persists tasks"| node_db
node_sharing -->|"persists shares"| node_db

click node_web "https://github.com/shumaione/shumai/blob/main/packages/webui/index.tsx"
click node_browser "https://github.com/shumaione/shumai/blob/main/packages/webui/components/file-system-manager.tsx"
click node_publicshare "https://github.com/shumaione/shumai/blob/main/packages/webui/components/public-share-manager.tsx"
click node_plugin "https://github.com/shumaione/shumai/blob/main/apps/premiere-uxp/src/App.tsx"
click node_cli "https://github.com/shumaione/shumai/blob/main/apps/cli/src/index.ts"
click node_api "https://github.com/shumaione/shumai/blob/main/packages/api/src/index.ts"
click node_projects "https://github.com/shumaione/shumai/blob/main/packages/core/src/project/project.ts"
click node_assets "https://github.com/shumaione/shumai/blob/main/packages/core/src/asset/asset.ts"
click node_comments "https://github.com/shumaione/shumai/blob/main/packages/core/src/chat/chat.ts"
click node_sharing "https://github.com/shumaione/shumai/blob/main/packages/core/src/share/share.ts"
click node_access "https://github.com/shumaione/shumai/blob/main/packages/core/src/authz/authz.ts"
click node_metadata "https://github.com/shumaione/shumai/blob/main/packages/core/src/metadata/metadata.ts"
click node_kanban "https://github.com/shumaione/shumai/blob/main/packages/core/src/kanban/kanban.ts"
click node_search "https://github.com/shumaione/shumai/blob/main/packages/core/src/search/search.ts"
click node_db "https://github.com/shumaione/shumai/blob/main/packages/db/src/index.ts"
click node_storage "https://github.com/shumaione/shumai/blob/main/packages/core/src/s3/s3.ts"
click node_transcode "https://github.com/shumaione/shumai/blob/main/packages/transcode/src/workflows/transcode.ts"
click node_preview "https://github.com/shumaione/shumai/blob/main/packages/core/src/s3/preview-converter.ts"
click node_agent "https://github.com/shumaione/shumai/blob/main/packages/agent/src/workflows/agent-chat.ts"
click node_agenttools "https://github.com/shumaione/shumai/blob/main/packages/agent/src/tools/list-assets.ts"
click node_mcp "https://github.com/shumaione/shumai/blob/main/packages/core/src/mcp/mcp-server-manager.ts"
click node_sandbox "https://github.com/shumaione/shumai/blob/main/packages/core/src/sandbox/sandbox-service.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_web,node_browser,node_publicshare,node_plugin,node_cli toneBlue
class node_api,node_projects,node_assets,node_comments,node_sharing,node_access,node_metadata,node_kanban,node_search,node_db toneAmber
class node_storage,node_transcode,node_preview toneMint
class node_agent,node_agenttools,node_mcp,node_sandbox toneRose
class node_premiere,node_s3service,node_temporal,node_gotenberg,node_mcpservers,node_member toneIndigo
```

## Components

### User experiences

- [Web application](https://github.com/shumaione/shumai/blob/main/packages/webui/index.tsx): `packages/webui/index.tsx`
- [File browser and review](https://github.com/shumaione/shumai/blob/main/packages/webui/components/file-system-manager.tsx): `packages/webui/components/file-system-manager.tsx`
- [Public share viewer](https://github.com/shumaione/shumai/blob/main/packages/webui/components/public-share-manager.tsx): `packages/webui/components/public-share-manager.tsx`
- [Premiere Pro plugin](https://github.com/shumaione/shumai/blob/main/apps/premiere-uxp/src/App.tsx): `apps/premiere-uxp/src/App.tsx`
- [CLI](https://github.com/shumaione/shumai/blob/main/apps/cli/src/index.ts): `apps/cli/src/index.ts`

### Collaboration domain

- [HTTP API](https://github.com/shumaione/shumai/blob/main/packages/api/src/index.ts): `packages/api/src/index.ts`
- [Projects and teams](https://github.com/shumaione/shumai/blob/main/packages/core/src/project/project.ts): `packages/core/src/project/project.ts`
- [Assets and folders](https://github.com/shumaione/shumai/blob/main/packages/core/src/asset/asset.ts): `packages/core/src/asset/asset.ts`
- [Comments and annotations](https://github.com/shumaione/shumai/blob/main/packages/core/src/chat/chat.ts): `packages/core/src/chat/chat.ts`
- [Shares and collections](https://github.com/shumaione/shumai/blob/main/packages/core/src/share/share.ts): `packages/core/src/share/share.ts`
- [Access control](https://github.com/shumaione/shumai/blob/main/packages/core/src/authz/authz.ts): `packages/core/src/authz/authz.ts`
- [Custom metadata](https://github.com/shumaione/shumai/blob/main/packages/core/src/metadata/metadata.ts): `packages/core/src/metadata/metadata.ts`
- [Kanban tasks](https://github.com/shumaione/shumai/blob/main/packages/core/src/kanban/kanban.ts): `packages/core/src/kanban/kanban.ts`
- [Semantic search](https://github.com/shumaione/shumai/blob/main/packages/core/src/search/search.ts): `packages/core/src/search/search.ts`
- [Application database](https://github.com/shumaione/shumai/blob/main/packages/db/src/index.ts): `packages/db/src/index.ts`

### Media handling

- [Asset storage](https://github.com/shumaione/shumai/blob/main/packages/core/src/s3/s3.ts): `packages/core/src/s3/s3.ts`
- [Media transcode workflows](https://github.com/shumaione/shumai/blob/main/packages/transcode/src/workflows/transcode.ts): `packages/transcode/src/workflows/transcode.ts`
- [Preview conversion](https://github.com/shumaione/shumai/blob/main/packages/core/src/s3/preview-converter.ts): `packages/core/src/s3/preview-converter.ts`

### AI capabilities

- [Agent workflows](https://github.com/shumaione/shumai/blob/main/packages/agent/src/workflows/agent-chat.ts): `packages/agent/src/workflows/agent-chat.ts`
- [Agent tools](https://github.com/shumaione/shumai/blob/main/packages/agent/src/tools/list-assets.ts): `packages/agent/src/tools/list-assets.ts`
- [MCP connections](https://github.com/shumaione/shumai/blob/main/packages/core/src/mcp/mcp-server-manager.ts): `packages/core/src/mcp/mcp-server-manager.ts`
- [Sandbox execution](https://github.com/shumaione/shumai/blob/main/packages/core/src/sandbox/sandbox-service.ts): `packages/core/src/sandbox/sandbox-service.ts`

### External integrations

- **Premiere Pro**
- **S3-compatible storage**
- **Temporal workers**
- **Gotenberg**
- **Remote MCP servers**

### Other components

- **Creative team member**

## Connections

- Creative team member → Web application: uses
- Web application → File browser and review: opens media
- File browser and review → HTTP API: requests files
- Public share viewer → HTTP API: fetches shared media
- Premiere Pro plugin → Premiere Pro: reads sequences
- Premiere Pro plugin → HTTP API: fetches comments
- CLI → HTTP API: manages assets
- HTTP API → Projects and teams: serves project operations
- HTTP API → Assets and folders: serves asset operations
- HTTP API → Shares and collections: serves share operations
- HTTP API → Comments and annotations: serves review operations
- HTTP API → Kanban tasks: serves task operations
- HTTP API → Custom metadata: serves metadata operations
- HTTP API → Semantic search: serves search requests
- Assets and folders → Asset storage: stores media
- Asset storage → S3-compatible storage: reads and writes
- Media transcode workflows → Temporal workers: runs workflows
- Media transcode workflows → Asset storage: processes media
- Preview conversion → Gotenberg: converts documents
- Agent workflows → Agent tools: dispatches tools
- Agent workflows → MCP connections: uses configured tools
- MCP connections → Remote MCP servers: connects to
- Agent workflows → Sandbox execution: runs scripts
- Agent workflows → Semantic search: supports asset discovery
- Assets and folders → Application database: persists asset records
- Projects and teams → Application database: persists project data
- Comments and annotations → Application database: persists review data
- Access control → Application database: reads access data
- Custom metadata → Application database: persists field values
- Kanban tasks → Application database: persists tasks
- Shares and collections → Application database: persists shares