# sherdotsh/sher architecture

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

- Interactive diagram: https://gitdiagram.com/sherdotsh/sher
- Repository: https://github.com/sherdotsh/sher

## Overview

This repo is a **developer CLI + serverless backend** that creates **instant preview links for static frontends**.

- **Client-side component:** `sher` CLI (published as `shersh` on npm) that:
- detects framework/package manager
- builds (or skips build)
- collects static output files
- uploads to a hosted API
- returns a shareable URL (optionally TTL / password tier)
- **Backend component:** **Cloudflare Worker** + **R2** + **KV** that:
- authenticates users via **GitHub OAuth**
- stores deployment metadata (IDs, TTL, ownership, tier, etc.)
- stores uploaded artifacts in **R2**
- serves preview URLs back to browsers
- optionally integrates **Polar** for paid “Pro” subscriptions
- **Ancillary:** agent “skill” docs (`skills/`, `.agents/skills/`) and packaging (`Formula/` for Homebrew).

#### 2) Map the file tree to architectural components (how to “separate into as many components as possible”)

##### CLI (Node/TypeScript) — `src/`

- `src/index.ts`: CLI entrypoint / command routing (likely `sher link/list/delete/login/...`)
- `src/detect.ts`: framework & package manager detection (Vite/Next/Astro/CRA/etc.)
- `src/build.ts`: runs the build command (e.g., `npm run build`)
- `src/static-export.ts`: Next.js static export logic (special-case)
- `src/collect.ts`: enumerates build output dir, file list, sizes
- `src/upload.ts`: upload client to Worker API (multipart or batched)
- `src/api.ts`: HTTP client wrapper + endpoint definitions (link/list/delete/whoami/upgrade)
- `src/auth.ts`: GitHub login flow (device flow or OAuth via Worker), token storage
- `src/clipboard.ts`: copies returned URL
- `src/constants.ts`: default API URL, directories, limits, etc.

Build/packaging for CLI:
- `tsup.config.ts`, `tsconfig.json`: compile/bundle
- `package.json`, `package-lock.json`: runtime deps, bin entry

##### Worker backend (Cloudflare) — `worker/`
Treat this as the “server” / API + static serving plane.

- `worker/src/index.ts`: Worker router / fetch handler (API + website pages)
- `worker/wrangler.toml`: binds **R2 bucket**, **KV namespace**, routes, env vars
- `worker/lifecycle.json`: hints about lifecycle/cron/maintenance (include if used)
- Website/marketing/blog pages are also in Worker:
- `worker/src/landing.ts`, `pricing.ts`, `why.ts`, `blog.ts`, plus many `blog-*.ts`

Backend integrations (from README; show as external systems):
- **GitHub OAuth**: callback `/auth/callback` (or similar)
- **Polar** (optional): webhook + product config for Pro

##### Storage & delivery plane (Cloudflare-managed)
- **R2 bucket** (e.g., `sher-uploads`): stores uploaded build artifacts
- **Cloudflare edge routing**: `https://<id>.sher.sh` resolves to Worker; Worker reads from R2 and returns static assets

##### Distribution / “installation”
- npm: package `shersh`
- Homebrew: `Formula/sher.rb`
- “Agent skill” docs: `skills/sher-deploy/SKILL.md` and `.agents/skills/...` (integration guidance for AI agents)

##### Worker writes
- artifacts → **R2**
- deployment metadata (owner, expiry, size, flags like password-protected) → **KV**

##### Worker
- looks up deployment metadata in **KV** (validate TTL, password requirement)
- fetches asset from **R2**

##### Flow 3: `sher list` / `sher delete`
- CLI calls Worker API endpoints
- Worker queries KV (and possibly R2) and returns deployments / deletes artifacts + metadata

##### Flow 4: Upgrade / Pro billing (optional branch)
- CLI calls Worker “upgrade” endpoint
- Worker interacts with **Polar**
- Polar sends **webhooks** back to Worker to confirm subscription state
- Worker updates user tier/quota in KV

##### System Context (Level 1): one-page overview
- Actors: “Developer (CLI user)”, “Recipient (browser viewer)”
- Systems: “Sher CLI”, “Sher Cloudflare Worker”, “GitHub OAuth”, “Polar (billing)”, “Cloudflare R2”, “Cloudflare KV”

- CLI subcomponents: Detect/Build/Collect/Upload/Auth
- Worker subcomponents: API router, Auth handler, Upload handler, Preview serving handler, Billing webhook handler
- Storage: R2 (artifacts), KV (metadata/state)

This matches the repo layout cleanly: `src/*` maps to CLI containers; `worker/src/*` maps to Worker containers.

##### Must-have labels (use exact tech names)
- “CLI (Node.js + TypeScript)”
- “Cloudflare Worker (TypeScript)”
- “Cloudflare R2 (artifact storage)”
- “Cloudflare KV (metadata/session/quota store)”
- “GitHub OAuth (identity)”
- “Polar (billing, optional)”
- “Preview URL: https://{id}.sher.sh (served by Worker)”
- “Env override: SHER_API_URL” (important architectural switch for self-hosting)

- CLI → Worker: “HTTPS API (upload, list, delete, whoami, upgrade)”
- Worker → R2: “PUT/GET artifacts”
- Worker → KV: “deployment metadata, TTL, auth state, tier/quota”
- Worker ↔ GitHub: “OAuth redirect + token exchange”
- Worker ↔ Polar: “create checkout / verify” and “webhook events”
- Browser → Worker: “GET / (static assets)”

##### Deliverables to ask the engineer to produce
- `sher link`
- “Open preview link”

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Level 1: System Context
  %% =========================
  subgraph "Actors"
    Dev["Developer"]:::actor
    Viewer["Recipient (Browser)"]:::actor
  end

  subgraph "Client Plane (Local Machine)"
    Project["User Project (Vite/Next/Astro/...)"]:::client
    CLI["Sher CLI (Node.js + TypeScript)"]:::cli
    EnvSwitch["Env override: SHER_API_URL"]:::note
  end

  subgraph "Cloudflare Edge / Compute Plane"
    Worker["Sher Cloudflare Worker (TypeScript)"]:::worker
    PreviewURL["Preview URL: https://{id}.sher.sh"]:::note
  end

  subgraph "Cloudflare Data Plane"
    R2[("Cloudflare R2\n(artifact storage)")]:::storage
    KV[("Cloudflare KV\n(metadata/session/quota store)")]:::storage
  end

  subgraph "External Services"
    GitHub["GitHub OAuth (identity)"]:::external
    Polar["Polar (billing, optional)"]:::external
  end

  %% Context connections (keep vertical feel)
  Dev -->|"runs 'sher link/list/delete/login'"| CLI
  CLI -->|"reads/executes"| Project
  EnvSwitch -.->|"changes API base URL"| CLI

  CLI -->|"HTTPS API (upload,list,delete,whoami,upgrade)"| Worker
  Worker -->|"PUT/GET artifacts"| R2
  Worker -->|"deployment metadata,TTL,auth state,tier/quota"| KV
  Worker <-->|"OAuth redirect + token exchange"| GitHub
  Worker <-->|"checkout/verify + webhook events"| Polar

  Viewer -->|"GET https://{id}.sher.sh/*"| Worker
  Worker -->|"serves static assets"| Viewer
  PreviewURL -.-> Worker

  %% =========================
  %% Level 2: Container / Component View
  %% =========================
  subgraph "CLI Internals (src/)"
    CLIEntry["CLI Entrypoint / Command routing\n(src/index.ts)"]:::cliComp
    Detect["Framework & package manager detection\n(src/detect.ts)"]:::cliComp
    Build["Build runner\n(src/build.ts)"]:::cliComp
    StaticExport["Next.js static export logic\n(src/static-export.ts)"]:::cliComp
    Collect["Collect static artifacts\n(src/collect.ts)"]:::cliComp
    AuthCLI["GitHub login flow + token storage\n(src/auth.ts)"]:::cliComp
    APIClient["HTTP API client wrapper\n(src/api.ts)"]:::cliComp
    Upload["Upload client (artifacts)\n(src/upload.ts)"]:::cliComp
    Clipboard["Clipboard copy of preview URL\n(src/clipboard.ts)"]:::cliComp
    Constants["CLI constants (API URL,limits)\n(src/constants.ts)"]:::cliComp
    Tsup["Build/Bundling config\n(tsup.config.ts)"]:::build
    TSConfig["TypeScript config\n(tsconfig.json)"]:::build
  end

  CLI -->|"routes commands"| CLIEntry
  CLIEntry -->|"detects"| Detect
  Detect -->|"selects build strategy"| Build
  Build -->|"may invoke"| StaticExport
  Build -->|"produces output"| Collect
  CLIEntry -->|"auth if needed"| AuthCLI
  AuthCLI -->|"uses"| APIClient
  Collect -->|"files+sizes"| Upload
  Upload -->|"uses"| APIClient
  APIClient -->|"returns previewUrl"| Clipboard
  Constants -.-> Detect
  Constants -.-> APIClient
  Tsup -.-> CLIEntry
  TSConfig -.-> CLIEntry

  %% Worker internals
  subgraph "Worker Internals (worker/)"
    WorkerRouter["Worker router / fetch handler\n(worker/src/index.ts)"]:::workerComp
    Bindings["Cloudflare bindings/config\n(worker/wrangler.toml)"]:::workerCfg
    Lifecycle["Lifecycle/maintenance config\n(worker/lifecycle.json)"]:::workerCfg

    subgraph "API & Preview Handlers"
      DeployAPI["Deployment API\n(create/list/delete)"]:::workerComp
      UploadHandler["Upload handler\n(ingest artifacts)"]:::workerComp
      PreviewHandler["Preview serving handler\n(subdomain routing + TTL/password checks)"]:::workerComp
      AuthWorker["Auth endpoints\n(GitHub OAuth callback)"]:::workerComp
      Billing["Billing endpoints/webhooks\n(Polar integration)"]:::workerComp
    end

    subgraph "Secondary workload (same Worker)"
      Landing["Marketing page: landing\n(worker/src/landing.ts)"]:::site
      Pricing["Marketing page: pricing\n(worker/src/pricing.ts)"]:::site
      Why["Marketing page: why\n(worker/src/why.ts)"]:::site
      Blog["Blog index\n(worker/src/blog.ts)"]:::site
      BlogPosts["Blog content pages\n(worker/src/blog-*.ts)"]:::site
    end
  end

  Worker -->|"implements"| WorkerRouter
  Bindings -.-> WorkerRouter
  Lifecycle -.-> WorkerRouter

  WorkerRouter -->|"routes /api/*"| DeployAPI
  DeployAPI -->|"uses"| UploadHandler
  WorkerRouter -->|"routes /auth/*"| AuthWorker
  WorkerRouter -->|"routes preview hostnames"| PreviewHandler
  WorkerRouter -->|"routes /upgrade + /webhooks"| Billing
  WorkerRouter -->|"routes / (site pages)"| Landing
  WorkerRouter -->|"routes /pricing"| Pricing
  WorkerRouter -->|"routes /why"| Why
  WorkerRouter -->|"routes /blog"| Blog
  WorkerRouter -->|"routes /blog/*"| BlogPosts

  UploadHandler -->|"write artifacts"| R2
  UploadHandler -->|"write deployment metadata"| KV
  DeployAPI -->|"read/write deployment list"| KV
  DeployAPI -->|"delete artifacts"| R2
  PreviewHandler -->|"lookup metadata (TTL/password/tier)"| KV
  PreviewHandler -->|"fetch asset"| R2
  AuthWorker <-->|"OAuth flow"| GitHub
  Billing <-->|"checkout/verify + webhooks"| Polar
  Billing -->|"update tier/quota"| KV

  %% Distribution / ecosystem
  subgraph "Distribution / Ecosystem"
    NPM["npm registry\n(package: shersh)"]:::external
    Brew["Homebrew Formula"]:::external
    Skills["Agent skill docs"]:::external
    FormulaFile["Formula/sher.rb"]:::dist
    SkillDoc1["skills/sher-deploy/SKILL.md"]:::dist
    SkillDoc2[".agents/skills/sher-deploy/SKILL.md"]:::dist
  end

  NPM -->|"install CLI"| Dev
  Brew -->|"install CLI"| Dev
  Skills -->|"integration guidance"| Dev
  Brew -.-> FormulaFile
  Skills -.-> SkillDoc1
  Skills -.-> SkillDoc2

  %% =========================
  %% Sequence: Money path (sher link + open preview)
  %% =========================
  subgraph "Sequence (Key Flows)"
    direction TB
    S1["1) sher link:\nDetect → (Build/Export) → Collect → Auth → Upload → URL"]:::seq
    S2["2) Open preview:\nBrowser GET → Worker checks KV → fetch from R2 → returns assets"]:::seq
  end

  Dev -->|"triggers"| S1
  S1 -->|"uses CLI internals"| CLIEntry
  S1 -->|"HTTPS upload"| WorkerRouter
  WorkerRouter -->|"store"| R2
  WorkerRouter -->|"store"| KV
  WorkerRouter -->|"returns {id,url,expiresAt}"| CLI
  CLI -->|"copies URL"| Clipboard
  Clipboard -->|"share link"| Viewer
  Viewer -->|"opens URL"| S2
  S2 -->|"request to"| WorkerRouter
  WorkerRouter -->|"validate"| KV
  WorkerRouter -->|"read"| R2
  WorkerRouter -->|"respond"| Viewer

  %% =========================
  %% Click events (mapped components)
  %% =========================
  click CLI "https://github.com/sherdotsh/sher/tree/main/src/"
  click CLIEntry "https://github.com/sherdotsh/sher/blob/main/src/index.ts"
  click Detect "https://github.com/sherdotsh/sher/blob/main/src/detect.ts"
  click Build "https://github.com/sherdotsh/sher/blob/main/src/build.ts"
  click StaticExport "https://github.com/sherdotsh/sher/blob/main/src/static-export.ts"
  click Collect "https://github.com/sherdotsh/sher/blob/main/src/collect.ts"
  click Upload "https://github.com/sherdotsh/sher/blob/main/src/upload.ts"
  click APIClient "https://github.com/sherdotsh/sher/blob/main/src/api.ts"
  click AuthCLI "https://github.com/sherdotsh/sher/blob/main/src/auth.ts"
  click Clipboard "https://github.com/sherdotsh/sher/blob/main/src/clipboard.ts"
  click Constants "https://github.com/sherdotsh/sher/blob/main/src/constants.ts"
  click Tsup "https://github.com/sherdotsh/sher/blob/main/tsup.config.ts"
  click TSConfig "https://github.com/sherdotsh/sher/blob/main/tsconfig.json"

  click Worker "https://github.com/sherdotsh/sher/tree/main/worker/"
  click WorkerRouter "https://github.com/sherdotsh/sher/blob/main/worker/src/index.ts"
  click Bindings "https://github.com/sherdotsh/sher/blob/main/worker/wrangler.toml"
  click Lifecycle "https://github.com/sherdotsh/sher/blob/main/worker/lifecycle.json"
  click Landing "https://github.com/sherdotsh/sher/blob/main/worker/src/landing.ts"
  click Pricing "https://github.com/sherdotsh/sher/blob/main/worker/src/pricing.ts"
  click Why "https://github.com/sherdotsh/sher/blob/main/worker/src/why.ts"
  click Blog "https://github.com/sherdotsh/sher/blob/main/worker/src/blog.ts"
  click BlogPosts "https://github.com/sherdotsh/sher/blob/main/worker/src/blog-*.ts"

  click FormulaFile "https://github.com/sherdotsh/sher/blob/main/Formula/sher.rb"
  click SkillDoc1 "https://github.com/sherdotsh/sher/blob/main/skills/sher-deploy/SKILL.md"
  click SkillDoc2 "https://github.com/sherdotsh/sher/blob/main/.agents/skills/sher-deploy/SKILL.md"

  %% =========================
  %% Styles (color required)
  %% =========================
  classDef actor fill:#FFF1CC,stroke:#8A6D3B,stroke-width:1px,color:#3D2F10
  classDef client fill:#E8F3FF,stroke:#2B6CB0,stroke-width:1px,color:#0B2E4E
  classDef cli fill:#D9FBEA,stroke:#1F7A4D,stroke-width:1px,color:#0B3B22
  classDef cliComp fill:#BFF3D3,stroke:#1F7A4D,stroke-width:1px,color:#0B3B22
  classDef worker fill:#F3E8FF,stroke:#6B46C1,stroke-width:1px,color:#2C1A5A
  classDef workerComp fill:#E9D8FF,stroke:#6B46C1,stroke-width:1px,color:#2C1A5A
  classDef workerCfg fill:#EFE7FF,stroke:#6B46C1,stroke-dasharray:3 3,stroke-width:1px,color:#2C1A5A
  classDef storage fill:#FFE3EA,stroke:#B83280,stroke-width:1px,color:#4A1030
  classDef external fill:#E5E7EB,stroke:#374151,stroke-width:1px,color:#111827
  classDef site fill:#D7F6FF,stroke:#0E7490,stroke-width:1px,color:#083344
  classDef dist fill:#FFE9C7,stroke:#B45309,stroke-width:1px,color:#4A2A06
  classDef note fill:#FFF7ED,stroke:#C2410C,stroke-dasharray:4 3,stroke-width:1px,color:#431407
  classDef seq fill:#F8FAFC,stroke:#475569,stroke-width:1px,color:#0F172A,stroke-dasharray:2 2
```
