# e2b-dev/dashboard architecture

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

- Interactive diagram: https://gitdiagram.com/e2b-dev/dashboard
- Repository: https://github.com/e2b-dev/dashboard

## Overview

##### Project Type and Purpose
- This is a full-stack, feature-rich web dashboard built with Next.js 15 + React 19 + TypeScript.
- It exposes a UI for managing “sandboxes”, API keys, usage analytics, billing, team settings, and integrated docs.

##### High-Level Components
Break the system into the following main components:
a. Client (Browser)
b. Next.js Application (Deployed on Vercel)
c. API Layer (Next.js App Router under src/app/api + server logic)
d. Data Stores and External Services
- Supabase Auth & PostgreSQL DB
- Supabase Storage (profile-pictures bucket)
- Redis-compatible KV store (Vercel KV or custom Redis)
- Analytics (PostHog or similar)
e. Supporting Infrastructure
- Vercel platform (Edge functions, CDN, KV integration)
- GitHub for code, CI/CD via GitHub Actions
- Migrations (SQL files under /migrations)

##### Core Architectural Patterns & Design Principles
- **App Router & API Routes**: Next.js app router (src/app) serves both server-rendered pages and API routes under src/app/api.
- **Server-only Logic**: Modules in src/server and data-access clients in src/lib/clients run only on the server (Edge or Node).
- **Shared Code**: UI components (src/ui), feature modules (src/features), and utility code (src/lib/utils) are reused across pages.
- **Partial Prerendering**: Static-generation + server functions using Vercel’s PPR.
- **Type-safe Contracts**: OpenAPI spec (spec/openapi.yaml) and generated DB types.

##### Mapping Relationships & Data Flows
- **User ↔️ Browser UI**: User interacts with React components delivered by Next.js (hydration, client-side navigation).
- **Browser ↔️ Next.js API**: All actions (auth, CRUD on sandboxes, teams, billing, usage metrics) go through Next.js API routes.
- **Next.js API ↔️ Services**:
- Auth flows use Supabase Auth API (callback, confirm, email).
- Data queries/write go to Supabase PostgreSQL (via supabase client) and Redis KV (via Vercel KV client).
- File uploads/downloads use Supabase Storage.
- Usage/analytics calls to PostHog or custom telemetry client.
- **Database Migrations**: Applied manually or via CI against Supabase DB before deployment.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client (Browser)"
        direction TB
        Browser["Browser (React UI)"]:::frontend
        UI["UI Components<br/>(src/ui)"]:::frontend
        Features["Feature Modules<br/>(src/features)"]:::frontend
        AppDir["App Router Pages<br/>(src/app)"]:::frontend
    end

    %% Next.js Application on Vercel
    subgraph "Next.js Application (Vercel)"
        direction TB
        SSR["SSR Pages & Client Components<br/>(src/app)"]:::frontend
        API["API Routes<br/>(src/app/api)"]:::backend
        Middleware["Middleware<br/>(src/middleware.ts,<br/>src/server/middleware.ts)"]:::backend
        EnvVars["Env Variables<br/>(.env.example,<br/>src/lib/env.ts)"]:::backend
        StaticAssets["Static Assets<br/>(public/,<br/>readme-assets/)"]:::backend
        ServerLogic["Server-Only Logic<br/>(src/server & src/lib/clients)"]:::backend
    end

    %% External Services & Infrastructure
    subgraph "External Services & Infrastructure"
        direction TB
        Vercel["Vercel Platform<br/>(Edge Functions, CDN, KV)"]:::infra
        GitHubCI["GitHub CI/CD<br/>(.github/workflows/test.yml)"]:::infra
        Migrations["DB Migrations<br/>(migrations/*.sql)"]:::infra
        subgraph "Supabase"
            direction TB
            SupabaseAuth["Auth Service"]:::external
            SupabaseDB["PostgreSQL Database"]:::db
            SupabaseStorage["Storage Bucket<br/>(profile-pictures)"]:::external
        end
        KVStore["Redis-compatible KV Store"]:::cache
        Analytics["Analytics / Telemetry"]:::external
    end

    %% Connections
    Browser -->|"hydrates & navigates"| SSR
    Browser -->|"API calls (HTTPS/REST)"| API
    AppDir -->|serves pages| Browser
    SSR -->|renders pages| Browser
    API -->|"routes requests"| ServerLogic
    Middleware -->|"pre-process"| API
    EnvVars -->|provides secrets| ServerLogic
    StaticAssets -->|serves files| Browser

    ServerLogic -->|"auth flows via"| SupabaseAuth
    ServerLogic -->|"queries & writes via"| SupabaseDB
    ServerLogic -->|"uploads/downloads via"| SupabaseStorage
    ServerLogic -->|"caches via"| KVStore
    ServerLogic -.->|"events"| Analytics
    Migrations -->|"apply migrations"| SupabaseDB

    GitHubCI -->|CI triggers| Vercel
    Vercel -->|deploys| SSR
    Vercel -->|deploys| API
    Vercel -->|KV integration| KVStore

    %% Click Events
    click AppDir "https://github.com/e2b-dev/dashboard/tree/main/src/app"
    click UI "https://github.com/e2b-dev/dashboard/tree/main/src/ui"
    click Features "https://github.com/e2b-dev/dashboard/tree/main/src/features"
    click SSR "https://github.com/e2b-dev/dashboard/tree/main/src/app"
    click API "https://github.com/e2b-dev/dashboard/tree/main/src/app/api"
    click ServerLogic "https://github.com/e2b-dev/dashboard/tree/main/src/lib/clients"
    click ServerLogic "https://github.com/e2b-dev/dashboard/tree/main/src/server"
    click SupabaseAuth "https://github.com/e2b-dev/dashboard/blob/main/src/lib/clients/supabase/client.ts"
    click SupabaseAuth "https://github.com/e2b-dev/dashboard/blob/main/src/lib/clients/supabase/server.ts"
    click SupabaseAuth "https://github.com/e2b-dev/dashboard/blob/main/src/lib/clients/supabase/admin.ts"
    click SupabaseStorage "https://github.com/e2b-dev/dashboard/blob/main/src/lib/clients/storage.ts"
    click KVStore "https://github.com/e2b-dev/dashboard/blob/main/src/lib/clients/kv.ts"
    click Analytics "https://github.com/e2b-dev/dashboard/blob/main/src/lib/clients/meter.ts"
    click Analytics "https://github.com/e2b-dev/dashboard/blob/main/src/instrumentation.ts"
    click Analytics "https://github.com/e2b-dev/dashboard/blob/main/src/instrumentation.node.ts"
    click Analytics "https://github.com/e2b-dev/dashboard/blob/main/src/lib/hooks/use-analytics.ts"
    click Migrations "https://github.com/e2b-dev/dashboard/tree/main/migrations/"
    click GitHubCI "https://github.com/e2b-dev/dashboard/blob/main/.github/workflows/test.yml"
    click EnvVars "https://github.com/e2b-dev/dashboard/blob/main/.env.example"
    click EnvVars "https://github.com/e2b-dev/dashboard/blob/main/src/lib/env.ts"
    click Middleware "https://github.com/e2b-dev/dashboard/blob/main/src/middleware.ts"
    click Middleware "https://github.com/e2b-dev/dashboard/blob/main/src/server/middleware.ts"
    click StaticAssets "https://github.com/e2b-dev/dashboard/tree/main/public/"
    click StaticAssets "https://github.com/e2b-dev/dashboard/tree/main/readme-assets/"
    click Vercel "https://github.com/e2b-dev/dashboard/blob/main/vercel.json"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#3399ff,color:#003366;
    classDef backend fill:#d4edda,stroke:#28a745,color:#155724;
    classDef external fill:#fff3cd,stroke:#ffcc00,color:#664d03;
    classDef infra fill:#e2e3e5,stroke:#6c757d,color:#495057;
    classDef db fill:#f8d7da,stroke:#dc3545,color:#721c24,stroke-dasharray: 5 5;
    classDef cache fill:#d1ecf1,stroke:#17a2b8,color:#0c5460;
```
