peterjaberau/dev-kit

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.