# nutlope/qrgpt architecture

> Architecture diagram of the GitHub repository nutlope/qrgpt, 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/nutlope/qrgpt
- Repository: https://github.com/nutlope/qrgpt

## Overview

##### Project Type and Purpose
- This is a full-stack web application built on Next.js (App Router) that lets users generate AI-powered QR codes in seconds.
- It combines a server-rendered/frontend UI with serverless API routes that call an external AI model (Replicate), and uses Vercel Blob and KV for storage and rate-limiting.

##### File Structure
- Top-level “app/” directory follows Next.js App Router:
– app/page.tsx: marketing/home page
– app/start/[id]/page.tsx & app/start/page.tsx: code-generation flow
– app/waitlist/page.tsx: waitlist signup
– app/api/generate/route.ts: serverless API endpoint
- “components/” contains UI primitives (Shadcn UI + custom components)
- “utils/” holds services & clients: ReplicateClient.ts, downloadQrCode.ts, env.ts, service.ts, types.ts
- Config files: next.config.js, postcss.config.js, tailwind.config.js, tsconfig.json

##### README Insights
- Tech Stack: Next.js App Router, Replicate (AI), Vercel Blob (image storage), Vercel KV (Redis-style storage + rate limiting), Shadcn UI
- Deployment on Vercel with environment variables for Replicate API key, KV namespace, Blob bucket

##### Main Components & Their Interactions
a. Client Browser (React/Next.js frontend)
b. Next.js Serverless Layer (app/api/generate)
c. External AI Service (Replicate)
d. Vercel Blob Storage (stores generated QR images)
e. Vercel KV Storage (stores usage counts, rate-limits, waitlist data)
f. Static Assets & UI Components

Interaction flow:
1. User clicks “Generate” on frontend → POST request to `/api/generate`.
2. Next.js route handler reads env (utils/env), checks rate-limit in KV (utils/service).
3. Handler invokes ReplicateClient (utils/ReplicateClient) → calls external Replicate API.
4. On image result, handler writes image to Vercel Blob → obtains Blob URL.
5. Handler persists any metadata or increments usage counters in Vercel KV.
6. Handler returns QR-code URL to frontend.
7. Frontend displays image (components/QrCard.tsx) and offers download (utils/downloadQrCode).

##### Architectural Patterns & Design Principles
- Serverless micro-endpoints (Next.js API routes)
- Separation of concerns: UI vs. service logic (utils folder)
- 12-factor app: environment config (example.env, env.ts)
- Component-based UI (Shadcn + custom)
- Scalability via external managed services (Replicate, Vercel Blob & KV)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Browser Layer
    subgraph "Client (Browser)"
        direction TB
        Home["Home Page<br>app/page.tsx"]:::frontend
        Start["Start Page<br>app/start/page.tsx"]:::frontend
        StartDetail["Start Detail Page<br>app/start/[id]/page.tsx"]:::frontend
        Waitlist["Waitlist Page<br>app/waitlist/page.tsx"]:::frontend

        subgraph "UI Components"
            direction TB
            QrCard["QrCard<br>components/QrCard.tsx"]:::frontend
            Body["Body<br>components/Body.tsx"]:::frontend
            CTA["CTA<br>components/CTA.tsx"]:::frontend
            Footer["Footer<br>components/Footer.tsx"]:::frontend
            GradientWrapper["GradientWrapper<br>components/GradientWrapper.tsx"]:::frontend
            Hero["Hero<br>components/Hero.tsx"]:::frontend
            NavLink["NavLink<br>components/NavLink.tsx"]:::frontend
            Navbar["Navbar<br>components/Navbar.tsx"]:::frontend
            PromptSuggestion["PromptSuggestion<br>components/PromptSuggestion.tsx"]:::frontend
            Testimonials["Testimonials<br>components/Testimonials.tsx"]:::frontend
            ButtonUI["Button UI<br>components/ui/button.tsx"]:::frontend
            FormUI["Form UI<br>components/ui/form.tsx"]:::frontend
            InputUI["Input UI<br>components/ui/input.tsx"]:::frontend
            LabelUI["Label UI<br>components/ui/label.tsx"]:::frontend
            TextareaUI["Textarea UI<br>components/ui/textarea.tsx"]:::frontend
            LoadingDots["LoadingDots UI<br>components/ui/loadingdots.tsx"]:::frontend
            PublicAssets["Static Assets<br>public/"]:::frontend
        end

        subgraph "Frontend Utilities"
            direction TB
            DownloadHelper["downloadQrCode<br>utils/downloadQrCode.ts"]:::frontend
        end
    end

    %% Serverless Functions Layer
    subgraph "Serverless Functions (Next.js API)"
        direction TB
        API["Generate API<br>app/api/generate/route.ts"]:::backend
        Env["Env Config<br>utils/env.ts<br>.example.env"]:::backend
        ServiceLogic["Service Logic<br>utils/service.ts"]:::backend
        Types["Type Definitions<br>utils/types.ts"]:::backend
        ReplicateClient["ReplicateClient<br>utils/ReplicateClient.ts"]:::backend
    end

    %% External Services
    Replicate["Replicate AI Service"]:::external
    BlobStorage["Vercel Blob Storage"]:::storage
    KVStorage["Vercel KV Storage"]:::storage

    %% Data Flows
    Start -->|"POST /api/generate"| API
    StartDetail -->|"POST /api/generate"| API
    Waitlist -->|"GET /api/generate"| API
    API -->|"reads env"| Env
    API -->|"uses service logic"| ServiceLogic
    API -->|"calls ReplicateClient"| ReplicateClient
    ReplicateClient -->|"calls external API"| Replicate
    Replicate -->|"returns image data"| ReplicateClient
    API -->|"store image"| BlobStorage
    API -->|"read/write usage"| KVStorage
    API -->|"returns URL"| QrCard

    %% Click Events
    click Home "https://github.com/nutlope/qrgpt/blob/main/app/page.tsx"
    click Start "https://github.com/nutlope/qrgpt/blob/main/app/start/page.tsx"
    click StartDetail "https://github.com/nutlope/qrgpt/blob/main/app/start/[id]/page.tsx"
    click Waitlist "https://github.com/nutlope/qrgpt/blob/main/app/waitlist/page.tsx"
    click QrCard "https://github.com/nutlope/qrgpt/blob/main/components/QrCard.tsx"
    click Body "https://github.com/nutlope/qrgpt/blob/main/components/Body.tsx"
    click CTA "https://github.com/nutlope/qrgpt/blob/main/components/CTA.tsx"
    click Footer "https://github.com/nutlope/qrgpt/blob/main/components/Footer.tsx"
    click GradientWrapper "https://github.com/nutlope/qrgpt/blob/main/components/GradientWrapper.tsx"
    click Hero "https://github.com/nutlope/qrgpt/blob/main/components/Hero.tsx"
    click NavLink "https://github.com/nutlope/qrgpt/blob/main/components/NavLink.tsx"
    click Navbar "https://github.com/nutlope/qrgpt/blob/main/components/Navbar.tsx"
    click PromptSuggestion "https://github.com/nutlope/qrgpt/blob/main/components/PromptSuggestion.tsx"
    click Testimonials "https://github.com/nutlope/qrgpt/blob/main/components/Testimonials.tsx"
    click ButtonUI "https://github.com/nutlope/qrgpt/blob/main/components/ui/button.tsx"
    click FormUI "https://github.com/nutlope/qrgpt/blob/main/components/ui/form.tsx"
    click InputUI "https://github.com/nutlope/qrgpt/blob/main/components/ui/input.tsx"
    click LabelUI "https://github.com/nutlope/qrgpt/blob/main/components/ui/label.tsx"
    click TextareaUI "https://github.com/nutlope/qrgpt/blob/main/components/ui/textarea.tsx"
    click LoadingDots "https://github.com/nutlope/qrgpt/blob/main/components/ui/loadingdots.tsx"
    click PublicAssets "https://github.com/nutlope/qrgpt/tree/main/public/"
    click DownloadHelper "https://github.com/nutlope/qrgpt/blob/main/utils/downloadQrCode.ts"
    click API "https://github.com/nutlope/qrgpt/blob/main/app/api/generate/route.ts"
    click Env "https://github.com/nutlope/qrgpt/blob/main/utils/env.ts"
    click ServiceLogic "https://github.com/nutlope/qrgpt/blob/main/utils/service.ts"
    click Types "https://github.com/nutlope/qrgpt/blob/main/utils/types.ts"
    click ReplicateClient "https://github.com/nutlope/qrgpt/blob/main/utils/ReplicateClient.ts"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,stroke-width:1px;
    classDef backend fill:#DFFFE0,stroke:#28a745,stroke-width:1px;
    classDef external fill:#FFE8CC,stroke:#d97706,stroke-width:1px;
    classDef storage fill:#E0F7FF,stroke:#036d6f,stroke-width:1px;
```
