Browserless

# MISSION: Scaffold "Browserless" Production Architecture
You are an expert Senior Staff Software Architect and Full-Stack Engineer. Your mission is to scaffold and implement a production-grade, highly reliable, and modular codebase following the proven architecture of **Browserless**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: Browserless
- **What It Does**: Browserless runs headless Chrome, Chromium, Firefox, Edge and WebKit as a managed Docker service, exposing them over WebSocket and REST to standard Playwright and Puppeteer client libraries so teams can run browser automation without managing browser infrastructure themselves.
- **Domain & Category**: Headless Browser Automation Infrastructure
- **Production Scale**: 2-5 People
- **Development Mode**: CLASSIC
- **Architectural Rationale**: A base Node.js/TypeScript image is specialized into per-browser Docker builds (and one combined multi-browser build) so deployments only ship the browser binaries and system libraries they actually need, while a single TypeScript server handles session pooling, queueing and protocol translation for all of them.
- **Live Website Reference**: https://browserless.io
- **Source Repository**: https://github.com/browserless/browserless
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: TypeScript, Node.js, Docker, Playwright, Puppeteer
- **Primary Language(s)**: TypeScript, JavaScript, Dockerfile, Shell
- **License of the reference repo**: NOASSERTION
- **Backend & APIs**: Node.js — Runtime for the service; a custom HTTP/WebSocket server (src/server.ts, http.ts, router.ts) pools browser connections without a web framework.; TypeScript — The entire src/ tree is TypeScript, compiled with tsc and published with declaration files (build/exports.d.ts).; Playwright — Primary automation protocol; playwright-core plus five version-pinned aliases let clients on older Playwright versions connect to matching routes.; Puppeteer — Alternate automation protocol via puppeteer-core, extended with @zorilla/puppeteer-extra and a stealth plugin for anti-detection.
- **Infrastructure & deploy**: Docker — docker/ has eight image variants (base, chrome, chromium, edge, firefox, webkit, multi, sdk), each a multi-stage build FROM ghcr.io/browserless/base.; GitHub Actions — Per-browser Docker build/publish workflows, CodeQL scanning, dependabot auto-merge, and release-please for automated versioning.
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/browserless/browserless @ 016ffa7)
1. **One base image, five browser-specific runtime images, built in two stages**: docker/base/Dockerfile installs Node 24 and the full npm tree (including devDependencies) via nvm on Ubuntu 24.04. Each of docker/chrome, docker/chromium, docker/edge, docker/firefox and docker/webkit then runs a builder stage (tsc, function bundle, debugger install) FROM that base, followed by a runtime stage that runs npm prune --omit=dev and installs only that one browser via the Playwright CLI.
2. **A single multi-browser image exists for platforms that need all engines**: docker/multi/Dockerfile installs Chromium, Firefox and WebKit (and Chrome/Edge on linux/amd64 only, gated on the TARGETPLATFORM build arg) into one image, at the cost of a larger runtime image than the per-browser variants.
3. **Playwright and Puppeteer are first-class, with several Playwright protocol versions pinned**: package.json's playwrightVersions map ties named dependency aliases (playwright-1.59 .. playwright-1.63) to specific playwright-core releases so that /playwright/<version> routes stay compatible with older client libraries, alongside puppeteer-core for the Puppeteer-compatible /webdriver and default routes.
4. **An SDK image lets extension authors build on top of the multi image**: docker/sdk/Dockerfile is FROM ghcr.io/browserless/multi:latest, reinstalls with --include=dev so the extension toolchain (typescript, marked, typescript-json-schema) is present, and strips route folders that do not match the base image (e.g. Firefox-only builds drop the chrome/chromium/edge/webkit route directories).
5. **API schemas and OpenAPI docs are generated from the TypeScript routes, not hand-written**: scripts/build-schemas.js (typescript-json-schema) and scripts/build-open-api.js generate the request/response schemas and OpenAPI document served at /docs directly from the route definitions under src/routes, keeping documentation in sync with the implementation.
---
## 4. NON-NEGOTIABLE ARCHITECTURAL GUARDRAILS
1. **Monorepo & Modular Separation**:
   - Structure as a Turborepo monorepo with strict package boundaries:
     - `apps/web`: Application UI, routing, layouts, and server endpoints.
     - `packages/ui`: Shared design tokens, CSS variables, and Radix UI primitive components.
     - `packages/db`: Database schemas, client singleton, declarative migrations, and seed scripts.
     - `packages/config`: Shared TypeScript, ESLint, and build configurations.
2. **Strict Type Safety & Zero `any` Policy**:
   - Enable `strict: true`, `noImplicitAny: true`, and `strictNullChecks: true`.
   - Validate ALL external inputs, API request bodies, and query parameters with **Zod** schemas before execution.
3. **Frontend & Rendering Guidelines**:
   - Isolate interactive UI state to leaf components. Keep core pages lightweight and performant.
4. **Design System & Aesthetics**:
   - Keep every color, radius, shadow and font in a single token file (CSS variables) and consume tokens everywhere; never hardcode hex values in components.
   - Prefer crisp 1px borders and one subtle shadow scale over blurry default shadows. Pair one sans-serif for body/headings with one monospace for tags, badges, metrics, and code.
5. **Data Layer & Reliability**:
   - Write declarative schema definitions with foreign keys, composite indexes on queried filters, and automated timestamp triggers.
   - Use connection pooling and prepared statements for serverless database execution.
---
## 5. STEP-BY-STEP SCAFFOLDING ROADMAP
- **Phase 1: Workspace & Root Config**: Initialize package manager, monorepo configuration (`turbo.json`, `tsconfig.base.json`, `package.json`).
- **Phase 2: Database Schema & Client**: Set up the data layer: client, connection pool, models, and migration scripts.
- **Phase 3: Design Tokens & UI Primitives**: Build accessible `Button`, `Input`, `Card`, `Badge`, and layout wrappers inside `packages/ui`.
- **Phase 4: Core Application Routes & Handlers**: Implement primary authentication, user session handling, and application routes.
- **Phase 5: Quality Assurance & Build Verification**: Run `tsc --noEmit`, ESLint, Prettier, and smoke test suites to ensure zero compilation or runtime errors.
---
## 6. EXECUTION INSTRUCTIONS
1. Review all specifications, architectural guardrails, and stack choices above.
2. Present the full monorepo directory tree structure.
3. Systematically generate the complete, production-ready codebase according to the 5-phase roadmap above — starting with the root workspace setup, followed by the database schema, UI design system package, and full-stack application routes until the repository is fully scaffolded and ready to run.