# sausi-7/carousels architecture

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

- Interactive diagram: https://gitdiagram.com/sausi-7/carousels
- Repository: https://github.com/sausi-7/carousels

## Overview

This repository subtree is the carousel rendering engine: a validated slide plan is rendered as animated video, lossless stills, or both. The graph preserves the documented plan gate and output choices, then shows the sampled React composition, template, primitive, and theme layers. Template coverage is summarized by subsystem; sampled source references support the internal rendering links. The README documents the gate and export behavior, but the render scripts were not excerpted, so their internal implementation is not inferred.

Main entry points: [`skills/carousels/engine/src/templates/SpotlightTemplate.tsx`](https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/templates/SpotlightTemplate.tsx) (Spotlight template), [`skills/carousels/engine/src/templates/StatTemplate.tsx`](https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/templates/StatTemplate.tsx) (Stat template), [`skills/carousels/engine/src/theme/motion.ts`](https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/theme/motion.ts) (Motion grammar), [`skills/carousels/engine/src/primitives/Region.tsx`](https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/primitives/Region.tsx) (Grid regions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_planning["Plan gate and export"]
  node_plan["Slide plan"]
  node_gate["Plan validation<br/>[validate-plan.mjs]"]
  node_render["Render and export<br/>[render.mjs]"]
  node_media["Video / stills"]
end

subgraph group_composition["Slide composition"]
  node_root["Remotion root<br/>[Root.tsx]"]
  node_slidecomp["Slide composition"]
end

subgraph group_visuals["Templates and primitives"]
  node_templates["Slide role templates"]
  node_spotlight["Spotlight template"]
  node_stat["Stat template<br/>[StatTemplate.tsx]"]
  node_canvas["Canvas surface<br/>[Canvas.tsx]"]
  node_region["Grid regions<br/>[Region.tsx]"]
  node_block["Color planes<br/>[Block.tsx]"]
  node_type["Typography<br/>[Type.tsx]"]
  node_chrome["Slide chrome<br/>[Chrome.tsx]"]
  node_imageplane["Image planes<br/>[ImagePlane.tsx]"]
  node_marks["Geometric marks<br/>[Marks.tsx]"]
end

subgraph group_theme["Theme and layout"]
  node_archetypes["Theme archetypes<br/>[archetypes.ts]"]
  node_resolve["Theme resolution<br/>[resolveTheme.ts]"]
  node_layout["Cut layouts<br/>[layout.ts]"]
  node_motion["Motion grammar<br/>[motion.ts]"]
  node_fit["Text fitting<br/>[fit.ts]"]
  node_fonts["Font registry<br/>[fontRegistry.ts]"]
  node_contrast["Contrast utilities<br/>[contrast.ts]"]
  node_scale["Canvas scale<br/>[scale.ts]"]
end

node_author(("Carousel requester"))

node_author -->|"supplies topic"| node_plan
node_plan -->|"checks plan"| node_gate
node_gate -->|"gates rendering"| node_render
node_render -->|"exports format"| node_media
node_root -->|"registers composition"| node_slidecomp
node_slidecomp -->|"routes slide roles"| node_templates
node_slidecomp -->|"resolves theme"| node_resolve
node_spotlight -->|"renders with"| node_canvas
node_spotlight -->|"positions with"| node_region
node_spotlight -->|"renders planes"| node_block
node_spotlight -->|"renders type"| node_type
node_spotlight -->|"renders chrome"| node_chrome
node_spotlight -->|"renders imagery"| node_imageplane
node_spotlight -->|"renders marks"| node_marks
node_stat -->|"renders with"| node_canvas
node_stat -->|"positions with"| node_region
node_stat -->|"renders planes"| node_block
node_stat -->|"renders type"| node_type
node_stat -->|"renders chrome"| node_chrome
node_stat -->|"renders marks"| node_marks
node_resolve -->|"loads defaults"| node_archetypes
node_resolve -->|"looks up fonts"| node_fonts
node_resolve -->|"checks contrast"| node_contrast
node_spotlight -->|"uses layout"| node_layout
node_spotlight -->|"uses motion"| node_motion
node_stat -->|"uses layout"| node_layout
node_stat -->|"uses motion"| node_motion
node_type -->|"measures text"| node_fit
node_type -->|"animates text"| node_motion
node_canvas -->|"provides direction"| node_region
node_region -->|"maps grid"| node_scale
node_block -->|"places plane"| node_region
node_block -->|"reveals plane"| node_motion
node_block -->|"checks edge"| node_contrast
node_imageplane -->|"places image"| node_region
node_imageplane -->|"animates image"| node_motion
node_chrome -->|"uses surfaces"| node_type
node_chrome -->|"animates chrome"| node_motion
node_marks -->|"animates marks"| node_motion
node_marks -->|"uses alpha"| node_contrast

click node_gate "https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/scripts/validate-plan.mjs"
click node_render "https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/scripts/render.mjs"
click node_root "https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/Root.tsx"
click node_slidecomp "https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/compositions/SlideComposition.tsx"
click node_templates "https://github.com/sausi-7/carousels/tree/main/skills/carousels/engine/src/templates"
click node_spotlight "https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/templates/SpotlightTemplate.tsx"
click node_stat "https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/templates/StatTemplate.tsx"
click node_canvas "https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/primitives/Canvas.tsx"
click node_region "https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/primitives/Region.tsx"
click node_block "https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/primitives/Block.tsx"
click node_type "https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/primitives/Type.tsx"
click node_chrome "https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/primitives/Chrome.tsx"
click node_imageplane "https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/primitives/ImagePlane.tsx"
click node_marks "https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/primitives/Marks.tsx"
click node_archetypes "https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/theme/archetypes.ts"
click node_resolve "https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/theme/resolveTheme.ts"
click node_layout "https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/theme/layout.ts"
click node_motion "https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/theme/motion.ts"
click node_fit "https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/theme/fit.ts"
click node_fonts "https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/theme/fontRegistry.ts"
click node_contrast "https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/theme/contrast.ts"
click node_scale "https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/theme/scale.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_plan,node_gate,node_render,node_media toneBlue
class node_root,node_slidecomp toneAmber
class node_templates,node_spotlight,node_stat,node_canvas,node_region,node_block,node_type,node_chrome,node_imageplane,node_marks,node_author toneMint
class node_archetypes,node_resolve,node_layout,node_motion,node_fit,node_fonts,node_contrast,node_scale toneRose
```

## Components

### Plan gate and export

- **Slide plan**
- [Plan validation](https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/scripts/validate-plan.mjs): `skills/carousels/engine/scripts/validate-plan.mjs`
- [Render and export](https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/scripts/render.mjs): `skills/carousels/engine/scripts/render.mjs`
- **Video / stills**

### Slide composition

- [Remotion root](https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/Root.tsx): `skills/carousels/engine/src/Root.tsx`
- [Slide composition](https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/compositions/SlideComposition.tsx): `skills/carousels/engine/src/compositions/SlideComposition.tsx`

### Templates and primitives

- [Slide role templates](https://github.com/sausi-7/carousels/tree/main/skills/carousels/engine/src/templates): `skills/carousels/engine/src/templates`
- [Spotlight template](https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/templates/SpotlightTemplate.tsx): `skills/carousels/engine/src/templates/SpotlightTemplate.tsx`
- [Stat template](https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/templates/StatTemplate.tsx): `skills/carousels/engine/src/templates/StatTemplate.tsx`
- [Canvas surface](https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/primitives/Canvas.tsx): `skills/carousels/engine/src/primitives/Canvas.tsx`
- [Grid regions](https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/primitives/Region.tsx): `skills/carousels/engine/src/primitives/Region.tsx`
- [Color planes](https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/primitives/Block.tsx): `skills/carousels/engine/src/primitives/Block.tsx`
- [Typography](https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/primitives/Type.tsx): `skills/carousels/engine/src/primitives/Type.tsx`
- [Slide chrome](https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/primitives/Chrome.tsx): `skills/carousels/engine/src/primitives/Chrome.tsx`
- [Image planes](https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/primitives/ImagePlane.tsx): `skills/carousels/engine/src/primitives/ImagePlane.tsx`
- [Geometric marks](https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/primitives/Marks.tsx): `skills/carousels/engine/src/primitives/Marks.tsx`

### Theme and layout

- [Theme archetypes](https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/theme/archetypes.ts): `skills/carousels/engine/src/theme/archetypes.ts`
- [Theme resolution](https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/theme/resolveTheme.ts): `skills/carousels/engine/src/theme/resolveTheme.ts`
- [Cut layouts](https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/theme/layout.ts): `skills/carousels/engine/src/theme/layout.ts`
- [Motion grammar](https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/theme/motion.ts): `skills/carousels/engine/src/theme/motion.ts`
- [Text fitting](https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/theme/fit.ts): `skills/carousels/engine/src/theme/fit.ts`
- [Font registry](https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/theme/fontRegistry.ts): `skills/carousels/engine/src/theme/fontRegistry.ts`
- [Contrast utilities](https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/theme/contrast.ts): `skills/carousels/engine/src/theme/contrast.ts`
- [Canvas scale](https://github.com/sausi-7/carousels/blob/main/skills/carousels/engine/src/theme/scale.ts): `skills/carousels/engine/src/theme/scale.ts`

### Other components

- **Carousel requester**

## Connections

- Carousel requester → Slide plan: supplies topic (evidence: `README.md`)
- Slide plan → Plan validation: checks plan (evidence: `README.md`)
- Plan validation → Render and export: gates rendering (evidence: `README.md`)
- Render and export → Video / stills: exports format (evidence: `README.md`)
- Remotion root → Slide composition: registers composition (evidence: `skills/carousels/engine/src/Root.tsx`)
- Slide composition → Slide role templates: routes slide roles (evidence: `skills/carousels/engine/src/compositions/SlideComposition.tsx`)
- Slide composition → Theme resolution: resolves theme (evidence: `skills/carousels/engine/src/compositions/SlideComposition.tsx`)
- Spotlight template → Canvas surface: renders with (evidence: `skills/carousels/engine/src/templates/SpotlightTemplate.tsx`)
- Spotlight template → Grid regions: positions with (evidence: `skills/carousels/engine/src/templates/SpotlightTemplate.tsx`)
- Spotlight template → Color planes: renders planes (evidence: `skills/carousels/engine/src/templates/SpotlightTemplate.tsx`)
- Spotlight template → Typography: renders type (evidence: `skills/carousels/engine/src/templates/SpotlightTemplate.tsx`)
- Spotlight template → Slide chrome: renders chrome (evidence: `skills/carousels/engine/src/templates/SpotlightTemplate.tsx`)
- Spotlight template → Image planes: renders imagery (evidence: `skills/carousels/engine/src/templates/SpotlightTemplate.tsx`)
- Spotlight template → Geometric marks: renders marks (evidence: `skills/carousels/engine/src/templates/SpotlightTemplate.tsx`)
- Stat template → Canvas surface: renders with (evidence: `skills/carousels/engine/src/templates/StatTemplate.tsx`)
- Stat template → Grid regions: positions with (evidence: `skills/carousels/engine/src/templates/StatTemplate.tsx`)
- Stat template → Color planes: renders planes (evidence: `skills/carousels/engine/src/templates/StatTemplate.tsx`)
- Stat template → Typography: renders type (evidence: `skills/carousels/engine/src/templates/StatTemplate.tsx`)
- Stat template → Slide chrome: renders chrome (evidence: `skills/carousels/engine/src/templates/StatTemplate.tsx`)
- Stat template → Geometric marks: renders marks (evidence: `skills/carousels/engine/src/templates/StatTemplate.tsx`)
- Theme resolution → Theme archetypes: loads defaults (evidence: `skills/carousels/engine/src/theme/resolveTheme.ts`)
- Theme resolution → Font registry: looks up fonts (evidence: `skills/carousels/engine/src/theme/resolveTheme.ts`)
- Theme resolution → Contrast utilities: checks contrast (evidence: `skills/carousels/engine/src/theme/resolveTheme.ts`)
- Spotlight template → Cut layouts: uses layout (evidence: `skills/carousels/engine/src/templates/SpotlightTemplate.tsx`)
- Spotlight template → Motion grammar: uses motion (evidence: `skills/carousels/engine/src/templates/SpotlightTemplate.tsx`)
- Stat template → Cut layouts: uses layout (evidence: `skills/carousels/engine/src/templates/StatTemplate.tsx`)
- Stat template → Motion grammar: uses motion (evidence: `skills/carousels/engine/src/templates/StatTemplate.tsx`)
- Typography → Text fitting: measures text (evidence: `skills/carousels/engine/src/primitives/Type.tsx`)
- Typography → Motion grammar: animates text (evidence: `skills/carousels/engine/src/primitives/Type.tsx`)
- Canvas surface → Grid regions: provides direction (evidence: `skills/carousels/engine/src/primitives/Canvas.tsx`)
- Grid regions → Canvas scale: maps grid (evidence: `skills/carousels/engine/src/primitives/Region.tsx`)
- Color planes → Grid regions: places plane (evidence: `skills/carousels/engine/src/primitives/Block.tsx`)
- Color planes → Motion grammar: reveals plane (evidence: `skills/carousels/engine/src/primitives/Block.tsx`)
- Color planes → Contrast utilities: checks edge (evidence: `skills/carousels/engine/src/primitives/Block.tsx`)
- Image planes → Grid regions: places image (evidence: `skills/carousels/engine/src/primitives/ImagePlane.tsx`)
- Image planes → Motion grammar: animates image (evidence: `skills/carousels/engine/src/primitives/ImagePlane.tsx`)
- Slide chrome → Typography: uses surfaces (evidence: `skills/carousels/engine/src/primitives/Chrome.tsx`)
- Slide chrome → Motion grammar: animates chrome (evidence: `skills/carousels/engine/src/primitives/Chrome.tsx`)
- Geometric marks → Motion grammar: animates marks (evidence: `skills/carousels/engine/src/primitives/Marks.tsx`)
- Geometric marks → Contrast utilities: uses alpha (evidence: `skills/carousels/engine/src/primitives/Marks.tsx`)
