# dinil-thilakarathne/sona-ui architecture

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

- Interactive diagram: https://gitdiagram.com/dinil-thilakarathne/sona-ui
- Repository: https://github.com/dinil-thilakarathne/sona-ui

## Overview

Sona UI combines a component catalog and documentation site with a source-owned React component registry that users install by copying code through the shadcn CLI. The primary journey is browse the catalog, inspect documentation and live previews, then install a selected component. Separate capabilities include AI-agent discovery resources, Motion Lab tuning, and GitHub-backed site data. The graph uses README statements and the supplied source index; unsampled modules are represented only where their role is documented or evident from the tree.

Main entry points: [`src/components/common/component-preview.tsx`](https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/components/common/component-preview.tsx) (Live Preview), [`src/registry/sonaui`](https://github.com/dinil-thilakarathne/sona-ui/tree/master/src/registry/sonaui) (Component Sources), [`src/components/common/component-preview-server.tsx`](https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/components/common/component-preview-server.tsx) (Preview Resolver), [`src/app/components/page.tsx`](https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/app/components/page.tsx) (Component Catalog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_site["Catalog and Docs"]
  node_catalog["Component Catalog<br/>[page.tsx]"]
  node_docnav["Docs Navigation<br/>[components.ts]"]
  node_search["Documentation Search<br/>[useSearch.ts]"]
  node_docs["Component Documentation"]
  node_showcase["Component Showcase"]
end

subgraph group_preview["Preview and Tuning"]
  node_previewserver["Preview Resolver"]
  node_preview["Live Preview"]
  node_tuning["Dialog Tuning"]
  node_motionlab["Motion Lab<br/>[motion-lab.tsx]"]
  node_motionconfig["Motion Presets<br/>[dialog-motion.ts]"]
end

subgraph group_registry["Component Registry"]
  node_registry["Component Sources"]
  node_registryindex["Registry Index<br/>[index.ts]"]
  node_sourceapi["Source File API<br/>[route.ts]"]
end

subgraph group_agents["Agent Resources"]
  node_agentcatalog["Agent Catalog<br/>[agent-metadata.ts]"]
  node_agentmarkdown["Agent Markdown<br/>[agent-markdown.ts]"]
  node_agentproxy["Agent Routes<br/>[proxy.ts]"]
end

subgraph group_services["Site Services"]
  node_contribapi["Contributions API<br/>[route.ts]"]
  node_contribdata["Contribution Data"]
  node_starsapi["Star History API<br/>[route.ts]"]
  node_stardata["Star History Data"]
end

node_visitor(("Developer"))
node_cli["shadcn CLI"]
node_github["GitHub"]

node_visitor -->|"browses"| node_catalog
node_catalog -->|"renders"| node_showcase
node_visitor -->|"opens docs"| node_docs
node_docs -.->|"uses navigation"| node_docnav
node_visitor -->|"searches docs"| node_search
node_search -->|"filters slugs"| node_docnav
node_showcase -->|"loads registry preview"| node_registryindex
node_previewserver -->|"resolves component"| node_registryindex
node_previewserver -->|"renders preview"| node_preview
node_preview -->|"uses tuning controls"| node_tuning
node_preview -->|"previews component"| node_registry
node_visitor -->|"tunes motion"| node_motionlab
node_motionlab -.->|"uses presets"| node_motionconfig
node_visitor -->|"installs component"| node_cli
node_cli -->|"copies source"| node_registry
node_visitor -->|"discovers components"| node_agentcatalog
node_agentproxy -->|"serves markdown"| node_agentmarkdown
node_visitor -->|"requests source"| node_sourceapi
node_sourceapi -->|"reads source"| node_registry
node_contribapi -->|"fetches data"| node_contribdata
node_stardata -.->|"requests history"| node_github
node_starsapi -->|"fetches history"| node_stardata
node_contribdata -.->|"requests contributions"| node_github

click node_catalog "https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/app/components/page.tsx"
click node_docnav "https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/config/components.ts"
click node_search "https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/hooks/useSearch.ts"
click node_docs "https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/components/docs-focus/docs-focus-shell.tsx"
click node_showcase "https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/components/component-showcase/component-showcase.tsx"
click node_previewserver "https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/components/common/component-preview-server.tsx"
click node_preview "https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/components/common/component-preview.tsx"
click node_tuning "https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/components/docs-focus/animated-dialog-tuning.tsx"
click node_motionlab "https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/components/motion-lab/motion-lab.tsx"
click node_registry "https://github.com/dinil-thilakarathne/sona-ui/tree/master/src/registry/sonaui"
click node_registryindex "https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/registry/index.ts"
click node_sourceapi "https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/app/api/read-file/route.ts"
click node_agentcatalog "https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/registry/agent-metadata.ts"
click node_agentmarkdown "https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/lib/agent-markdown.ts"
click node_agentproxy "https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/proxy.ts"
click node_contribapi "https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/app/api/github-contributions/route.ts"
click node_contribdata "https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/lib/github-contributions.ts"
click node_starsapi "https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/app/api/github-star-history/route.ts"
click node_stardata "https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/lib/github-star-history.ts"
click node_motionconfig "https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/lib/motion-lab/dialog-motion.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_catalog,node_docnav,node_search,node_docs,node_showcase toneBlue
class node_previewserver,node_preview,node_tuning,node_motionlab,node_motionconfig toneAmber
class node_registry,node_registryindex,node_sourceapi toneMint
class node_agentcatalog,node_agentmarkdown,node_agentproxy toneRose
class node_contribapi,node_contribdata,node_starsapi,node_stardata,node_visitor,node_cli,node_github toneIndigo
```

## Components

### Catalog and Docs

- [Component Catalog](https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/app/components/page.tsx): `src/app/components/page.tsx`
- [Docs Navigation](https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/config/components.ts): `src/config/components.ts`
- [Documentation Search](https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/hooks/useSearch.ts): `src/hooks/useSearch.ts`
- [Component Documentation](https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/components/docs-focus/docs-focus-shell.tsx): `src/components/docs-focus/docs-focus-shell.tsx`
- [Component Showcase](https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/components/component-showcase/component-showcase.tsx): `src/components/component-showcase/component-showcase.tsx`

### Preview and Tuning

- [Preview Resolver](https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/components/common/component-preview-server.tsx): `src/components/common/component-preview-server.tsx`
- [Live Preview](https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/components/common/component-preview.tsx): `src/components/common/component-preview.tsx`
- [Dialog Tuning](https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/components/docs-focus/animated-dialog-tuning.tsx): `src/components/docs-focus/animated-dialog-tuning.tsx`
- [Motion Lab](https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/components/motion-lab/motion-lab.tsx): `src/components/motion-lab/motion-lab.tsx`
- [Motion Presets](https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/lib/motion-lab/dialog-motion.ts): `src/lib/motion-lab/dialog-motion.ts`

### Component Registry

- [Component Sources](https://github.com/dinil-thilakarathne/sona-ui/tree/master/src/registry/sonaui): `src/registry/sonaui`
- [Registry Index](https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/registry/index.ts): `src/registry/index.ts`
- [Source File API](https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/app/api/read-file/route.ts): `src/app/api/read-file/route.ts`

### Agent Resources

- [Agent Catalog](https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/registry/agent-metadata.ts): `src/registry/agent-metadata.ts`
- [Agent Markdown](https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/lib/agent-markdown.ts): `src/lib/agent-markdown.ts`
- [Agent Routes](https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/proxy.ts): `src/proxy.ts`

### Site Services

- [Contributions API](https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/app/api/github-contributions/route.ts): `src/app/api/github-contributions/route.ts`
- [Contribution Data](https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/lib/github-contributions.ts): `src/lib/github-contributions.ts`
- [Star History API](https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/app/api/github-star-history/route.ts): `src/app/api/github-star-history/route.ts`
- [Star History Data](https://github.com/dinil-thilakarathne/sona-ui/blob/master/src/lib/github-star-history.ts): `src/lib/github-star-history.ts`

### Other components

- **Developer**
- **shadcn CLI**
- **GitHub**

## Connections

- Developer → Component Catalog: browses (evidence: `README.md`)
- Component Catalog → Component Showcase: renders (evidence: `src/app/components/page.tsx`)
- Developer → Component Documentation: opens docs (evidence: `README.md`)
- Component Documentation → Docs Navigation: uses navigation
- Developer → Documentation Search: searches docs
- Documentation Search → Docs Navigation: filters slugs (evidence: `src/hooks/useSearch.ts`)
- Component Showcase → Registry Index: loads registry preview
- Preview Resolver → Registry Index: resolves component (evidence: `src/components/common/component-preview-server.tsx`)
- Preview Resolver → Live Preview: renders preview (evidence: `src/components/common/component-preview-server.tsx`)
- Live Preview → Dialog Tuning: uses tuning controls (evidence: `src/components/common/component-preview.tsx`)
- Live Preview → Component Sources: previews component (evidence: `src/components/common/component-preview.tsx`)
- Developer → Motion Lab: tunes motion (evidence: `README.md`)
- Motion Lab → Motion Presets: uses presets
- Developer → shadcn CLI: installs component (evidence: `README.md`)
- shadcn CLI → Component Sources: copies source (evidence: `README.md`)
- Developer → Agent Catalog: discovers components (evidence: `README.md`)
- Agent Routes → Agent Markdown: serves markdown (evidence: `src/proxy.ts`)
- Developer → Source File API: requests source (evidence: `src/app/api/read-file/route.ts`)
- Source File API → Component Sources: reads source (evidence: `src/app/api/read-file/route.ts`)
- Contributions API → Contribution Data: fetches data (evidence: `src/app/api/github-contributions/route.ts`)
- Star History Data → GitHub: requests history
- Star History API → Star History Data: fetches history (evidence: `src/app/api/github-star-history/route.ts`)
- Contribution Data → GitHub: requests contributions
