# alfredoperez/toku architecture

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

- Interactive diagram: https://gitdiagram.com/alfredoperez/toku
- Repository: https://github.com/alfredoperez/toku

## Overview

Toku is a monorepo of reusable content engines and copy-in kits, a CLI for adopting them, and read-only demo applications. The main consumer workflow is to scaffold a deck project, select registry content, copy its dependency closure into the project, then render slides with the deck engine and a theme. The README documents the broader video, HTML-doc, and motion capabilities; their internals are not fully sampled, so those branches are represented at package level. The skills plugin is described but its source is absent from the supplied tree.

Main entry points: [`packages/cli/src/cli.ts`](https://github.com/alfredoperez/toku/blob/main/packages/cli/src/cli.ts) (butai CLI), [`packages/cli/src/commands/add.ts`](https://github.com/alfredoperez/toku/blob/main/packages/cli/src/commands/add.ts) (Registry installer), [`packages/deck/src/SlideEngine.tsx`](https://github.com/alfredoperez/toku/blob/main/packages/deck/src/SlideEngine.tsx) (Slide engine), [`apps/studio/src`](https://github.com/alfredoperez/toku/tree/main/apps/studio/src) (Read-only studio)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_adoption["Project adoption"]
  node_cli["butai CLI<br/>[cli.ts]"]
  node_cli_init["Project scaffold<br/>[init.ts]"]
  node_cli_add["Registry installer<br/>[add.ts]"]
  node_cli_diff["Copy comparison<br/>[diff.ts]"]
  node_registry["Registry resolver<br/>[registry.ts]"]
  node_transform["Copy transforms<br/>[transform.ts]"]
end

subgraph group_presentation["Presentation runtime"]
  node_deck_engine["Slide engine<br/>[SlideEngine.tsx]"]
  node_slide_state["Slide navigation<br/>[useSlides.ts]"]
end

subgraph group_content_kits["Content kits"]
  node_slide_kit["Slide archetypes"]
  node_scene_kit["Video scenes<br/>[storyboard.ts]"]
  node_docs_kit["HTML doc patterns"]
  node_motion_kit["Motion recipes"]
end

subgraph group_exploration["Demo surfaces"]
  node_studio["Read-only studio"]
  node_playground["Deck playground<br/>[App.tsx]"]
end

subgraph group_shared["Shared substrate"]
  node_patterns["Design patterns"]
  node_themes["Theme tokens<br/>[index.ts]"]
  node_credits["Credit ledger"]
end

node_consumer(("Project author"))

node_consumer -->|"runs commands"| node_cli
node_cli -->|"dispatches init"| node_cli_init
node_cli -->|"dispatches add"| node_cli_add
node_cli -.->|"dispatches diff"| node_cli_diff
node_cli_add -->|"resolves items"| node_registry
node_cli_add -->|"rewrites copies"| node_transform
node_consumer -->|"selects archetypes"| node_slide_kit
node_cli_add -->|"copies registry files"| node_slide_kit
node_consumer -->|"authors deck"| node_deck_engine
node_deck_engine -->|"uses navigation"| node_slide_state
node_deck_engine -->|"renders with theme"| node_themes
node_consumer -->|"authors video"| node_scene_kit
node_consumer -->|"authors HTML docs"| node_docs_kit
node_consumer -->|"uses recipes"| node_motion_kit
node_scene_kit -->|"uses shared types"| node_patterns
node_docs_kit -->|"extracts themes"| node_patterns
node_studio -.->|"explores storyboards"| node_scene_kit
node_studio -->|"explores patterns"| node_patterns
node_studio -.->|"explores tokens"| node_themes
node_playground -->|"renders demo deck"| node_deck_engine
node_playground -->|"browses archetypes"| node_slide_kit

click node_cli "https://github.com/alfredoperez/toku/blob/main/packages/cli/src/cli.ts"
click node_cli_init "https://github.com/alfredoperez/toku/blob/main/packages/cli/src/commands/init.ts"
click node_cli_add "https://github.com/alfredoperez/toku/blob/main/packages/cli/src/commands/add.ts"
click node_cli_diff "https://github.com/alfredoperez/toku/blob/main/packages/cli/src/commands/diff.ts"
click node_registry "https://github.com/alfredoperez/toku/blob/main/packages/cli/src/registry.ts"
click node_transform "https://github.com/alfredoperez/toku/blob/main/packages/cli/src/transform.ts"
click node_deck_engine "https://github.com/alfredoperez/toku/blob/main/packages/deck/src/SlideEngine.tsx"
click node_slide_state "https://github.com/alfredoperez/toku/blob/main/packages/deck/src/useSlides.ts"
click node_slide_kit "https://github.com/alfredoperez/toku/tree/main/packages/slide-kit/src/slides"
click node_scene_kit "https://github.com/alfredoperez/toku/blob/main/packages/scene-kit/src/storyboard.ts"
click node_docs_kit "https://github.com/alfredoperez/toku/tree/main/packages/docs-kit/src"
click node_motion_kit "https://github.com/alfredoperez/toku/tree/main/packages/motion-kit/src/recipes"
click node_patterns "https://github.com/alfredoperez/toku/tree/main/packages/patterns/src"
click node_themes "https://github.com/alfredoperez/toku/blob/main/packages/themes/src/index.ts"
click node_credits "https://github.com/alfredoperez/toku/tree/main/packages/credits/src"
click node_studio "https://github.com/alfredoperez/toku/tree/main/apps/studio/src"
click node_playground "https://github.com/alfredoperez/toku/blob/main/apps/playground/src/App.tsx"

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_cli,node_cli_init,node_cli_add,node_cli_diff,node_registry,node_transform toneBlue
class node_deck_engine,node_slide_state toneAmber
class node_slide_kit,node_scene_kit,node_docs_kit,node_motion_kit toneMint
class node_studio,node_playground toneRose
class node_patterns,node_themes,node_credits,node_consumer toneIndigo
```

## Components

### Project adoption

- [butai CLI](https://github.com/alfredoperez/toku/blob/main/packages/cli/src/cli.ts): `packages/cli/src/cli.ts`
- [Project scaffold](https://github.com/alfredoperez/toku/blob/main/packages/cli/src/commands/init.ts): `packages/cli/src/commands/init.ts`
- [Registry installer](https://github.com/alfredoperez/toku/blob/main/packages/cli/src/commands/add.ts): `packages/cli/src/commands/add.ts`
- [Copy comparison](https://github.com/alfredoperez/toku/blob/main/packages/cli/src/commands/diff.ts): `packages/cli/src/commands/diff.ts`
- [Registry resolver](https://github.com/alfredoperez/toku/blob/main/packages/cli/src/registry.ts): `packages/cli/src/registry.ts`
- [Copy transforms](https://github.com/alfredoperez/toku/blob/main/packages/cli/src/transform.ts): `packages/cli/src/transform.ts`

### Presentation runtime

- [Slide engine](https://github.com/alfredoperez/toku/blob/main/packages/deck/src/SlideEngine.tsx): `packages/deck/src/SlideEngine.tsx`
- [Slide navigation](https://github.com/alfredoperez/toku/blob/main/packages/deck/src/useSlides.ts): `packages/deck/src/useSlides.ts`

### Content kits

- [Slide archetypes](https://github.com/alfredoperez/toku/tree/main/packages/slide-kit/src/slides): `packages/slide-kit/src/slides`
- [Video scenes](https://github.com/alfredoperez/toku/blob/main/packages/scene-kit/src/storyboard.ts): `packages/scene-kit/src/storyboard.ts`
- [HTML doc patterns](https://github.com/alfredoperez/toku/tree/main/packages/docs-kit/src): `packages/docs-kit/src`
- [Motion recipes](https://github.com/alfredoperez/toku/tree/main/packages/motion-kit/src/recipes): `packages/motion-kit/src/recipes`

### Demo surfaces

- [Read-only studio](https://github.com/alfredoperez/toku/tree/main/apps/studio/src): `apps/studio/src`
- [Deck playground](https://github.com/alfredoperez/toku/blob/main/apps/playground/src/App.tsx): `apps/playground/src/App.tsx`

### Shared substrate

- [Design patterns](https://github.com/alfredoperez/toku/tree/main/packages/patterns/src): `packages/patterns/src`
- [Theme tokens](https://github.com/alfredoperez/toku/blob/main/packages/themes/src/index.ts): `packages/themes/src/index.ts`
- [Credit ledger](https://github.com/alfredoperez/toku/tree/main/packages/credits/src): `packages/credits/src`

### Other components

- **Project author**

## Connections

- Project author → butai CLI: runs commands (evidence: `README.md`)
- butai CLI → Project scaffold: dispatches init (evidence: `README.md`)
- butai CLI → Registry installer: dispatches add (evidence: `packages/cli/src/commands/add.ts`)
- butai CLI → Copy comparison: dispatches diff
- Registry installer → Registry resolver: resolves items (evidence: `packages/cli/src/commands/add.ts`)
- Registry installer → Copy transforms: rewrites copies (evidence: `packages/cli/src/commands/add.ts`)
- Project author → Slide archetypes: selects archetypes (evidence: `README.md`)
- Registry installer → Slide archetypes: copies registry files (evidence: `README.md`)
- Project author → Slide engine: authors deck (evidence: `README.md`)
- Slide engine → Slide navigation: uses navigation (evidence: `packages/deck/src/SlideEngine.tsx`)
- Slide engine → Theme tokens: renders with theme (evidence: `README.md`)
- Project author → Video scenes: authors video (evidence: `README.md`)
- Project author → HTML doc patterns: authors HTML docs (evidence: `README.md`)
- Project author → Motion recipes: uses recipes (evidence: `README.md`)
- Video scenes → Design patterns: uses shared types (evidence: `packages/scene-kit/src/storyboard.ts`)
- HTML doc patterns → Design patterns: extracts themes (evidence: `packages/docs-kit/src/node/render-preview.ts`)
- Read-only studio → Video scenes: explores storyboards
- Read-only studio → Design patterns: explores patterns (evidence: `apps/studio/src/theme-studio/index.tsx`)
- Read-only studio → Theme tokens: explores tokens
- Deck playground → Slide engine: renders demo deck (evidence: `apps/playground/src/App.tsx`)
- Deck playground → Slide archetypes: browses archetypes