# shadcn/ui architecture

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

- Interactive diagram: https://gitdiagram.com/shadcn/ui
- Repository: https://github.com/shadcn/ui

## Overview

shadcn/ui is an open-code component library and ecosystem: developers browse documentation and examples, use or customize components, and can install registry items or scaffold projects with the CLI. The repository also contains a chat-streaming helper library and React transcript-scroller primitives. The tree identifies additional product areas such as the visual designer, charts, colors, and style previews; their internal links are left unasserted where source was not sampled. Edges cite shown imports/calls or documented product context; dashed edges indicate unverified relationships.

Main entry points: [`packages/helpers/src/core/chat.ts`](https://github.com/shadcn/ui/blob/main/packages/helpers/src/core/chat.ts) (Chat API), [`packages/react/src/message-scroller/use-message-scroller-controller.ts`](https://github.com/shadcn/ui/blob/main/packages/react/src/message-scroller/use-message-scroller-controller.ts) (Scroller controller), [`apps/v4/app/(app)/blocks/page.tsx`](https://github.com/shadcn/ui/blob/main/apps/v4/app/(app)/blocks/page.tsx) (Documentation), [`packages/shadcn/src/templates/react-router.ts`](https://github.com/shadcn/ui/blob/main/packages/shadcn/src/templates/react-router.ts) (Router template)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_site["UI site"]
  node_docs["Documentation<br/>[page.tsx]"]
  node_component_catalog["Component catalog<br/>[components.ts]"]
  node_block_catalog["Block catalog<br/>[blocks.ts]"]
  node_designer["Theme designer<br/>[page.tsx]"]
  node_style_previews["Style previews<br/>[page.tsx]"]
  node_charts["Charts<br/>[charts.tsx]"]
  node_colors["Color palettes<br/>[colors.ts]"]
end

subgraph group_registry["Registry and CLI"]
  node_registry_data[("Component registry<br/>[__index__.tsx]")]
  node_registry_search["Registry search<br/>[search.ts]"]
  node_cli_search["CLI search<br/>[search.ts]"]
end

subgraph group_helpers["Runtime libraries"]
  node_chat_api["Chat API<br/>[chat.ts]"]
  node_chat_ids["Chat IDs<br/>[ids.ts]"]
  node_chat_lower["Event lowering<br/>[lower.ts]"]
  node_chat_payloads["Chat payloads<br/>[payloads.ts]"]
  node_chat_stream["Turn streaming<br/>[stream.ts]"]
  node_chat_writer["Event writer<br/>[writer.ts]"]
  node_scroller_controller["Scroller controller"]
  node_scroller_geometry["Scroll geometry<br/>[geometry.ts]"]
  node_scroller_commands["Scroll commands"]
  node_scroller_refs["Scroller refs"]
  node_scroller_types["Scroller contracts<br/>[types.ts]"]
end

subgraph group_templates["Project templates"]
  node_template_creator["Template creation<br/>[create-template.ts]"]
  node_monorepo_setup["Monorepo setup<br/>[monorepo.ts]"]
  node_router_template["Router template<br/>[react-router.ts]"]
end

node_developer(("Developer"))

node_developer -.->|"browses"| node_docs
node_developer -.->|"customizes"| node_designer
node_developer -.->|"searches registry"| node_cli_search
node_docs -.->|"presents"| node_component_catalog
node_docs -.->|"presents"| node_block_catalog
node_registry_search -.->|"searches"| node_registry_data
node_cli_search -->|"uses"| node_registry_search
node_chat_api -->|"creates IDs"| node_chat_ids
node_chat_api -->|"lowers events"| node_chat_lower
node_chat_api -->|"creates payloads"| node_chat_payloads
node_chat_api -->|"creates streams"| node_chat_stream
node_chat_api -->|"creates writers"| node_chat_writer
node_scroller_controller -->|"measures scroll"| node_scroller_geometry
node_scroller_controller -->|"configures commands"| node_scroller_commands
node_scroller_controller -->|"creates refs"| node_scroller_refs
node_scroller_controller -.->|"uses contracts"| node_scroller_types
node_router_template -->|"configures"| node_template_creator
node_router_template -->|"configures"| node_monorepo_setup
node_monorepo_setup -->|"uses"| node_template_creator

click node_docs "https://github.com/shadcn/ui/blob/main/apps/v4/app/(app)/blocks/page.tsx"
click node_component_catalog "https://github.com/shadcn/ui/blob/main/apps/v4/lib/components.ts"
click node_block_catalog "https://github.com/shadcn/ui/blob/main/apps/v4/lib/blocks.ts"
click node_designer "https://github.com/shadcn/ui/blob/main/apps/v4/app/(app)/(create)/create/page.tsx"
click node_style_previews "https://github.com/shadcn/ui/blob/main/apps/v4/app/(app)/(styles)/sera/page.tsx"
click node_charts "https://github.com/shadcn/ui/blob/main/apps/v4/app/(app)/charts/charts.tsx"
click node_colors "https://github.com/shadcn/ui/blob/main/apps/v4/lib/colors.ts"
click node_registry_data "https://github.com/shadcn/ui/blob/main/apps/v4/registry/__index__.tsx"
click node_registry_search "https://github.com/shadcn/ui/blob/main/packages/registry/src/registry/search.ts"
click node_cli_search "https://github.com/shadcn/ui/blob/main/packages/shadcn/src/commands/search.ts"
click node_chat_api "https://github.com/shadcn/ui/blob/main/packages/helpers/src/core/chat.ts"
click node_chat_ids "https://github.com/shadcn/ui/blob/main/packages/helpers/src/core/ids.ts"
click node_chat_lower "https://github.com/shadcn/ui/blob/main/packages/helpers/src/core/lower.ts"
click node_chat_payloads "https://github.com/shadcn/ui/blob/main/packages/helpers/src/core/payloads.ts"
click node_chat_stream "https://github.com/shadcn/ui/blob/main/packages/helpers/src/core/stream.ts"
click node_chat_writer "https://github.com/shadcn/ui/blob/main/packages/helpers/src/core/writer.ts"
click node_scroller_controller "https://github.com/shadcn/ui/blob/main/packages/react/src/message-scroller/use-message-scroller-controller.ts"
click node_scroller_geometry "https://github.com/shadcn/ui/blob/main/packages/react/src/message-scroller/geometry.ts"
click node_scroller_commands "https://github.com/shadcn/ui/blob/main/packages/react/src/message-scroller/use-message-scroller-commands.ts"
click node_scroller_refs "https://github.com/shadcn/ui/blob/main/packages/react/src/message-scroller/use-message-scroller-refs.ts"
click node_scroller_types "https://github.com/shadcn/ui/blob/main/packages/react/src/message-scroller/types.ts"
click node_template_creator "https://github.com/shadcn/ui/blob/main/packages/shadcn/src/templates/create-template.ts"
click node_monorepo_setup "https://github.com/shadcn/ui/blob/main/packages/shadcn/src/templates/monorepo.ts"
click node_router_template "https://github.com/shadcn/ui/blob/main/packages/shadcn/src/templates/react-router.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_docs,node_component_catalog,node_block_catalog,node_designer,node_style_previews,node_charts,node_colors toneBlue
class node_registry_data,node_registry_search,node_cli_search toneAmber
class node_chat_api,node_chat_ids,node_chat_lower,node_chat_payloads,node_chat_stream,node_chat_writer,node_scroller_controller,node_scroller_geometry,node_scroller_commands,node_scroller_refs,node_scroller_types toneMint
class node_template_creator,node_monorepo_setup,node_router_template toneRose
class node_developer toneIndigo
```

## Components

### UI site

- [Documentation](https://github.com/shadcn/ui/blob/main/apps/v4/app/(app)/blocks/page.tsx): `apps/v4/app/(app)/blocks/page.tsx`
- [Component catalog](https://github.com/shadcn/ui/blob/main/apps/v4/lib/components.ts): `apps/v4/lib/components.ts`
- [Block catalog](https://github.com/shadcn/ui/blob/main/apps/v4/lib/blocks.ts): `apps/v4/lib/blocks.ts`
- [Theme designer](https://github.com/shadcn/ui/blob/main/apps/v4/app/(app)/(create)/create/page.tsx): `apps/v4/app/(app)/(create)/create/page.tsx`
- [Style previews](https://github.com/shadcn/ui/blob/main/apps/v4/app/(app)/(styles)/sera/page.tsx): `apps/v4/app/(app)/(styles)/sera/page.tsx`
- [Charts](https://github.com/shadcn/ui/blob/main/apps/v4/app/(app)/charts/charts.tsx): `apps/v4/app/(app)/charts/charts.tsx`
- [Color palettes](https://github.com/shadcn/ui/blob/main/apps/v4/lib/colors.ts): `apps/v4/lib/colors.ts`

### Registry and CLI

- [Component registry](https://github.com/shadcn/ui/blob/main/apps/v4/registry/__index__.tsx): `apps/v4/registry/__index__.tsx`
- [Registry search](https://github.com/shadcn/ui/blob/main/packages/registry/src/registry/search.ts): `packages/registry/src/registry/search.ts`
- [CLI search](https://github.com/shadcn/ui/blob/main/packages/shadcn/src/commands/search.ts): `packages/shadcn/src/commands/search.ts`

### Runtime libraries

- [Chat API](https://github.com/shadcn/ui/blob/main/packages/helpers/src/core/chat.ts): `packages/helpers/src/core/chat.ts`
- [Chat IDs](https://github.com/shadcn/ui/blob/main/packages/helpers/src/core/ids.ts): `packages/helpers/src/core/ids.ts`
- [Event lowering](https://github.com/shadcn/ui/blob/main/packages/helpers/src/core/lower.ts): `packages/helpers/src/core/lower.ts`
- [Chat payloads](https://github.com/shadcn/ui/blob/main/packages/helpers/src/core/payloads.ts): `packages/helpers/src/core/payloads.ts`
- [Turn streaming](https://github.com/shadcn/ui/blob/main/packages/helpers/src/core/stream.ts): `packages/helpers/src/core/stream.ts`
- [Event writer](https://github.com/shadcn/ui/blob/main/packages/helpers/src/core/writer.ts): `packages/helpers/src/core/writer.ts`
- [Scroller controller](https://github.com/shadcn/ui/blob/main/packages/react/src/message-scroller/use-message-scroller-controller.ts): `packages/react/src/message-scroller/use-message-scroller-controller.ts`
- [Scroll geometry](https://github.com/shadcn/ui/blob/main/packages/react/src/message-scroller/geometry.ts): `packages/react/src/message-scroller/geometry.ts`
- [Scroll commands](https://github.com/shadcn/ui/blob/main/packages/react/src/message-scroller/use-message-scroller-commands.ts): `packages/react/src/message-scroller/use-message-scroller-commands.ts`
- [Scroller refs](https://github.com/shadcn/ui/blob/main/packages/react/src/message-scroller/use-message-scroller-refs.ts): `packages/react/src/message-scroller/use-message-scroller-refs.ts`
- [Scroller contracts](https://github.com/shadcn/ui/blob/main/packages/react/src/message-scroller/types.ts): `packages/react/src/message-scroller/types.ts`

### Project templates

- [Template creation](https://github.com/shadcn/ui/blob/main/packages/shadcn/src/templates/create-template.ts): `packages/shadcn/src/templates/create-template.ts`
- [Monorepo setup](https://github.com/shadcn/ui/blob/main/packages/shadcn/src/templates/monorepo.ts): `packages/shadcn/src/templates/monorepo.ts`
- [Router template](https://github.com/shadcn/ui/blob/main/packages/shadcn/src/templates/react-router.ts): `packages/shadcn/src/templates/react-router.ts`

### Other components

- **Developer**

## Connections

- Developer → Documentation: browses (evidence: `README.md`)
- Developer → Theme designer: customizes
- Developer → CLI search: searches registry
- Documentation → Component catalog: presents
- Documentation → Block catalog: presents
- Registry search → Component registry: searches
- CLI search → Registry search: uses (evidence: `packages/shadcn/src/commands/search.ts`)
- Chat API → Chat IDs: creates IDs (evidence: `packages/helpers/src/core/chat.ts`)
- Chat API → Event lowering: lowers events (evidence: `packages/helpers/src/core/chat.ts`)
- Chat API → Chat payloads: creates payloads (evidence: `packages/helpers/src/core/chat.ts`)
- Chat API → Turn streaming: creates streams (evidence: `packages/helpers/src/core/chat.ts`)
- Chat API → Event writer: creates writers (evidence: `packages/helpers/src/core/chat.ts`)
- Scroller controller → Scroll geometry: measures scroll (evidence: `packages/react/src/message-scroller/use-message-scroller-controller.ts`)
- Scroller controller → Scroll commands: configures commands (evidence: `packages/react/src/message-scroller/use-message-scroller-controller.ts`)
- Scroller controller → Scroller refs: creates refs (evidence: `packages/react/src/message-scroller/use-message-scroller-controller.ts`)
- Scroller controller → Scroller contracts: uses contracts (evidence: `packages/react/src/message-scroller/use-message-scroller-controller.ts`)
- Router template → Template creation: configures (evidence: `packages/shadcn/src/templates/react-router.ts`)
- Router template → Monorepo setup: configures (evidence: `packages/shadcn/src/templates/react-router.ts`)
- Monorepo setup → Template creation: uses (evidence: `packages/shadcn/src/templates/monorepo.ts`)