# leo-expose/pesto architecture

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

- Interactive diagram: https://gitdiagram.com/leo-expose/pesto
- Repository: https://github.com/leo-expose/pesto

## Overview

1. **Overall shape**
   - Pesto is a **Next.js App Router** application that combines a public pastebin, authenticated user areas, an admin console, and a first-run setup wizard in one repo.
   - The runtime is split between **React server components / route handlers / server actions** and smaller client-side islands for interactive editors, tables, prompts, and theme controls.

2. **Main user-facing boundaries**
   - The `app/(auth)` group handles authentication screens, mainly the login flow.
   - The `app/(app)` group contains the authenticated product surface: home, new paste, personal pastes, settings, admin, and individual paste pages.
   - Public read paths exist outside that boundary, including `/p/[alias]` for the formatted paste view and `/raw/[alias]` for plain text access.

3. **Persistence layer**
   - PostgreSQL is the primary datastore, accessed through **Drizzle ORM**.
   - `lib/db/schema.ts` defines the domain tables, while `lib/db/index.ts` is the database entry point used by route handlers and server actions.
   - The database is central to users, pastes, versions, settings, and setup state.

4. **Paste lifecycle**
   - Paste creation and updates flow through the app’s paste forms and API handlers in `app/api/pastes`.
   - Individual paste pages render from the alias parameter, with support for **version history**, **password protection**, **burn-after-reading**, and theme selection.
   - A separate `/raw/[alias]` route serves unformatted content, indicating a clean split between presentation rendering and source retrieval.

5. **Authentication and identity**
   - Auth is implemented with **Auth.js v5** via `app/api/auth/[...nextauth]/route.ts`, backed by `auth.ts` and `auth.config.ts`.
   - The login path supports credentials and optional OAuth providers, with provider toggles managed from the admin side.
   - `types/next-auth.d.ts` extends session/user typing for the app’s auth model.

6. **Admin and instance control**
   - The admin console lives under `app/(app)/admin` and is backed by server actions plus client components like `AdminClient`.
   - It governs instance-wide behavior such as user management, registration/provider settings, and the default syntax theme.
   - This is a distinct operational boundary from normal paste usage: it changes global configuration rather than user content.

7. **Setup mode as a separate operational phase**
   - First-run installation is intentionally isolated behind `SETUP_MODE=true`.
   - Setup routes under `app/setup` and `app/api/setup/*` handle database testing, schema push, environment bootstrapping, and creation of the first admin account.
   - The README makes clear this is a **temporary provisioning mode**, not normal runtime behavior.

8. **Security and access control**
   - Setup access is constrained by explicit checks in `lib/setupAccess.ts`, `lib/setupState.ts`, and related helpers, with additional admin/setup logic in `lib/setupAdmin.ts`.
   - The application also has standard auth-based access control for user areas and admin-only routes.
   - Password-protected pastes add a second content-level gate separate from account login.

9. **Server-side business logic**
   - Most domain rules are concentrated in `lib/`: alias generation, markdown handling, syntax highlighting, language detection, themes, settings, validation, and paste-specific helpers.
   - `lib/highlight.ts`, `lib/markdown.ts`, `lib/language.ts`, and `lib/themes.ts` are especially important to the rendering pipeline.
   - `lib/validators.ts` and `lib/utils.ts` likely serve as shared policy and formatting layers across routes and actions.

10. **Rendering and editing experience**
   - The editor stack uses **CodeMirror 6**, surfaced through the “new paste” page and related client components.
   - Read views use `PasteViewer`, `PasteCard`, `VersionHistory`, `PasswordPrompt`, and `VisibilityBadge` to compose the paste experience.
   - The app theme UI is separate from syntax highlighting: `ThemeProvider` and `ThemePicker` manage chrome/theme preferences, while Shiki-backed syntax themes control code rendering.

11. **API surface**
   - The API is fairly broad and maps to product subsystems: pastes, paste versions, user pastes, settings, themes, uploads, health, auth, and setup.
   - `app/api/cron/cleanup/route.ts` indicates a scheduled maintenance path, likely for expiring or deleting burn-after-reading content and other cleanup tasks.
   - `app/api/upload/route.ts` suggests attachment or media handling is a distinct service boundary from paste text creation.

12. **Rate limiting and external dependencies**
   - Paste creation can use **Upstash Redis** for shared rate limiting, with an in-memory fallback in `lib/ratelimit-fallback.ts`.
   - This means abuse protection is designed to work both in distributed deployments and in a single-node/self-hosted fallback mode.
   - The main external dependencies that materially affect architecture are PostgreSQL, Auth.js providers, and optional Redis; everything else is internal to the Next.js app.

13. **Operational and deployment split**
   - The repo includes scripts for setup, production start, database bootstrapping, and Next.js cleanup, which reinforces that installation and runtime are intentionally separated.
   - `instrumentation.ts` and `proxy.ts` indicate request-level runtime hooks and edge/proxy behavior, while `next.config.ts` and `drizzle.config.ts` tie build-time and schema tooling into the application.
   - Overall, the system is a self-hosted monolith with clear internal boundaries: setup/provisioning, auth, paste CRUD, admin/config, and public read access.

Main entry points: [`lib/settings.ts`](https://github.com/leo-expose/pesto/blob/main/lib/settings.ts) (State & policy), [`lib/db/index.ts`](https://github.com/leo-expose/pesto/blob/main/lib/db/index.ts) (Database layer), [`lib/paste.ts`](https://github.com/leo-expose/pesto/blob/main/lib/paste.ts) (Paste logic), [`lib/setupAccess.ts`](https://github.com/leo-expose/pesto/blob/main/lib/setupAccess.ts) (Access control)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["App surfaces"]
  node_node_app_root["App shell<br/>Next.js layout<br/>[layout.tsx]"]
  node_node_app_public["Public read<br/>Route group<br/>[page.tsx]"]
  node_node_app_authenticated["User area<br/>Route group<br/>[page.tsx]"]
  node_node_app_admin["Admin console<br/>Admin surface<br/>[page.tsx]"]
  node_node_app_auth["Login flow<br/>Auth route group<br/>[page.tsx]"]
  node_node_app_setup["Setup wizard<br/>Provisioning flow<br/>[page.tsx]"]
end

subgraph group_group_api["API layer"]
  node_node_api_auth["Auth API<br/>Auth.js route<br/>[route.ts]"]
  node_node_api_pastes["Paste API<br/>Paste routes<br/>[route.ts]"]
  node_node_api_settings["Settings API<br/>Config routes<br/>[route.ts]"]
  node_node_api_upload["Upload API<br/>Upload route<br/>[route.ts]"]
  node_node_api_setup["Setup API<br/>Bootstrap routes<br/>[route.ts]"]
  node_node_api_maintenance["Health & cleanup<br/>Ops routes<br/>[route.ts]"]
end

subgraph group_group_lib["Core logic"]
  node_node_lib_db[("Database layer<br/>Drizzle/Postgres<br/>[index.ts]")]
  node_node_lib_paste["Paste logic<br/>Domain rules<br/>[paste.ts]"]
  node_node_lib_render["Render pipeline<br/>Markdown/highlight<br/>[markdown.ts]"]
  node_node_lib_auth_setup["Access control<br/>Auth/setup guards<br/>[setupAccess.ts]"]
  node_node_lib_state["State & policy<br/>Shared policy<br/>[settings.ts]"]
end

subgraph group_group_components["UI components"]
  node_node_ui_layout["Navigation UI<br/>Shared UI<br/>[Navbar.tsx]"]
  node_node_ui_paste["Paste UI<br/>Shared UI<br/>[PasteViewer.tsx]"]
  node_node_ui_form["Form controls<br/>Shared UI<br/>[Button.tsx]"]
end

subgraph group_group_ops["Runtime & tooling"]
  node_node_ops_config["Tooling<br/>Build/runtime<br/>[next.config.ts]"]
end

node_node_app_root -->|"uses"| node_node_ui_layout
node_node_app_public -->|"renders"| node_node_ui_paste
node_node_app_authenticated -->|"uses"| node_node_ui_paste
node_node_app_admin -->|"uses"| node_node_ui_form
node_node_app_auth -->|"uses"| node_node_ui_form
node_node_app_setup -->|"uses"| node_node_ui_form
node_node_app_authenticated -->|"depends on"| node_node_lib_paste
node_node_app_public -->|"depends on"| node_node_lib_render
node_node_app_admin -->|"guards"| node_node_lib_auth_setup
node_node_app_auth -->|"calls"| node_node_api_auth
node_node_app_setup -->|"calls"| node_node_api_setup
node_node_api_auth -->|"auth"| node_node_lib_auth_setup
node_node_api_pastes -->|"business logic"| node_node_lib_paste
node_node_api_pastes -->|"persists"| node_node_lib_db
node_node_api_settings -->|"policy"| node_node_lib_state
node_node_api_setup -->|"bootstrap"| node_node_lib_db
node_node_api_maintenance -->|"maintenance"| node_node_lib_state
node_node_lib_paste -->|"stores"| node_node_lib_db
node_node_lib_render -->|"config"| node_node_lib_state
node_node_lib_auth_setup -->|"checks"| node_node_lib_state
node_node_lib_state -->|"reads/writes"| node_node_lib_db
node_node_ops_config -->|"hosts"| node_node_api_maintenance
node_node_ops_config -->|"tooling"| node_node_lib_db

click node_node_app_root "https://github.com/leo-expose/pesto/blob/main/app/layout.tsx"
click node_node_app_public "https://github.com/leo-expose/pesto/blob/main/app/(app)/p/[alias]/page.tsx"
click node_node_app_authenticated "https://github.com/leo-expose/pesto/blob/main/app/(app)/page.tsx"
click node_node_app_admin "https://github.com/leo-expose/pesto/blob/main/app/(app)/admin/page.tsx"
click node_node_app_auth "https://github.com/leo-expose/pesto/blob/main/app/(auth)/login/page.tsx"
click node_node_app_setup "https://github.com/leo-expose/pesto/blob/main/app/setup/page.tsx"
click node_node_api_auth "https://github.com/leo-expose/pesto/blob/main/app/api/auth/[...nextauth]/route.ts"
click node_node_api_pastes "https://github.com/leo-expose/pesto/blob/main/app/api/pastes/route.ts"
click node_node_api_settings "https://github.com/leo-expose/pesto/blob/main/app/api/settings/route.ts"
click node_node_api_upload "https://github.com/leo-expose/pesto/blob/main/app/api/upload/route.ts"
click node_node_api_setup "https://github.com/leo-expose/pesto/blob/main/app/api/setup/test-db/route.ts"
click node_node_api_maintenance "https://github.com/leo-expose/pesto/blob/main/app/api/health/route.ts"
click node_node_lib_db "https://github.com/leo-expose/pesto/blob/main/lib/db/index.ts"
click node_node_lib_paste "https://github.com/leo-expose/pesto/blob/main/lib/paste.ts"
click node_node_lib_render "https://github.com/leo-expose/pesto/blob/main/lib/markdown.ts"
click node_node_lib_auth_setup "https://github.com/leo-expose/pesto/blob/main/lib/setupAccess.ts"
click node_node_lib_state "https://github.com/leo-expose/pesto/blob/main/lib/settings.ts"
click node_node_ui_layout "https://github.com/leo-expose/pesto/blob/main/components/layout/Navbar.tsx"
click node_node_ui_paste "https://github.com/leo-expose/pesto/blob/main/components/paste/PasteViewer.tsx"
click node_node_ui_form "https://github.com/leo-expose/pesto/blob/main/components/ui/Button.tsx"
click node_node_ops_config "https://github.com/leo-expose/pesto/blob/main/next.config.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_app_root,node_node_app_public,node_node_app_authenticated,node_node_app_admin,node_node_app_auth,node_node_app_setup toneBlue
class node_node_api_auth,node_node_api_pastes,node_node_api_settings,node_node_api_upload,node_node_api_setup,node_node_api_maintenance toneAmber
class node_node_lib_db,node_node_lib_paste,node_node_lib_render,node_node_lib_auth_setup,node_node_lib_state toneMint
class node_node_ui_layout,node_node_ui_paste,node_node_ui_form toneRose
class node_node_ops_config toneIndigo
```

## Components

### App surfaces

Next.js route groups and page-level product surfaces.

- [App shell](https://github.com/leo-expose/pesto/blob/main/app/layout.tsx): Next.js layout · Global app layout and shared chrome for the runtime. · `app/layout.tsx`
- [Public read](https://github.com/leo-expose/pesto/blob/main/app/(app)/p/[alias]/page.tsx): Route group · Public paste rendering and raw content access. · `app/(app)/p/[alias]/page.tsx`
- [User area](https://github.com/leo-expose/pesto/blob/main/app/(app)/page.tsx): Route group · Authenticated product surface for creating and managing pastes. · `app/(app)/page.tsx`
- [Admin console](https://github.com/leo-expose/pesto/blob/main/app/(app)/admin/page.tsx): Admin surface · Instance-wide settings and user management UI. · `app/(app)/admin/page.tsx`
- [Login flow](https://github.com/leo-expose/pesto/blob/main/app/(auth)/login/page.tsx): Auth route group · Sign-in screens and login actions. · `app/(auth)/login/page.tsx`
- [Setup wizard](https://github.com/leo-expose/pesto/blob/main/app/setup/page.tsx): Provisioning flow · First-run installation and bootstrap UI. · `app/setup/page.tsx`

### API layer

Route handlers for product, auth, setup, and maintenance workflows.

- [Auth API](https://github.com/leo-expose/pesto/blob/main/app/api/auth/[...nextauth]/route.ts): Auth.js route · NextAuth handler for sessions and provider sign-in. · `app/api/auth/[...nextauth]/route.ts`
- [Paste API](https://github.com/leo-expose/pesto/blob/main/app/api/pastes/route.ts): Paste routes · Create, read, update, and version paste endpoints. · `app/api/pastes/route.ts`
- [Settings API](https://github.com/leo-expose/pesto/blob/main/app/api/settings/route.ts): Config routes · Instance and user settings endpoints. · `app/api/settings/route.ts`
- [Upload API](https://github.com/leo-expose/pesto/blob/main/app/api/upload/route.ts): Upload route · Attachment or media upload boundary. · `app/api/upload/route.ts`
- [Setup API](https://github.com/leo-expose/pesto/blob/main/app/api/setup/test-db/route.ts): Bootstrap routes · Database test, schema push, and setup completion endpoints. · `app/api/setup/test-db/route.ts`
- [Health & cleanup](https://github.com/leo-expose/pesto/blob/main/app/api/health/route.ts): Ops routes · Health check and scheduled cleanup entrypoints. · `app/api/health/route.ts`

### Core logic

Domain logic, persistence, security, and rendering helpers.

- [Database layer](https://github.com/leo-expose/pesto/blob/main/lib/db/index.ts): Drizzle/Postgres · Database entrypoint and schema definitions for users, pastes, versions, settings, and setup state. · `lib/db/index.ts`
- [Paste logic](https://github.com/leo-expose/pesto/blob/main/lib/paste.ts): Domain rules · Alias generation, paste lifecycle, validation, and content helpers. · `lib/paste.ts`
- [Render pipeline](https://github.com/leo-expose/pesto/blob/main/lib/markdown.ts): Markdown/highlight · Markdown, language detection, syntax highlighting, themes, and editor language mapping. · `lib/markdown.ts`
- [Access control](https://github.com/leo-expose/pesto/blob/main/lib/setupAccess.ts): Auth/setup guards · Auth model plus setup-mode and admin access checks. · `lib/setupAccess.ts`
- [State & policy](https://github.com/leo-expose/pesto/blob/main/lib/settings.ts): Shared policy · Settings, setup state, rate limiting, validators, and general utilities. · `lib/settings.ts`

### UI components

Reusable client and server UI building blocks.

- [Navigation UI](https://github.com/leo-expose/pesto/blob/main/components/layout/Navbar.tsx): Shared UI · Navbar, theme provider, and chrome shared across screens. · `components/layout/Navbar.tsx`
- [Paste UI](https://github.com/leo-expose/pesto/blob/main/components/paste/PasteViewer.tsx): Shared UI · Viewer, card, prompt, history, and visibility components for paste reading. · `components/paste/PasteViewer.tsx`
- [Form controls](https://github.com/leo-expose/pesto/blob/main/components/ui/Button.tsx): Shared UI · Reusable buttons, inputs, selects, dialogs, and theme picker. · `components/ui/Button.tsx`

### Runtime & tooling

Build, deployment, and operational entrypoints.

- [Tooling](https://github.com/leo-expose/pesto/blob/main/next.config.ts): Build/runtime · Next.js, Drizzle, instrumentation, proxy, scripts, and type extensions. · `next.config.ts`

## Connections

- App shell → Navigation UI: uses · Global layout composes shared navigation and theme shell.
- Public read → Paste UI: renders · Public paste pages use viewer, history, prompts, and badges.
- User area → Paste UI: uses · New paste and personal paste views reuse paste UI pieces.
- Admin console → Form controls: uses · Admin console relies on common form and dialog controls.
- Login flow → Form controls: uses · Login screens use shared input and button primitives.
- Setup wizard → Form controls: uses · Setup wizard uses shared form controls for bootstrap steps.
- User area → Paste logic: depends on · Authenticated paste flows invoke paste domain rules.
- Public read → Render pipeline: depends on · Read views use markdown and syntax rendering pipeline.
- Admin console → Access control: guards · Admin screens enforce instance and setup access rules.
- Login flow → Auth API: calls · Login flow delegates session handling to Auth API.
- Setup wizard → Setup API: calls · Provisioning UI drives setup bootstrap endpoints.
- Auth API → Access control: auth · Auth route relies on the app's auth model and guards.
- Paste API → Paste logic: business logic · Paste endpoints use alias, versioning, and content helpers.
- Paste API → Database layer: persists · Paste CRUD reads and writes the primary database.
- Settings API → State & policy: policy · Settings endpoints use shared settings and validation logic.
- Setup API → Database layer: bootstrap · Setup routes test and initialize the database schema.
- Health & cleanup → State & policy: maintenance · Health and cleanup use shared operational policy.
- Paste logic → Database layer: stores · Paste logic is centered on the Drizzle/Postgres layer.
- Render pipeline → State & policy: config · Rendering pipeline pulls theme and language policy.
- Access control → State & policy: checks · Access control uses setup state and instance policy.
- State & policy → Database layer: reads/writes · Shared policy layer touches settings and setup-related data.
- Tooling → Health & cleanup: hosts · Operational scripts and hooks support runtime maintenance paths.
- Tooling → Database layer: tooling · Build and setup tooling tie into schema and database config.
