# kevinkoosk/dubsh architecture

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

- Interactive diagram: https://gitdiagram.com/kevinkoosk/dubsh
- Repository: https://github.com/kevinkoosk/dubsh

## Overview

##### Project type and purpose
- Dub is a full‑stack, multi‑tenant SaaS web application: an open‑source link shortener with built‑in analytics, custom domains, QR code generation, and payment/subscription management.
- Built on Next.js (React), deployed on Vercel, using Edge Functions for link redirects/stats, serverless API routes for data operations, Redis (Upstash) as a caching/time‑series store, and MySQL (PlanetScale via Prisma) for core persistent data.

##### Key architectural components
A. Client (Browser / Mobile)
- Next.js React UI (pages in `pages/app`, `pages/home`, `components/…`)
- Tailwind CSS for styling
B. Edge Layer (Vercel Edge Functions)
- Fast redirects, analytics increments, OG image proxy, title fetching (under `pages/api/edge/…`)
- Bypasses full serverless API for performance-critical link resolution
C. Serverless API Layer (Vercel Serverless Functions)
- Auth (NextAuth.js), user/project/link CRUD, domain management, invitations, stats queries, Stripe endpoints (under `pages/api/…`)
- Middleware (`middleware.ts`, `lib/middleware/…`) handles multi‑tenant routing (domain → project)
D. Background/CRON Jobs
- Scheduled tasks (`lib/cron`, `pages/api/cron/…`) for domain verification, usage aggregation
E. Data Stores
1. Redis (Upstash)
– Caching of link → target mapping (`{domain}:{key}`)
– Sorted sets for time‑series analytics (`{domain}:clicks:{key}`, `{domain}:root:clicks`)
2. MySQL (PlanetScale via Prisma)
– Persistent storage of users, projects, link metadata, domain configs, subscription records
F. External Services
- Stripe – payment, subscription management (`lib/stripe`, `pages/api/stripe/…`)
- Vercel Domains API – custom domain provisioning (`pages/api/projects/[slug]/domains/…`)
- Email Provider – transactional emails (welcome, invites) via Next.js email templates (`emails/…`)
- Upstash CRON – optional Redis scheduled tasks if used
G. Utilities & Libraries
- `lib/qr` – QR code generation
- `lib/twitter` – OG/twitter card fetching
- `lib/hooks`, `lib/utils` – shared hooks/helpers

##### Relationships & data flows
1. User → Next.js frontend (SSG/SSR/CSR)
2. Frontend → Serverless API → MySQL (via Prisma) for CRUD (users, projects, links, domains)
3. Frontend → Serverless API → Redis for quick usage/analytics data retrieval
4. External Stripe requests → Serverless API → Stripe SDK → MySQL update
5. Client clicks a short link (ex. `https://mydomain.com/abc`) → Vercel Edge Function
- Edge Function reads mapping from Redis (falls back to MySQL via serverless API if miss)
- Logs click to Redis sorted set
- Redirects to target URL
6. Cron jobs periodically reconcile/cache or verify domain statuses
7. Notifications/emails triggered by serverless functions using email templates

##### Architectural patterns / design principles
- Multi‑tenant routing using Next.js Middleware – domain‑based tenant resolution
- CQRS‑like split: Edge functions handle read‑heavy, latency‑sensitive link resolution; serverless APIs handle writes/CUD
- Cache‑aside pattern for Redis (hot link metadata in Redis, fallback to primary store)
- Micro‑frontend‐style directory separation: `components/app` vs. `components/home` vs. `components/shared`
- Separation of concerns: UI → API → Data → External integrations

##### Detail
- Critical components: middleware, edge vs. serverless, scheduled jobs
- Multi‑tenant design: illustrate domain routing via Middleware
- Caching strategy: Redis as first‑look store for link metadata/analytics

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Browser["Browser (React UI)"]:::ui
        Pages["Next.js Pages"]:::ui
        Components["Components"]:::ui
    end

    %% Edge Layer
    subgraph "Edge Layer"
        direction TB
        EdgeFuncs["Vercel Edge Functions"]:::edge
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        Middleware["Multi-tenant Middleware"]:::api
        APIRoutes["Serverless API Routes"]:::api
    end

    %% Background Jobs
    subgraph "Background Jobs"
        direction TB
        CronLib["CRON Job Libraries"]:::jobs
        CronAPIs["CRON API Endpoints"]:::jobs
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        Redis["Redis (Upstash)"]:::datastore
        MySQL["MySQL (PlanetScale via Prisma)"]:::datastore
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Stripe["Stripe"]:::external
        VercelDomains["Vercel Domains API"]:::external
        EmailSvc["Email Service"]:::external
    end

    %% Data Flows
    Browser -->|"CRUD & Stats"| APIRoutes
    Browser -->|"Link Click"| EdgeFuncs

    EdgeFuncs -->|"Read/Write Mapping"| Redis
    EdgeFuncs -->|"Fallback to API"| APIRoutes
    EdgeFuncs -->|"Redirect to URL"| Browser

    APIRoutes -->|"Read/Write"| MySQL
    APIRoutes -->|"Cache/Stats"| Redis
    APIRoutes -->|"Invoke"| Middleware
    APIRoutes -->|"Stripe Operations"| Stripe
    APIRoutes -->|"Domain Provision"| VercelDomains
    APIRoutes -->|"Send Emails"| EmailSvc

    Stripe -->|"Webhook Events"| APIRoutes

    CronLib -->|"Schedule Trigger"| CronAPIs
    CronAPIs -->|"Verify/Aggregate"| MySQL
    CronAPIs -->|"Cache Updates"| Redis

    %% Middleware flow
    Browser -->|"Tenant Routing"| Middleware
    Middleware --> APIRoutes

    %% Click Events
    click Pages "https://github.com/kevinkoosk/dubsh/tree/main/pages/app"
    click Pages "https://github.com/kevinkoosk/dubsh/tree/main/pages/home"
    click Pages "https://github.com/kevinkoosk/dubsh/blob/main/pages/_app.tsx"
    click Pages "https://github.com/kevinkoosk/dubsh/blob/main/pages/_document.tsx"
    click Components "https://github.com/kevinkoosk/dubsh/tree/main/components/app"
    click Components "https://github.com/kevinkoosk/dubsh/tree/main/components/home"
    click Components "https://github.com/kevinkoosk/dubsh/tree/main/components/layout/app"
    click Components "https://github.com/kevinkoosk/dubsh/tree/main/components/layout/home"
    click Components "https://github.com/kevinkoosk/dubsh/tree/main/components/shared"
    click EdgeFuncs "https://github.com/kevinkoosk/dubsh/tree/main/pages/api/edge"
    click APIRoutes "https://github.com/kevinkoosk/dubsh/tree/main/pages/api"
    click Middleware "https://github.com/kevinkoosk/dubsh/blob/main/middleware.ts"
    click Middleware "https://github.com/kevinkoosk/dubsh/blob/main/lib/middleware/index.ts"
    click Middleware "https://github.com/kevinkoosk/dubsh/blob/main/lib/middleware/app.ts"
    click Middleware "https://github.com/kevinkoosk/dubsh/blob/main/lib/middleware/link.ts"
    click Middleware "https://github.com/kevinkoosk/dubsh/blob/main/lib/middleware/root.ts"
    click Middleware "https://github.com/kevinkoosk/dubsh/blob/main/lib/middleware/utils.ts"
    click CronLib "https://github.com/kevinkoosk/dubsh/blob/main/lib/cron/domains.tsx"
    click CronLib "https://github.com/kevinkoosk/dubsh/blob/main/lib/cron/usage.tsx"
    click CronAPIs "https://github.com/kevinkoosk/dubsh/blob/main/pages/api/cron/domains.ts"
    click CronAPIs "https://github.com/kevinkoosk/dubsh/blob/main/pages/api/cron/links.ts"
    click CronAPIs "https://github.com/kevinkoosk/dubsh/blob/main/pages/api/cron/usage.ts"
    click Redis "https://github.com/kevinkoosk/dubsh/blob/main/lib/upstash.ts"
    click MySQL "https://github.com/kevinkoosk/dubsh/blob/main/lib/prisma.ts"
    click MySQL "https://github.com/kevinkoosk/dubsh/blob/main/prisma/schema.prisma"
    click Stripe "https://github.com/kevinkoosk/dubsh/blob/main/lib/stripe/index.ts"
    click Stripe "https://github.com/kevinkoosk/dubsh/blob/main/lib/stripe/client.ts"
    click Stripe "https://github.com/kevinkoosk/dubsh/blob/main/lib/stripe/constants.ts"
    click Stripe "https://github.com/kevinkoosk/dubsh/blob/main/pages/api/stripe/manage-subscription.ts"
    click Stripe "https://github.com/kevinkoosk/dubsh/blob/main/pages/api/stripe/upgrade.ts"
    click Stripe "https://github.com/kevinkoosk/dubsh/blob/main/pages/api/stripe/webhook.ts"
    click VercelDomains "https://github.com/kevinkoosk/dubsh/tree/main/pages/api/projects/[slug]/domains"
    click EmailSvc "https://github.com/kevinkoosk/dubsh/tree/main/emails"
    click EmailSvc "https://github.com/kevinkoosk/dubsh/tree/main/emails/components"

    %% Styles
    classDef ui fill:#DDEBFF,stroke:#555,stroke-width:1px;
    classDef edge fill:#E0F7EF,stroke:#555,stroke-width:1px;
    classDef api fill:#FFF4E5,stroke:#555,stroke-width:1px;
    classDef jobs fill:#EDEDED,stroke:#555,stroke-width:1px;
    classDef datastore fill:#FFE5E5,stroke:#555,stroke-width:1px;
    classDef external fill:#F1F8E9,stroke:#555,stroke-width:1px;
```
