# ibelick/prompt-kit architecture

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

- Interactive diagram: https://gitdiagram.com/ibelick/prompt-kit
- Repository: https://github.com/ibelick/prompt-kit

## Overview

##### Project Type and Purpose
- A Next.js-based documentation and demo site for an AI UI component library (“prompt-kit”).
- Combines static docs (MDX), dynamic demo pages, and serverless API routes to prototype/chat with LLMs.
- Ships as a customizable React/TypeScript component suite built on top of shadcn/ui.

##### File Structure Analysis
- Top-level “app” directory: Next.js 13 App Router pages, layouts, dynamic routes (`[slug]`), MDX docs under `app/docs`.
- `app/api`: serverless functions for “demo” and “primitives” (chatbot & tool-calling).
- `components/*`: library of reusable React components (grouped by feature: ui primitives, prompt-kit facades, demo helpers, blocks).
- `lib` + `hooks`: shared utilities, code-rendering, API-key handling, viewport helpers.
- `scripts`: Node scripts generating JSON registries and LLM lists, feeding build-time data into the site.
- `public`: static assets (images, JSON schemas) served directly.
- Config files: Next.js, Tailwind/PostCSS, ESLint, TypeScript.

##### Key Insights from README
- Exposes prompt-kit components via `npx shadcn add prompt-kit/...`.
- Focus is on composable chat UIs, file-upload, code previews, streaming responses, etc.
- No traditional database—state is ephemeral in serverless routes or in-browser.

##### Main Components
a. Client (Browser)
– Renders React pages (SSG/SSR) and components.
– Invokes demo pages and interactive primitives.
b. Next.js Server (Node.js Lambdas)
– Routes under `app/` handle SSR and SSG of MDX pages, dynamic route params.
– API endpoints (`/api/demo/*`, `/api/primitives/*`) proxy or orchestrate calls to external LLM services.
c. External LLM Services
– OpenAI, ChatGPT, MistralAI, or custom LLMs (configured via `lib` + `scripts`).
d. Static Asset Store (CDN)
– `public/` folder serves JSON schemas and images.
e. Build & Registry Pipeline
– `scripts/registry-*.ts` and `generate-llms-txt.js` produce JSON/text files in `public/` at build time.
f. Component Library
– `components/prompt-kit` (the public API), wrapping lower-level `components/ui` and `components/primitives`.
– Used both in docs examples and intended for consumer projects.

##### Relationships and Data Flows
- User ➔ Browser: requests page (docs, demo, component preview).
- Browser ➔ Next.js Server: SSR/SSG page generation or client-side navigation.
- Next.js Server ➔ External LLMs: via API routes when user interacts (e.g., chat).
- Build Scripts ➔ Public Assets: inject LLM lists and component registries consumed by the site.
- Browser ➔ CDN: fetch static JSON schemas and OpenGraph images.

##### Architectural Patterns & Principles
- “File-based Routing” with App Router (Next.js 13).
- Component-driven development: atomic UI → primitives → composite prompt-kit.
- ISR/SSG for docs, on-demand SSR for dynamic pages.
- Serverless functions for external HTTP calls (decoupled from UI).
- Build-time code generation for registry and LLM support lists.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client (Browser)" 
        direction TB
        Browser["Browser UI & Pages"]:::nextjsApp
    end

    %% Next.js Application Layer
    subgraph "Next.js App (app/ + components/)" 
        direction TB
        NextServer["Next.js App (app/)"]:::nextjsApp
    end

    %% Serverless API Routes Layer
    subgraph "Serverless API Routes" 
        direction TB
        DemoChatAPI["/api/demo/chatbot"]:::api
        DemoToolAPI["/api/demo/tool-calling"]:::api
        PrimChatAPI["/api/primitives/chatbot"]:::api
        PrimToolAPI["/api/primitives/tool-calling"]:::api
    end

    %% Generated LLM Lists Routes
    subgraph "LLM List Routes" 
        direction TB
        LLMS["/llms.txt & /llms-full.txt"]:::api
    end

    %% Component Library Layer
    subgraph "Component Library (components/)" 
        direction TB
        PromptKit["Prompt-Kit Facades"]:::comp
        UIPrimitives["UI Primitives"]:::comp
        CorePrimitives["Core Primitives"]:::comp
        DemoHelpers["Demo Helpers"]:::comp
        Blocks["Blocks (Examples)"]:::comp
    end

    %% Shared Hooks & Utilities
    subgraph "Shared Hooks & Utilities" 
        direction TB
        HooksUtils["hooks/ & lib/"]:::comp
    end

    %% Build & Registry Pipeline
    subgraph "Build & Registry Pipeline (scripts/)" 
        direction TB
        Scripts["Registry & Build Scripts"]:::build
    end

    %% Static Assets (CDN)
    subgraph "Static Assets (CDN)" 
        direction TB
        PublicAssets["public/ (JSON & Images)"]:::cdn
    end

    %% External LLM Services
    subgraph "External LLM Services" 
        direction TB
        ExternalLLM["OpenAI, ChatGPT, MistralAI, etc."]:::ext
    end

    %% Data Flows
    Browser -->|"Request pages"| NextServer
    Browser -->|"XHR Fetch"| DemoChatAPI
    Browser -->|"XHR Fetch"| DemoToolAPI
    Browser -->|"XHR Fetch"| PrimChatAPI
    Browser -->|"XHR Fetch"| PrimToolAPI
    Browser -->|"Fetch JSON/Images"| PublicAssets

    DemoChatAPI -->|"HTTP calls"| ExternalLLM
    DemoToolAPI -->|"HTTP calls"| ExternalLLM
    PrimChatAPI -->|"HTTP calls"| ExternalLLM
    PrimToolAPI -->|"HTTP calls"| ExternalLLM

    Scripts -->|"Generate at build"| PublicAssets
    Scripts -->|"Generate at build"| LLMS
    LLMS -->|"Serve text lists"| Browser

    %% Click Events
    click Browser "https://github.com/ibelick/prompt-kit/tree/main/app/"
    click NextServer "https://github.com/ibelick/prompt-kit/tree/main/app/"
    click DemoChatAPI "https://github.com/ibelick/prompt-kit/blob/main/app/api/demo/chatbot/route.ts"
    click DemoToolAPI "https://github.com/ibelick/prompt-kit/blob/main/app/api/demo/tool-calling/route.ts"
    click PrimChatAPI "https://github.com/ibelick/prompt-kit/blob/main/app/api/primitives/chatbot/route.ts"
    click PrimToolAPI "https://github.com/ibelick/prompt-kit/blob/main/app/api/primitives/tool-calling/route.ts"
    click PromptKit "https://github.com/ibelick/prompt-kit/tree/main/components/prompt-kit/"
    click UIPrimitives "https://github.com/ibelick/prompt-kit/tree/main/components/ui/"
    click CorePrimitives "https://github.com/ibelick/prompt-kit/blob/main/components/primitives/chatbot.tsx"
    click CorePrimitives "https://github.com/ibelick/prompt-kit/blob/main/components/primitives/tool-calling.tsx"
    click DemoHelpers "https://github.com/ibelick/prompt-kit/tree/main/components/demo/"
    click Blocks "https://github.com/ibelick/prompt-kit/tree/main/components/blocks/"
    click HooksUtils "https://github.com/ibelick/prompt-kit/blob/main/hooks/use-api-key.ts"
    click HooksUtils "https://github.com/ibelick/prompt-kit/blob/main/hooks/use-breakpoint.ts"
    click HooksUtils "https://github.com/ibelick/prompt-kit/blob/main/hooks/use-mobile.ts"
    click HooksUtils "https://github.com/ibelick/prompt-kit/blob/main/lib/code.ts"
    click HooksUtils "https://github.com/ibelick/prompt-kit/blob/main/lib/shiki.ts"
    click HooksUtils "https://github.com/ibelick/prompt-kit/blob/main/lib/utils.ts"
    click Scripts "https://github.com/ibelick/prompt-kit/blob/main/scripts/generate-llms-txt.js"
    click Scripts "https://github.com/ibelick/prompt-kit/blob/main/scripts/registry-build.ts"
    click Scripts "https://github.com/ibelick/prompt-kit/blob/main/scripts/registry-components.ts"
    click Scripts "https://github.com/ibelick/prompt-kit/blob/main/scripts/registry-primitives.ts"
    click Scripts "https://github.com/ibelick/prompt-kit/blob/main/scripts/registry-schema.ts"
    click PublicAssets "https://github.com/ibelick/prompt-kit/tree/main/public/c/"
    click PublicAssets "https://github.com/ibelick/prompt-kit/blob/main/public/opengraph-image.alt"
    click LLMS "https://github.com/ibelick/prompt-kit/blob/main/app/llms.txt/route.ts"
    click LLMS "https://github.com/ibelick/prompt-kit/blob/main/app/llms-full.txt/route.ts"

    %% Styles
    classDef nextjsApp fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef api fill:#FFD580,stroke:#333,stroke-width:1px,shape:hexagon
    classDef comp fill:#cfe2ff,stroke:#333,stroke-width:1px
    classDef build fill:#FFFACD,stroke:#333,stroke-width:1px
    classDef cdn fill:#90EE90,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef ext fill:#E0B0FF,stroke:#333,stroke-width:1px,shape:cloud
```
