# peterjaberau/dev-kit architecture

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

- Interactive diagram: https://gitdiagram.com/peterjaberau/dev-kit
- Repository: https://github.com/peterjaberau/dev-kit

## Overview

1. **Repository shape**
   - This is a **pnpm monorepo** for a design-system / UI-kit ecosystem called `dev-kit`.
   - The repo is split into reusable packages, Storybook-driven documentation apps, and starter templates.

2. **Core product boundary: `packages/ui-kit/components`**
   - This is the main component library and the architectural center of the repo.
   - It contains reusable UI primitives and composites such as dialogs, menus, form controls, overlays, feedback, navigation, and utility components.
   - It also includes more specialized widgets like `draggable-panel` and `floating-panel`, which have their own submodules for constants, recipes, utils, and types.

3. **Experimental UI layer: `packages/ui-kit/experiments`**
   - This package holds non-core, likely unstable components such as `resizable-panel` and `toolbar`.
   - It is separated from the main component package, which suggests the repo distinguishes between supported UI primitives and exploratory features.

4. **Icon system: `packages/icons`**
   - Icons are managed as a dedicated package with SVG/component/type layers.
   - This gives the design system a separate asset pipeline for icon definitions and rendering, rather than treating icons as ad hoc assets inside components.

5. **Documentation/rendering support: `packages/documenter`**
   - This package provides components and types for “documenter” functionality, likely used to present component or token documentation in a structured way.
   - It sits between raw UI packages and the story/demo apps, acting as a documentation presentation layer.

6. **Primary showcase app: `apps/stories`**
   - This is a **Next.js + Storybook** application used to present examples and interactive stories.
   - Its content is organized by domain: charts, system components, tokens, site-level examples, and experiments.
   - The large number of example files indicates it serves as the main visual QA and documentation surface for the UI kit.

7. **Storybook runtime and theming**
   - The root `.storybook` directory provides shared Storybook configuration, decorators, preview setup, and theme handling.
   - It also includes “actors” support files, suggesting Storybook stories are wired into a state/model layer for interactive demos and controlled examples.
   - The theme decorator and preview setup are important boundaries: they wrap every story in the design-system context.

8. **Standalone demo app: `apps/ui-actors-stateless`**
   - This is a separate Next.js app, likely used to exercise the actor-based UI patterns without persistent app state.
   - Its minimal structure suggests it is a focused demo or verification surface rather than a full product app.

9. **Template layer: `templates/basic` and `templates/cloudflare`**
   - These are starter app templates for consumers of the kit.
   - Both include an `actors` architecture with model, hooks, selectors, shared data, and providers, plus standard app/layout/page entry points.
   - `templates/cloudflare` adds deployment-specific configuration (`open-next.config.ts`, `wrangler.jsonc`, `env.d.ts`), showing a deployment boundary for Cloudflare/OpenNext.

10. **Shared architecture pattern: actors/state modeling**
    - Multiple places in the repo use an `actors` directory with `model`, `machines`, `selectors`, `hooks`, and `provider`.
    - This indicates a deliberate application-state pattern built around actor/machine concepts, shared across templates and demos.
    - In diagram terms, this is a cross-cutting state layer that sits between UI components and app pages.

11. **How code flows through the repo**
    - The dependency direction is generally: **packages** provide reusable UI/docs/icon primitives, **apps/stories** and **templates** consume them, and **Storybook** demonstrates them in isolation.
    - The story/demo apps are the primary integration points where components, themes, and actor-based state models are composed together.

12. **Tooling and build surface**
    - The repo uses modern frontend tooling: **Next.js** for apps, **Storybook** for component exploration, **Vite** and **tsup** for build-related tasks, and TypeScript everywhere.
    - Root config files (`tsconfig`, ESLint, Prettier, workspace config) suggest a shared monorepo toolchain rather than isolated package tooling.

13. **What to draw as the main boundaries**
    - Draw three major areas: **reusable packages**, **interactive documentation/demo apps**, and **starter templates**.
    - Inside reusable packages, separate **core components**, **experimental components**, **icons**, and **documentation helpers**.
    - Inside apps, show **Storybook/app shell**, **theming/decorators**, and **actor/state providers** as the key composition layers.

Main entry points: [`apps/stories`](https://github.com/peterjaberau/dev-kit/tree/main/apps/stories) (Stories app), [`packages/ui-kit/components`](https://github.com/peterjaberau/dev-kit/tree/main/packages/ui-kit/components) (Core components), [`packages/documenter`](https://github.com/peterjaberau/dev-kit/tree/main/packages/documenter) (Documenter), [`.storybook/actors`](https://github.com/peterjaberau/dev-kit/blob/main/.storybook/actors) (Storybook actors)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_packages["Reusable packages"]
  node_node_ui_components["Core components<br/>design-system UI"]
  node_node_ui_floating["Floating panel<br/>panel component"]
  node_node_ui_draggable["Draggable panel<br/>panel component"]
  node_node_ui_experiments["Experimental UI<br/>unstable components"]
  node_node_icons["Icon system<br/>svg icon package"]
  node_node_documenter["Documenter<br/>docs components"]
end

subgraph group_group_apps["Interactive apps"]
  node_node_stories_shell["Stories app<br/>Next.js + Storybook"]
  node_node_stories_charts["Chart demos<br/>story examples"]
  node_node_stories_system["System demos<br/>story examples"]
  node_node_stories_tokens["Token demos<br/>story examples"]
  node_node_stories_components["Component demos<br/>story examples"]
  node_node_stories_experiments["Experiment demos<br/>story examples"]
  node_node_stories_site["Site demos<br/>story examples"]
  node_node_actors_stateless["Stateless demo<br/>Next.js demo"]
end

subgraph group_group_templates["Starter templates"]
  node_node_template_basic["Basic template<br/>starter app"]
  node_node_template_cloudflare["Cloudflare template<br/>starter app"]
end

subgraph group_group_runtime["Shared runtime"]
  node_node_storybook_shell["Storybook shell<br/>storybook runtime<br/>[.storybook]"]
  node_node_storybook_actors["Storybook actors<br/>state layer<br/>[actors]"]
  node_node_storybook_theme["Theme decorator<br/>storybook theming<br/>[withTheme.tsx]"]
end

subgraph group_group_tooling["Tooling"]
  node_node_toolchain["Monorepo tooling<br/>pnpm + TS"]
end

node_node_toolchain -->|"builds"| node_node_storybook_shell
node_node_toolchain -->|"builds"| node_node_stories_shell
node_node_toolchain -->|"builds"| node_node_actors_stateless
node_node_toolchain -->|"scaffolds"| node_node_template_basic
node_node_toolchain -->|"scaffolds"| node_node_template_cloudflare
node_node_storybook_shell -->|"wraps"| node_node_storybook_theme
node_node_storybook_shell -->|"loads"| node_node_storybook_actors
node_node_storybook_actors -.->|"feeds"| node_node_storybook_theme
node_node_stories_shell -->|"uses"| node_node_storybook_shell
node_node_stories_shell -->|"showcases"| node_node_ui_components
node_node_stories_shell -->|"showcases"| node_node_ui_experiments
node_node_stories_shell -->|"showcases"| node_node_icons
node_node_stories_shell -->|"showcases"| node_node_documenter
node_node_stories_shell -->|"contains"| node_node_stories_charts
node_node_stories_shell -->|"contains"| node_node_stories_system
node_node_stories_shell -->|"contains"| node_node_stories_tokens
node_node_stories_shell -->|"contains"| node_node_stories_components
node_node_stories_shell -->|"contains"| node_node_stories_experiments
node_node_stories_shell -->|"contains"| node_node_stories_site
node_node_stories_components -->|"drives"| node_node_ui_draggable
node_node_stories_components -->|"drives"| node_node_ui_floating
node_node_stories_experiments -->|"drives"| node_node_ui_experiments
node_node_stories_experiments -->|"drives"| node_node_documenter
node_node_template_basic -->|"consumes"| node_node_ui_components
node_node_template_basic -->|"consumes"| node_node_icons
node_node_template_basic -->|"uses"| node_node_storybook_actors
node_node_template_cloudflare -->|"consumes"| node_node_ui_components
node_node_template_cloudflare -->|"consumes"| node_node_icons
node_node_template_cloudflare -->|"uses"| node_node_storybook_actors
node_node_ui_components -->|"includes"| node_node_ui_draggable
node_node_ui_components -->|"includes"| node_node_ui_floating
node_node_ui_components -->|"depends on"| node_node_icons
node_node_ui_components -.->|"documents with"| node_node_documenter
node_node_ui_experiments -.->|"extends"| node_node_ui_components
node_node_documenter -->|"describes"| node_node_ui_components
node_node_documenter -.->|"renders"| node_node_icons
node_node_actors_stateless -.->|"shares pattern"| node_node_storybook_actors
node_node_actors_stateless -->|"consumes"| node_node_ui_components

click node_node_storybook_shell "https://github.com/peterjaberau/dev-kit/blob/main/.storybook"
click node_node_storybook_actors "https://github.com/peterjaberau/dev-kit/blob/main/.storybook/actors"
click node_node_storybook_theme "https://github.com/peterjaberau/dev-kit/blob/main/.storybook/decorators/withTheme.tsx"
click node_node_ui_components "https://github.com/peterjaberau/dev-kit/tree/main/packages/ui-kit/components"
click node_node_ui_floating "https://github.com/peterjaberau/dev-kit/tree/main/packages/ui-kit/components/src/components/floating-panel"
click node_node_ui_draggable "https://github.com/peterjaberau/dev-kit/tree/main/packages/ui-kit/components/src/components/draggable-panel"
click node_node_ui_experiments "https://github.com/peterjaberau/dev-kit/tree/main/packages/ui-kit/experiments"
click node_node_icons "https://github.com/peterjaberau/dev-kit/tree/main/packages/icons"
click node_node_documenter "https://github.com/peterjaberau/dev-kit/tree/main/packages/documenter"
click node_node_stories_shell "https://github.com/peterjaberau/dev-kit/tree/main/apps/stories"
click node_node_stories_charts "https://github.com/peterjaberau/dev-kit/tree/main/apps/stories/src/components/compositions/examples/charts"
click node_node_stories_system "https://github.com/peterjaberau/dev-kit/tree/main/apps/stories/src/components/compositions/examples/system"
click node_node_stories_tokens "https://github.com/peterjaberau/dev-kit/tree/main/apps/stories/src/components/compositions/examples/tokens"
click node_node_stories_components "https://github.com/peterjaberau/dev-kit/tree/main/apps/stories/src/components/compositions/examples/components"
click node_node_stories_experiments "https://github.com/peterjaberau/dev-kit/tree/main/apps/stories/src/components/compositions/examples/experiments"
click node_node_stories_site "https://github.com/peterjaberau/dev-kit/tree/main/apps/stories/src/components/compositions/examples/site"
click node_node_actors_stateless "https://github.com/peterjaberau/dev-kit/tree/main/apps/ui-actors-stateless"
click node_node_template_basic "https://github.com/peterjaberau/dev-kit/tree/main/templates/basic"
click node_node_template_cloudflare "https://github.com/peterjaberau/dev-kit/tree/main/templates/cloudflare"

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_node_ui_components,node_node_ui_floating,node_node_ui_draggable,node_node_ui_experiments,node_node_icons,node_node_documenter toneBlue
class node_node_stories_shell,node_node_stories_charts,node_node_stories_system,node_node_stories_tokens,node_node_stories_components,node_node_stories_experiments,node_node_stories_site,node_node_actors_stateless toneAmber
class node_node_template_basic,node_node_template_cloudflare toneMint
class node_node_storybook_shell,node_node_storybook_actors,node_node_storybook_theme toneRose
class node_node_toolchain toneIndigo
```

## Components

### Reusable packages

Core UI kit, icons, and documenter libraries.

- [Core components](https://github.com/peterjaberau/dev-kit/tree/main/packages/ui-kit/components): design-system UI · Main reusable component library: dialogs, menus, forms, overlays, navigation, and composites. · `packages/ui-kit/components`
- [Floating panel](https://github.com/peterjaberau/dev-kit/tree/main/packages/ui-kit/components/src/components/floating-panel): panel component · Floating panel subsystem with recipe and namespace support. · `packages/ui-kit/components/src/components/floating-panel`
- [Draggable panel](https://github.com/peterjaberau/dev-kit/tree/main/packages/ui-kit/components/src/components/draggable-panel): panel component · Draggable panel subsystem with constants, recipe, utils, and types. · `packages/ui-kit/components/src/components/draggable-panel`
- [Experimental UI](https://github.com/peterjaberau/dev-kit/tree/main/packages/ui-kit/experiments): unstable components · Non-core exploratory components such as resizable panel and toolbar. · `packages/ui-kit/experiments`
- [Icon system](https://github.com/peterjaberau/dev-kit/tree/main/packages/icons): svg icon package · Dedicated SVG/component/type pipeline for icons. · `packages/icons`
- [Documenter](https://github.com/peterjaberau/dev-kit/tree/main/packages/documenter): docs components · Documentation presentation components and types. · `packages/documenter`

### Interactive apps

Storybook showcase and standalone demo app.

- [Stories app](https://github.com/peterjaberau/dev-kit/tree/main/apps/stories): Next.js + Storybook · Primary showcase app for charts, system examples, tokens, and experiments. · `apps/stories`
- [Chart demos](https://github.com/peterjaberau/dev-kit/tree/main/apps/stories/src/components/compositions/examples/charts): story examples · Large set of composition examples for charting components. · `apps/stories/src/components/compositions/examples/charts`
- [System demos](https://github.com/peterjaberau/dev-kit/tree/main/apps/stories/src/components/compositions/examples/system): story examples · System-level examples for recipes, color, animation, and styling patterns. · `apps/stories/src/components/compositions/examples/system`
- [Token demos](https://github.com/peterjaberau/dev-kit/tree/main/apps/stories/src/components/compositions/examples/tokens): story examples · Token and style documentation examples. · `apps/stories/src/components/compositions/examples/tokens`
- [Component demos](https://github.com/peterjaberau/dev-kit/tree/main/apps/stories/src/components/compositions/examples/components): story examples · Examples for draggable and floating panel components. · `apps/stories/src/components/compositions/examples/components`
- [Experiment demos](https://github.com/peterjaberau/dev-kit/tree/main/apps/stories/src/components/compositions/examples/experiments): story examples · Story examples for documenter, resizable panels, and toolbar. · `apps/stories/src/components/compositions/examples/experiments`
- [Site demos](https://github.com/peterjaberau/dev-kit/tree/main/apps/stories/src/components/compositions/examples/site): story examples · Site-level documentation and accessibility examples. · `apps/stories/src/components/compositions/examples/site`
- [Stateless demo](https://github.com/peterjaberau/dev-kit/tree/main/apps/ui-actors-stateless): Next.js demo · Standalone app for exercising actor-based UI patterns without persistent app state. · `apps/ui-actors-stateless`

### Starter templates

Consumer app templates with shared actor/state architecture.

- [Basic template](https://github.com/peterjaberau/dev-kit/tree/main/templates/basic): starter app · Starter template with actor model, app shell, and views. · `templates/basic`
- [Cloudflare template](https://github.com/peterjaberau/dev-kit/tree/main/templates/cloudflare): starter app · Cloudflare/OpenNext starter with actor model and deployment config. · `templates/cloudflare`

### Shared runtime

Cross-cutting Storybook theming and actor/state model.

- [Storybook shell](https://github.com/peterjaberau/dev-kit/blob/main/.storybook): storybook runtime · Shared Storybook entrypoints and preview/manager setup. · `.storybook`
- [Storybook actors](https://github.com/peterjaberau/dev-kit/blob/main/.storybook/actors): state layer · Interactive Storybook actor model, hooks, provider, and data defaults. · `.storybook/actors`
- [Theme decorator](https://github.com/peterjaberau/dev-kit/blob/main/.storybook/decorators/withTheme.tsx): storybook theming · Wraps stories in design-system theme and preview context. · `.storybook/decorators/withTheme.tsx`

### Tooling

Workspace-level build and type tooling.

- **Monorepo tooling**: pnpm + TS · Workspace config, TypeScript, linting, formatting, and build tooling.

## Connections

- Monorepo tooling → Storybook shell: builds · Shared workspace tooling supports the Storybook app.
- Monorepo tooling → Stories app: builds · Shared workspace tooling supports the showcase app.
- Monorepo tooling → Stateless demo: builds · Shared workspace tooling supports the standalone demo app.
- Monorepo tooling → Basic template: scaffolds · Workspace tooling and conventions shape the starter template.
- Monorepo tooling → Cloudflare template: scaffolds · Workspace tooling and conventions shape the Cloudflare starter.
- Storybook shell → Theme decorator: wraps · Storybook preview applies the theme decorator.
- Storybook shell → Storybook actors: loads · Shared preview/runtime imports actor support.
- Storybook actors → Theme decorator: feeds · Actor-driven stories are rendered within themed context.
- Stories app → Storybook shell: uses · The stories app consumes Storybook configuration and runtime.
- Stories app → Core components: showcases · The showcase app renders the core UI kit.
- Stories app → Experimental UI: showcases · The showcase app renders experimental components.
- Stories app → Icon system: showcases · The showcase app uses the icon system in demos.
- Stories app → Documenter: showcases · The showcase app includes documenter demos.
- Stories app → Chart demos: contains · Chart example surface inside the showcase app.
- Stories app → System demos: contains · System example surface inside the showcase app.
- Stories app → Token demos: contains · Token example surface inside the showcase app.
- Stories app → Component demos: contains · Component example surface inside the showcase app.
- Stories app → Experiment demos: contains · Experiment example surface inside the showcase app.
- Stories app → Site demos: contains · Site example surface inside the showcase app.
- Component demos → Draggable panel: drives · Draggable panel examples exercise the component subsystem.
- Component demos → Floating panel: drives · Floating panel examples exercise the component subsystem.
- Experiment demos → Experimental UI: drives · Experimental stories exercise the unstable UI layer.
- Experiment demos → Documenter: drives · Documenter stories exercise documentation components.
- Basic template → Core components: consumes · Starter apps consume the reusable UI kit.
- Basic template → Icon system: consumes · Starter apps consume the shared icon package.
- Basic template → Storybook actors: uses · Starter apps follow the shared actor/state pattern.
- Cloudflare template → Core components: consumes · Cloudflare starter consumes the reusable UI kit.
- Cloudflare template → Icon system: consumes · Cloudflare starter consumes the shared icon package.
- Cloudflare template → Storybook actors: uses · Cloudflare starter follows the shared actor/state pattern.
- Core components → Draggable panel: includes · Core library contains the draggable panel subsystem.
- Core components → Floating panel: includes · Core library contains the floating panel subsystem.
- Core components → Icon system: depends on · Components use the shared icon package for glyphs.
- Core components → Documenter: documents with · Component docs and metadata are supported by the documenter package.
- Experimental UI → Core components: extends · Experimental UI builds on the core component layer.
- Documenter → Core components: describes · Documenter presents the core UI primitives and composites.
- Documenter → Icon system: renders · Documenter can render icon-related content.
- Stateless demo → Storybook actors: shares pattern · Standalone demo uses the same actor-based UI model.
- Stateless demo → Core components: consumes · Demo app composes the reusable UI kit.