How leo-expose/pesto works
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: settings.ts State & policy · index.ts Database layer · paste.ts Paste logic · setupAccess.ts Access control
Components 21
App surfaces
Next.js route groups and page-level product surfaces.
- App shell · Global app layout and shared chrome for the runtime.
app/layout.tsx - Public read · Public paste rendering and raw content access.
app/(app)/p/[alias]/page.tsx - User area · Authenticated product surface for creating and managing pastes.
app/(app)/page.tsx - Admin console · Instance-wide settings and user management UI.
app/(app)/admin/page.tsx - Login flow · Sign-in screens and login actions.
app/(auth)/login/page.tsx - Setup wizard · First-run installation and bootstrap UI.
app/setup/page.tsx
API layer
Route handlers for product, auth, setup, and maintenance workflows.
- Auth API · NextAuth handler for sessions and provider sign-in.
app/api/auth/[...nextauth]/route.ts - Paste API · Create, read, update, and version paste endpoints.
app/api/pastes/route.ts - Settings API · Instance and user settings endpoints.
app/api/settings/route.ts - Upload API · Attachment or media upload boundary.
app/api/upload/route.ts - Setup API · Database test, schema push, and setup completion endpoints.
app/api/setup/test-db/route.ts - Health & cleanup · Health check and scheduled cleanup entrypoints.
app/api/health/route.ts
Core logic
Domain logic, persistence, security, and rendering helpers.
- Database layer · Database entrypoint and schema definitions for users, pastes, versions, settings, and setup state.
lib/db/index.ts - Paste logic · Alias generation, paste lifecycle, validation, and content helpers.
lib/paste.ts - Render pipeline · Markdown, language detection, syntax highlighting, themes, and editor language mapping.
lib/markdown.ts - Access control · Auth model plus setup-mode and admin access checks.
lib/setupAccess.ts - State & policy · Settings, setup state, rate limiting, validators, and general utilities.
lib/settings.ts
UI components
Reusable client and server UI building blocks.
- Navigation UI · Navbar, theme provider, and chrome shared across screens.
components/layout/Navbar.tsx - Paste UI · Viewer, card, prompt, history, and visibility components for paste reading.
components/paste/PasteViewer.tsx - Form controls · Reusable buttons, inputs, selects, dialogs, and theme picker.
components/ui/Button.tsx
Runtime & tooling
Build, deployment, and operational entrypoints.
- Tooling · Next.js, Drizzle, instrumentation, proxy, scripts, and type extensions.
next.config.ts
Connections 23
- 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.