# markmead/hyperui architecture

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

- Interactive diagram: https://gitdiagram.com/markmead/hyperui
- Repository: https://github.com/markmead/hyperui

## Overview

##### Project type and purpose
- This is a full-stack React/Next.js application (App Router) used to showcase and serve a catalogue of Tailwind CSS components (HyperUI).
- It combines static site generation (SSG), dynamic routing (MDX-based pages), and a lightweight API route for search.

##### High-level components
a. Client (Browser)
b. Next.js Server (SSG/SSR)
c. File-system Content Layer (MDX files in src/data)
d. UI Component Library (React components in src/components + public HTML snippets)
e. API Layer (app/api/search/route.js + src/utils/db.js)
f. CSS Build Pipeline (Tailwind CSS, PostCSS, styles in src/styles)
g. Configuration & Deployment (next.config.js, Vercel/GitHub CI)

##### Relationships and data flows
- Browser → Next.js Server
- Requests pages under /, /about, /blog, /components/:category/:collection
- Requests search via AJAX against /api/search
- Next.js Server → File-system Content Layer
- Reads MDX files (src/data/pages, src/data/posts, src/data/components/…)
- Transforms MDX via src/utils/transformers.js into React elements
- Next.js Server → UI Component Library
- Renders pages by composing layout.jsx + header/footer/navigation + dynamic page.jsx
- Embeds component previews using HTML snippets from public/components or live React previews
- Browser ← Next.js Server
- Receives pre-rendered HTML/CSS/JS (Tailwind CSS styles via PostCSS pipeline)
- Browser → /api/search → Next.js Server → src/utils/db.js → File-system
- Returns JSON search results

##### Architectural patterns & design principles
- App Router (Next.js 13+) for nested layouts and file-based routing
- Content-driven pages via MDX + data-first approach
- SSG for performance, with on-demand dynamic rendering for API routes
- Separation of concerns
- “app/” for routes and layouts
- “src/components/” for React UI primitives
- “src/data/” for Markdown content
- “public/components/” for static HTML previews
- “src/utils/” for transformation and data access logic

##### Relevant technologies, frameworks, and libraries
- Next.js 13 App Router (layout.jsx, page.jsx, route.js)
- React (JSX, client/server components)
- MDX (Markdown + JSX pages)
- Tailwind CSS (postcss.config.js, tailwind.config.js)
- PostCSS, Prettier, ESLint for linting & formatting
- Node.js file-system for content ingestion
- Potential hosting on Vercel or Netlify

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client (Browser)"
        direction TB
        Browser["Browser"]:::client
    end

    %% Server Layer
    subgraph "Server (Next.js)"
        direction TB

        subgraph "App Router (Next.js 13+)" 
            direction TB
            Layout["layout.jsx"]:::server
            Page["page.jsx"]:::server
            NotFound["not-found.jsx"]:::server

            subgraph "Dynamic Content Routes (MDX-based)"
                direction TB
                CompCol["[components]/[category]/[collection]/page.jsx"]:::server
                CompCat["[components]/[category]/page.jsx"]:::server
                AboutSlug["about/[slug]/page.jsx"]:::server
                BlogSlug["blog/[slug]/page.jsx"]:::server
                BlogIndex["blog/page.jsx"]:::server
            end
        end

        subgraph "API Layer"
            direction TB
            SearchAPI["/api/search/route.js"]:::server
            DBUtil["db.js"]:::server
        end

        subgraph "Utilities"
            direction TB
            Transformer["transformers.js"]:::server
        end

        subgraph "UI Component Library"
            direction TB
            Components["src/components/"]:::client
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        MDXStore["src/data/ (MDX files)"]:::data
        StaticHTML["public/components/"]:::data
    end

    %% Build & Config
    CSS["CSS Build Pipeline (Tailwind/PostCSS)"]:::config
    Config["Configuration & Deployment"]:::config

    %% Connections
    Browser -->|"HTTP GET pages"| Layout
    Browser -->|"AJAX /api/search"| SearchAPI
    Layout -->|reads MDX files| MDXStore
    Layout -->|renders with| Transformer
    Transformer -->|builds UI elements| Components
    Layout -->|embeds previews| StaticHTML
    SearchAPI -->|queries| DBUtil
    DBUtil -->|reads for search| MDXStore
    Layout -->|serves CSS| CSS
    CSS -->|uses| Config

    Layout -->|fallback| NotFound

    %% Responses
    Layout -->|HTML/CSS/JS| Browser
    SearchAPI -->|JSON| Browser

    %% Click events for component mapping
    click Layout "https://github.com/markmead/hyperui/blob/main/app/layout.jsx"
    click Page "https://github.com/markmead/hyperui/blob/main/app/page.jsx"
    click NotFound "https://github.com/markmead/hyperui/blob/main/app/not-found.jsx"
    click CompCol "https://github.com/markmead/hyperui/blob/main/app/[components]/[category]/[collection]/page.jsx"
    click CompCat "https://github.com/markmead/hyperui/blob/main/app/[components]/[category]/page.jsx"
    click AboutSlug "https://github.com/markmead/hyperui/blob/main/app/about/[slug]/page.jsx"
    click BlogSlug "https://github.com/markmead/hyperui/blob/main/app/blog/[slug]/page.jsx"
    click BlogIndex "https://github.com/markmead/hyperui/blob/main/app/blog/page.jsx"
    click Components "https://github.com/markmead/hyperui/tree/main/src/components/"
    click StaticHTML "https://github.com/markmead/hyperui/tree/main/public/components/"
    click MDXStore "https://github.com/markmead/hyperui/tree/main/src/data/"
    click SearchAPI "https://github.com/markmead/hyperui/blob/main/app/api/search/route.js"
    click DBUtil "https://github.com/markmead/hyperui/blob/main/src/utils/db.js"
    click Transformer "https://github.com/markmead/hyperui/blob/main/src/utils/transformers.js"
    click CSS "https://github.com/markmead/hyperui/blob/main/postcss.config.js"
    click Config "https://github.com/markmead/hyperui/blob/main/next.config.js"

    %% Styles
    classDef client fill:#D0E8FF,stroke:#004EAA,color:#004EAA
    classDef server fill:#DFF7DD,stroke:#237A00,color:#237A00
    classDef data fill:#FFF4D0,stroke:#AA6D00,color:#AA6D00
    classDef config fill:#EEEEEE,stroke:#888888,color:#555555
```
