Penpot

# MISSION: Scaffold "Penpot" 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 **Penpot**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: Penpot
- **What It Does**: Penpot is an open-source, MPL-2.0 design and prototyping platform with a Clojure and ClojureScript core, a Rust/WebAssembly canvas renderer, PostgreSQL storage, and separate Redis-backed export and media-processing services.
- **Domain & Category**: Design & Prototyping Platform
- **Production Scale**: 20+ people
- **Development Mode**: CLASSIC
- **Architectural Rationale**: Splitting the backend, frontend, exporter, media processing, and MCP server into independently managed pnpm/Clojure projects, and moving canvas rendering into a Rust/WebAssembly engine, lets each heavy or performance-sensitive piece evolve and scale on its own instead of living inside one ClojureScript monolith.
- **Live Website Reference**: https://penpot.app
- **Source Repository**: https://github.com/penpot/penpot
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: Clojure, ClojureScript, Rust, WebAssembly, TypeScript, PostgreSQL, Redis, Docker, pnpm, Playwright
- **Primary Language(s)**: Clojure, JavaScript, Rust
- **License of the reference repo**: MPL-2.0
- **Frontend**: ClojureScript — The main app and worker are compiled by shadow-cljs (build:app:main runs "clojure -M:dev:shadow-cljs release main worker").; Rust — render-wasm implements the canvas renderer, compiled to WebAssembly and invoked from the frontend build via build:wasm.; WebAssembly — Compilation target for the render-wasm crate, loaded by the frontend as the canvas rendering engine.
- **Backend & APIs**: Clojure — Server-side application code lives under backend/src with its own deps.edn.; PostgreSQL — Primary database; a dedicated maintenance script upgrades it across major versions.; ClojureScript — The exporter service is a Node-targeted ClojureScript app that drives headless Chromium through Playwright.
- **Data & persistence**: PostgreSQL — Primary relational datastore for the backend.; Redis — The exporter depends on ioredis, used to coordinate export jobs outside the main backend process.
- **Infrastructure & deploy**: Docker — docker/devenv and docker/imagemagick provide Dockerfiles for the dev environment and image-processing tooling.; pnpm — Each subproject (backend, frontend, common, exporter, library, mcp, media-processor, docs, render-wasm) is its own independently versioned pnpm workspace.; GitHub Actions — Per-module workflows (tests-backend.yml, tests-frontend.yml, tests-wasm.yml, tests-mcp.yml) plus build-docker*.yml handle CI and release bundling.
- **Tooling, testing & ops**: Model Context Protocol — @penpot/mcp is a standalone package exposing a penpot-mcp binary for AI-agent integration.; Playwright — Used both by the exporter to render designs headlessly and, via @playwright/mcp at the repo root, for MCP-driven browser test tooling.
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/penpot/penpot @ ecf8436)
1. **Every subsystem is its own independently managed project, not one JS monorepo**: backend, frontend, common, exporter, library, mcp, media-processor, docs, and render-wasm each have their own package.json and pnpm-workspace.yaml (and, for the Clojure pieces, their own deps.edn), and the root package.json only carries end-to-end test tooling (@playwright/test, @playwright/mcp, nrepl-client) rather than a shared workspaces field.
2. **Canvas rendering moved from ClojureScript to a Rust/WebAssembly engine**: render-wasm/Cargo.toml depends on skia-safe, glam, and bezier-rs to implement the renderer in Rust, and frontend/package.json’s build:wasm script ("../render-wasm/build frontend") compiles it to WebAssembly and wires it into the ClojureScript-built app rather than keeping the renderer purely in ClojureScript.
3. **Design export runs as a separate ClojureScript service driving headless Chromium**: exporter/package.json is a shadow-cljs-targeted Node project depending directly on playwright for headless rendering and ioredis for job coordination, isolating the CPU- and memory-heavy PDF/PNG/SVG export path from the main backend process.
4. **Image and font processing is a separate stateless TypeScript service**: media-processor/package.json describes itself as a "Stateless HTTP service for Penpot image and font processing," built with Express and Sharp and its own esbuild-based build script, distinct from both the Clojure backend and the ClojureScript exporter.
5. **MCP support ships as its own installable package**: mcp/package.json defines a bin entry (penpot-mcp) and bootstrap/build/start scripts that run across an internal pnpm -r workspace, so Model Context Protocol access to Penpot is a separately versioned artifact rather than a flag on an existing service.
6. **Production frontend builds still go through shadow-cljs, not a JS bundler**: Despite a Vite config existing in the tree (frontend/vite.config.js), the actual app build script (build:app:main) invokes "clojure -M:dev:shadow-cljs release main worker", so shadow-cljs remains the ClojureScript-to-JS compiler for the shipped application.
---
## 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 (PostgreSQL, Redis): 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.