# awakelab-dev/awk-motion architecture

> Architecture diagram of the GitHub repository awakelab-dev/awk-motion, 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/awakelab-dev/awk-motion
- Repository: https://github.com/awakelab-dev/awk-motion

## Overview

Wilox Motion is a web app and API for turning text into narrated, illustrated motion videos, then managing and delivering them. The principal workflow is text submission, voice and word timing, storyboard and timeline planning, keyframe approval, clip generation, post-processing, and final rendering. Separate branches cover theme creation, projects and access, imports, reviews and sharing, and exports/publications. The README documents these product capabilities; edges are limited to relationships shown in the supplied excerpts, source index, or README, so some unsampled subsystem links are omitted.

Main entry points: [`apps/api/src/pipeline/pipeline.service.ts`](https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/pipeline/pipeline.service.ts) (Generation pipeline), [`apps/api/src/generations/run-store.ts`](https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/generations/run-store.ts) (Run persistence), [`apps/api/src/themes/themes.controller.ts`](https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/themes/themes.controller.ts) (Theme studio API), [`apps/api/src/access/access.service.ts`](https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/access/access.service.ts) (Access control)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_creation["Video creation"]
  node_generation_api["Generation API"]
  node_pipeline["Generation pipeline"]
  node_prompts["Storyboard prompts<br/>[index.ts]"]
  node_timeline["Timeline planner<br/>[timeline.ts]"]
  node_providers["AI providers<br/>[ports.ts]"]
  node_media["Media processing<br/>[ffmpeg.ts]"]
end

subgraph group_themes["Themes and assets"]
  node_themes_api["Theme studio API"]
  node_theme_store[("Theme store<br/>[theme-store.ts]")]
  node_studio_service["Studio generation<br/>[studio.service.ts]"]
end

subgraph group_workspace["Projects and access"]
  node_projects["Project management"]
  node_access["Access control<br/>[access.service.ts]"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_imports["Content import"]
end

subgraph group_delivery["Review and delivery"]
  node_review["Video review<br/>[review.service.ts]"]
  node_sharing["Project sharing"]
  node_delivery_api["Exports and delivery"]
  node_publications["Publications"]
end

subgraph group_platform["Runtime platform"]
  node_run_store[("Run persistence<br/>[run-store.ts]")]
  node_media_storage[("Media storage<br/>[media.service.ts]")]
  node_database[("PostgreSQL<br/>[index.ts]")]
end

node_user(("Creator"))
node_web["Web app<br/>[App.tsx]"]
node_external_ai{{"AI services"}}

node_user -->|"submits text"| node_web
node_web -.->|"requests generation"| node_generation_api
node_generation_api -->|"starts run"| node_pipeline
node_pipeline -->|"builds prompts"| node_prompts
node_pipeline -->|"plans shots"| node_timeline
node_pipeline -->|"uses providers"| node_providers
node_providers -.->|"calls models"| node_external_ai
node_pipeline -->|"encodes media"| node_media
node_pipeline -->|"updates run"| node_run_store
node_pipeline -.->|"uses selected theme"| node_themes_api
node_themes_api -->|"manages themes"| node_theme_store
node_themes_api -->|"generates proposals"| node_studio_service
node_theme_store -->|"persists themes"| node_database
node_run_store -->|"persists run state"| node_database
node_run_store -->|"stores run files"| node_media_storage
node_projects -->|"checks permissions"| node_access
node_projects -->|"loads generations"| node_run_store
node_auth -.->|"identifies user"| node_access
node_imports -->|"checks permissions"| node_access
node_review -->|"reads media"| node_media_storage
node_sharing -->|"serves review links"| node_review
node_delivery_api -->|"reads media"| node_media_storage
node_publications -->|"uses delivery"| node_delivery_api

click node_web "https://github.com/awakelab-dev/awk-motion/blob/main/apps/web/src/App.tsx"
click node_generation_api "https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/generations/generations.controller.ts"
click node_pipeline "https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/pipeline/pipeline.service.ts"
click node_prompts "https://github.com/awakelab-dev/awk-motion/blob/main/packages/prompts/src/index.ts"
click node_timeline "https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/pipeline/timeline.ts"
click node_providers "https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/providers/ports.ts"
click node_media "https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/media/ffmpeg.ts"
click node_themes_api "https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/themes/themes.controller.ts"
click node_theme_store "https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/themes/theme-store.ts"
click node_studio_service "https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/themes/studio.service.ts"
click node_projects "https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/projects/projects.controller.ts"
click node_access "https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/access/access.service.ts"
click node_auth "https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/auth/auth.service.ts"
click node_imports "https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/imports/imports.controller.ts"
click node_run_store "https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/generations/run-store.ts"
click node_media_storage "https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/storage/media.service.ts"
click node_database "https://github.com/awakelab-dev/awk-motion/blob/main/packages/db/src/index.ts"
click node_review "https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/review/review.service.ts"
click node_sharing "https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/share/project-share.service.ts"
click node_delivery_api "https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/delivery/delivery.service.ts"
click node_publications "https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/publications/publications.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_generation_api,node_pipeline,node_prompts,node_timeline,node_providers,node_media toneBlue
class node_themes_api,node_theme_store,node_studio_service toneAmber
class node_projects,node_access,node_auth,node_imports toneMint
class node_review,node_sharing,node_delivery_api,node_publications toneRose
class node_run_store,node_media_storage,node_database,node_user,node_external_ai toneIndigo
class node_web toneTeal
```

## Components

### Video creation

- [Generation API](https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/generations/generations.controller.ts): `apps/api/src/generations/generations.controller.ts`
- [Generation pipeline](https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/pipeline/pipeline.service.ts): `apps/api/src/pipeline/pipeline.service.ts`
- [Storyboard prompts](https://github.com/awakelab-dev/awk-motion/blob/main/packages/prompts/src/index.ts): `packages/prompts/src/index.ts`
- [Timeline planner](https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/pipeline/timeline.ts): `apps/api/src/pipeline/timeline.ts`
- [AI providers](https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/providers/ports.ts): `apps/api/src/providers/ports.ts`
- [Media processing](https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/media/ffmpeg.ts): `apps/api/src/media/ffmpeg.ts`

### Themes and assets

- [Theme studio API](https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/themes/themes.controller.ts): `apps/api/src/themes/themes.controller.ts`
- [Theme store](https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/themes/theme-store.ts): `apps/api/src/themes/theme-store.ts`
- [Studio generation](https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/themes/studio.service.ts): `apps/api/src/themes/studio.service.ts`

### Projects and access

- [Project management](https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/projects/projects.controller.ts): `apps/api/src/projects/projects.controller.ts`
- [Access control](https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/access/access.service.ts): `apps/api/src/access/access.service.ts`
- [Authentication](https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/auth/auth.service.ts): `apps/api/src/auth/auth.service.ts`
- [Content import](https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/imports/imports.controller.ts): `apps/api/src/imports/imports.controller.ts`

### Review and delivery

- [Video review](https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/review/review.service.ts): `apps/api/src/review/review.service.ts`
- [Project sharing](https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/share/project-share.service.ts): `apps/api/src/share/project-share.service.ts`
- [Exports and delivery](https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/delivery/delivery.service.ts): `apps/api/src/delivery/delivery.service.ts`
- [Publications](https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/publications/publications.service.ts): `apps/api/src/publications/publications.service.ts`

### Runtime platform

- [Run persistence](https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/generations/run-store.ts): `apps/api/src/generations/run-store.ts`
- [Media storage](https://github.com/awakelab-dev/awk-motion/blob/main/apps/api/src/storage/media.service.ts): `apps/api/src/storage/media.service.ts`
- [PostgreSQL](https://github.com/awakelab-dev/awk-motion/blob/main/packages/db/src/index.ts): `packages/db/src/index.ts`

### Other components

- **Creator**
- [Web app](https://github.com/awakelab-dev/awk-motion/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- **AI services**

## Connections

- Creator → Web app: submits text
- Web app → Generation API: requests generation
- Generation API → Generation pipeline: starts run (evidence: `apps/api/src/generations/generations.controller.ts`)
- Generation pipeline → Storyboard prompts: builds prompts (evidence: `apps/api/src/pipeline/pipeline.service.ts`)
- Generation pipeline → Timeline planner: plans shots (evidence: `apps/api/src/pipeline/pipeline.service.ts`)
- Generation pipeline → AI providers: uses providers (evidence: `apps/api/src/pipeline/pipeline.service.ts`)
- AI providers → AI services: calls models
- Generation pipeline → Media processing: encodes media (evidence: `apps/api/src/pipeline/pipeline.service.ts`)
- Generation pipeline → Run persistence: updates run (evidence: `apps/api/src/pipeline/pipeline.service.ts`)
- Generation pipeline → Theme studio API: uses selected theme
- Theme studio API → Theme store: manages themes (evidence: `apps/api/src/themes/themes.controller.ts`)
- Theme studio API → Studio generation: generates proposals (evidence: `apps/api/src/themes/themes.controller.ts`)
- Theme store → PostgreSQL: persists themes (evidence: `apps/api/src/themes/theme-store.ts`)
- Run persistence → PostgreSQL: persists run state (evidence: `apps/api/src/generations/run-store.ts`)
- Run persistence → Media storage: stores run files (evidence: `apps/api/src/generations/run-store.ts`)
- Project management → Access control: checks permissions (evidence: `apps/api/src/projects/projects.controller.ts`)
- Project management → Run persistence: loads generations (evidence: `apps/api/src/projects/projects.controller.ts`)
- Authentication → Access control: identifies user
- Content import → Access control: checks permissions (evidence: `apps/api/src/imports/imports.controller.ts`)
- Video review → Media storage: reads media (evidence: `apps/api/src/review/review.service.ts`)
- Project sharing → Video review: serves review links (evidence: `apps/api/src/share/project-share.controller.ts`)
- Exports and delivery → Media storage: reads media (evidence: `apps/api/src/delivery/delivery.service.ts`)
- Publications → Exports and delivery: uses delivery (evidence: `apps/api/src/publications/publications.controller.ts`)
