# jordanliu/themecn architecture

> Architecture diagram of the GitHub repository jordanliu/themecn, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jordanliu/themecn
- Repository: https://github.com/jordanliu/themecn

## Overview

##### Project Type and Purpose
- This is a Next.js 13+ full-stack web application (app router) whose primary function is an interactive “theme studio” for generating, previewing, sharing, and importing/exporting design themes targeting the shadcn/ui component library.

##### High-Level Components
a. Client (Browser) – React components under `/app` & `/components` + CSS/JS bundles
b. Next.js Server – Server-side rendering, routing, and API endpoints under `/app/api/registry`
c. Data Store – Simple JSON (“app/dashboard/data.json”) for registry; URL-encoded theme state for shareable links
d. Static Assets – `/public` folder (images, open-graph)

##### Relationships & Data Flow
1. Browser requests page → Next.js server performs SSR or SSG → delivers HTML + JS bundles
2. Client React tree hydrates; ThemeProvider (in `app/layout.tsx`) reads theme settings from:
- URL query (encoded via `lib/theme-url.ts`)
- Local store (`lib/store.ts`)
4. UI updates client state; Live preview updates CSS variables (via `globals.css` and React custom hooks)
5. For “Share” or “Registry” features:
- “Share” encodes theme in URL → updated URL shown in UI
- “Registry” POST/GET calls Next.js API at `/api/registry/[id]/route.ts` → reads/writes `data.json` → returns stored themes

##### Architectural Patterns & Principles
- Componentized UI (shadcn/ui + custom React components)
- Server-Client separation via Next.js App Router (React Server Components vs Client Components)
- API-driven data persistence (flat JSON store; easily swap for database)
- CSS-in-JS / CSS Variables for real-time theming
- URL-first state sharing (no server sessions required)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client (Browser)" 
        direction TB
        Layout["app/layout.tsx"]:::client
        PageHome["app/page.tsx"]:::client
        PageDashboard["app/dashboard/page.tsx"]:::client
        ThemeProvider["components/theme-provider.tsx"]:::client
        ColorPicker["components/color-picker.tsx"]:::client
        ThemeDock["components/theme-dock/theme-dock.tsx"]:::client
        subgraph "Theme Dock Controls"
            direction TB
            ColorPickers["components/theme-dock/theme-color-pickers.tsx"]:::client
            Typography["components/theme-dock/theme-typography.tsx"]:::client
            BorderRadius["components/theme-dock/theme-border-radius.tsx"]:::client
            Harmonies["components/theme-dock/theme-harmonies.tsx"]:::client
            UtilityControls["components/theme-dock/theme-utility-controls.tsx"]:::client
            MobileControls["components/theme-dock/theme-mobile-controls.tsx"]:::client
            Templates["components/theme-dock/theme-templates.tsx"]:::client
        end
        UIWrappers["components/ui/*"]:::external
    end

    %% Server Layer
    NextServer["Next.js Server (SSR/Router)"]:::server
    subgraph "Next.js Server Components"
        direction TB
        APIRegistryDir["app/api/registry"]:::server
        APIRegistry["app/api/registry/[id]/route.ts"]:::server
        NextConfig["next.config.mjs"]:::server
    end

    %% Utility Modules
    subgraph "Utilities & Hooks"
        direction TB
        ThemeURL["lib/theme-url.ts"]:::server
        StoreLib["lib/store.ts"]:::server
        ColorUtils["lib/color-utils.ts"]:::server
        Utils["lib/utils.ts"]:::server
        UseMobile["hooks/use-mobile.ts"]:::server
    end

    %% Data & Assets
    subgraph "Data Store" 
        direction TB
        JSONStore["app/dashboard/data.json"]:::data
    end
    subgraph "Static Assets (CDN)" 
        direction TB
        Public["public/"]:::data
    end

    subgraph "Styles & CSS"
        direction TB
        GlobalsCSS["app/globals.css"]:::external
        PostCSS["postcss.config.mjs"]:::external
    end

    %% Data Flows
    PageHome -->|"GET page"| NextServer
    NextServer -->|"HTML+JS bundles"| PageHome
    PageDashboard -->|"GET dashboard"| NextServer
    NextServer -->|"HTML+JS bundles"| PageDashboard

    Layout -->|"hydrate"| ThemeProvider
    ThemeProvider -->|"decode URL"| ThemeURL
    ThemeProvider -->|"load local store"| StoreLib
    ThemeProvider -->|"apply CSS vars"| GlobalsCSS

    Layout -->|"load UI wrappers"| UIWrappers
    ThemeDock -->|interaction| ColorPickers
    ThemeDock -->|interaction| Typography
    ThemeDock -->|interaction| BorderRadius
    ThemeDock -->|interaction| Harmonies
    ThemeDock -->|interaction| UtilityControls
    ThemeDock -->|interaction| MobileControls
    ThemeDock -->|interaction| Templates
    ColorPicker -->|state update| ThemeProvider

    PageHome -->|fetch assets| Public
    NextServer -->|serve assets| Public

    %% API Interaction
    ThemeDock -->|"POST theme / GET theme"| APIRegistry
    APIRegistry -->|"read/write JSON"| JSONStore
    NextServer -->|"route config"| NextConfig

    %% Utilities
    ThemeURL -->|encode/decode| ThemeDock
    StoreLib -->|persist state| ThemeProvider
    ColorUtils -->|utils for color| ColorPickers
    UseMobile -->|detect mobile| MobileControls

    %% Click Events
    click Layout "https://github.com/jordanliu/themecn/blob/main/app/layout.tsx"
    click PageHome "https://github.com/jordanliu/themecn/blob/main/app/page.tsx"
    click PageDashboard "https://github.com/jordanliu/themecn/blob/main/app/dashboard/page.tsx"
    click ThemeProvider "https://github.com/jordanliu/themecn/blob/main/components/theme-provider.tsx"
    click ColorPicker "https://github.com/jordanliu/themecn/blob/main/components/color-picker.tsx"
    click ThemeDock "https://github.com/jordanliu/themecn/blob/main/components/theme-dock/theme-dock.tsx"
    click ColorPickers "https://github.com/jordanliu/themecn/blob/main/components/theme-dock/theme-color-pickers.tsx"
    click Typography "https://github.com/jordanliu/themecn/blob/main/components/theme-dock/theme-typography.tsx"
    click BorderRadius "https://github.com/jordanliu/themecn/blob/main/components/theme-dock/theme-border-radius.tsx"
    click Harmonies "https://github.com/jordanliu/themecn/blob/main/components/theme-dock/theme-harmonies.tsx"
    click UtilityControls "https://github.com/jordanliu/themecn/blob/main/components/theme-dock/theme-utility-controls.tsx"
    click MobileControls "https://github.com/jordanliu/themecn/blob/main/components/theme-dock/theme-mobile-controls.tsx"
    click Templates "https://github.com/jordanliu/themecn/blob/main/components/theme-dock/theme-templates.tsx"
    click UIWrappers "https://github.com/jordanliu/themecn/tree/main/components/ui/"
    click APIRegistryDir "https://github.com/jordanliu/themecn/tree/main/app/api/registry"
    click APIRegistry "https://github.com/jordanliu/themecn/blob/main/app/api/registry/[id]/route.ts"
    click NextConfig "https://github.com/jordanliu/themecn/blob/main/next.config.mjs"
    click JSONStore "https://github.com/jordanliu/themecn/blob/main/app/dashboard/data.json"
    click Public "https://github.com/jordanliu/themecn/tree/main/public/"
    click GlobalsCSS "https://github.com/jordanliu/themecn/blob/main/app/globals.css"
    click PostCSS "https://github.com/jordanliu/themecn/blob/main/postcss.config.mjs"
    click ThemeURL "https://github.com/jordanliu/themecn/blob/main/lib/theme-url.ts"
    click StoreLib "https://github.com/jordanliu/themecn/blob/main/lib/store.ts"
    click ColorUtils "https://github.com/jordanliu/themecn/blob/main/lib/color-utils.ts"
    click Utils "https://github.com/jordanliu/themecn/blob/main/lib/utils.ts"
    click UseMobile "https://github.com/jordanliu/themecn/blob/main/hooks/use-mobile.ts"

    %% Styles
    classDef client fill:#D0E8FF,stroke:#0366d6
    classDef server fill:#DFFFE0,stroke:#22863a
    classDef data fill:#FFF5B1,stroke:#DBAB09
    classDef external fill:#EDEFF0,stroke:#6a737d
```
