# grillsdev/grills architecture

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

- Interactive diagram: https://gitdiagram.com/grillsdev/grills
- Repository: https://github.com/grillsdev/grills

## Overview

##### Project Type & Purpose
- Full-stack, server-rendered web application built on Next.js (App Router) and TypeScript.
- Purpose: a “Your Own Gen UI Platform” that generates unstyled UI code via LLMs, previews it in a sandbox, and lets users copy-and-paste into their own projects.
- Key features: AI chat UI, code-generation sandbox (E2B), pluggable LLM backends, Drizzle/Cloudflare Hyperdrive DB, optional Redis, and Cloudflare Workers edge runtime.

##### Main Components
A. Client / Browser (React)
– Next.js pages & server components under src/app and src/components.
– UI sub-systems: Chat interface, Home/marketing pages, ShadCN-style unstyled components.
B. Next.js Server & API Layer
– App Router under src/app handles SSR/SSG and API endpoints under src/app/api (auth, completion, sandbox, theme).
– Middleware (src/middleware.ts) for auth checks.
C. E2B Sandbox Service
– e2b-nextjs-sandbox-template directory: Docker-based service that spins up a preview container of generated UI code.
– Controlled via a REST endpoint (src/app/api/sandbox/route.ts).
D. Database & ORM
– Postgres (LOCAL_DB_URL) managed via Drizzle ORM (drizzle.config.ts, drizzle.db.config.ts).
– Cloudflare Hyperdrive binding (wrangler.toml/jsonc) for production edge DB.
– Migrations & schema files under src/db.
E. Cache & Session Store (optional)
– Upstash Redis for caching, rate-limiting, session store (configured via .env).
F. External Services
– LLM providers (OpenAI, Anthropic, etc.) called from src/lib/fetchers.ts.
– OAuth (Google) and Better-Auth for user authentication.
– Cloudflare Workers runtime (via wrangler) for edge deployment.

##### Component Relationships & Data Flows
1. User Browser → Next.js Frontend
- Fetch SSR pages, static assets (public/*).
- Client-side React calls API routes.
2. Next.js API Routes → Business Logic
- Auth route invokes Better-Auth and/or Google OAuth.
- Completion routes call LLM fetchers, apply reasoning, store/retrieve chats in Postgres.
- Sandbox route triggers E2B service and streams sandbox progress to the client.
- Theme route persists user theme preferences in DB or Redis.
3. API → Database (Drizzle ORM)
- Reads/writes chat history, user models, theme settings.
- Migrations keep schema in sync.
4. API → External LLMs
- src/lib/fetchers.ts abstracts provider calls.
5. API → E2B Sandbox Service
- Launches preview containers via Docker; streams logs/status.
6. Deployment
- Next.js and API routes deployed as Cloudflare Workers (edge functions).
- Cloudflare Hyperdrive provides the Postgres binding at edge.
- Wrangler config manages local vs. production DB connections.

##### Important Architectural Patterns
- Server Components + Client Components (Next.js App Router)
- Serverless / Edge Functions (Cloudflare Workers)
- Micro-service for E2B sandbox (isolated Docker container)
- ORM + Migrations (Drizzle) with a hybrid local/postgres-edge strategy
- Pluggable adapters for LLM providers (strategy pattern in src/lib/fetchers.ts)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Top Layer: Client
    subgraph "Client / Browser (React)" 
        direction TB
        ChatInterface["Chat Interface"]:::frontend
        HomePages["Home / Marketing Pages"]:::frontend
        UIComponents["Unstyled ShadCN UI Components"]:::frontend
    end

    %% Middle Layer: Next.js App (Edge)
    subgraph "Next.js App (UI + Server/API) - Cloudflare Workers" 
        direction TB
        SSR["SSR/SSG Pages & Layout"]:::backend
        subgraph "API Endpoints"
            direction TB
            AuthAPI["Auth API"]:::api
            CompletionAPI["Completion API"]:::api
            SandboxAPI["Sandbox API"]:::api
            ThemeAPI["Theme API"]:::api
        end
        Middleware["Auth Middleware"]:::backend
    end

    %% E2B Sandbox Microservice
    E2BSandbox["E2B Sandbox Service (Docker)"]:::microservice

    %% Data Stores
    subgraph "Data Layer"
        direction TB
        Postgres["Postgres (Drizzle ORM)"]:::db
        RedisCache["Upstash Redis (Cache & Session)"]:::cache
    end

    %% External Services
    subgraph "External Services"
        direction TB
        LLMGateway["LLM Providers Gateway"]:::external
        ModelsRegistry["Pluggable Models Registry"]:::external
        OAuthService["OAuth / Better-Auth"]:::external
        PromptMgmt["Prompt Management"]:::external
    end

    %% Deployment & Config
    subgraph "Deployment & Config"
        direction TB
        CloudflareConfig["Cloudflare Workers Config"]:::config
        NextConfig["Next.js Edge Config"]:::config
    end

    %% Data Flows
    ChatInterface -->|"fetch pages / assets"| SSR
    HomePages -->|"fetch pages / assets"| SSR
    UIComponents --> SSR

    SSR -->|"API calls"| AuthAPI
    SSR -->|"API calls"| CompletionAPI
    SSR -->|"API calls"| SandboxAPI
    SSR -->|"API calls"| ThemeAPI

    AuthAPI -->|"auth checks"| Middleware
    CompletionAPI -->|"DB read/write"| Postgres
    CompletionAPI -->|"LLM calls"| LLMGateway
    SandboxAPI -->|"trigger preview"| E2BSandbox
    ThemeAPI -->|"DB read/write"| Postgres

    AuthAPI -->|"OAuth flow"| OAuthService
    AuthAPI -->|"session store"| RedisCache

    LLMGateway -->|"use models"| ModelsRegistry
    PromptMgmt --> LLMGateway

    E2BSandbox -->|"streams logs"| SandboxAPI

    Postgres -->|"migrations/schema"| DrizzleConfig
    RedisCache -->|"env config"| RedisCache

    AuthAPI -->|"prompt templates"| PromptMgmt

    %% Deployment Flows
    SSR --> CloudflareConfig
    AuthAPI --> CloudflareConfig
    CompletionAPI --> CloudflareConfig
    SandboxAPI --> CloudflareConfig
    ThemeAPI --> CloudflareConfig

    CloudflareConfig --> NextConfig

    %% Click Events
    click ChatInterface "https://github.com/grillsdev/grills/tree/main/src/app/(chat)"
    click HomePages "https://github.com/grillsdev/grills/tree/main/src/app/home"
    click UIComponents "https://github.com/grillsdev/grills/tree/main/src/components/ui"
    click AuthAPI "https://github.com/grillsdev/grills/blob/main/src/app/api/auth/[...all]/route.ts"
    click CompletionAPI "https://github.com/grillsdev/grills/blob/main/src/app/api/completion/route.ts"
    click SandboxAPI "https://github.com/grillsdev/grills/blob/main/src/app/api/sandbox/route.ts"
    click ThemeAPI "https://github.com/grillsdev/grills/blob/main/src/app/api/theme/route.ts"
    click Middleware "https://github.com/grillsdev/grills/blob/main/src/middleware.ts"
    click E2BSandbox "https://github.com/grillsdev/grills/tree/main/e2b-nextjs-sandox-template/"
    click Postgres "https://github.com/grillsdev/grills/blob/main/drizzle.config.ts"
    click RedisCache "https://github.com/grillsdev/grills/blob/main/.example.env"
    click LLMGateway "https://github.com/grillsdev/grills/blob/main/src/lib/fetchers.ts"
    click ModelsRegistry "https://github.com/grillsdev/grills/blob/main/src/lib/models.ts"
    click OAuthService "https://github.com/grillsdev/grills/blob/main/src/lib/auth-client.ts"
    click PromptMgmt "https://github.com/grillsdev/grills/blob/main/src/lib/prompt.ts"
    click CloudflareConfig "https://github.com/grillsdev/grills/blob/main/wrangler.toml"
    click NextConfig "https://github.com/grillsdev/grills/blob/main/next.config.ts"

    %% Styles
    classDef frontend fill:#AEDFF7,stroke:#0277BD,stroke-width:2px
    classDef backend fill:#C8E6C9,stroke:#388E3C,stroke-width:2px
    classDef api fill:#FFE0B2,stroke:#F57C00,stroke-width:2px
    classDef microservice fill:#E1BEE7,stroke:#8E24AA,stroke-width:2px
    classDef db fill:#FFCCBC,stroke:#D84315,stroke-width:2px
    classDef cache fill:#D1C4E9,stroke:#5E35B1,stroke-width:2px
    classDef external fill:#F0F4C3,stroke:#AFB42B,stroke-width:2px
    classDef config fill:#CFD8DC,stroke:#455A64,stroke-width:2px
```
