Monorepo starter for AI agents building apps on Cloudflare

A developer published a production-oriented monorepo starter that combines pnpm workspaces, Turborepo, and Cloudflare Workers infrastructure, with explicit design choices to enable AI agents to safely build and maintain applications. The template is built on Node.js 22+, pnpm (pinned via the root package.json), and includes a Cloudflare Workers API gateway (Hono), React frontend (Vite + Tailwind CSS v4 + TanStack Router/Query), and structured shared packages for DTOs (data transfer objects via Zod), enums, and TypeScript configuration presets.

The monorepo is organized into three categories: backend services (worker-api, worker-* business logic, queue-* consumers, webhook-* ingress, and mcp-* MCP servers), frontend applications (React SPA), and shared packages (@repo/dtos-common, @repo/enums-common, @repo/typescript-config). Architecture is enforced through strict naming conventions and patterns. The public HTTP gateway (worker-api) validates requests and routes work via service-binding RPC to private business workers (worker-*). Each worker owns at most one Drizzle database schema under src/db/, and other workers access that data exclusively through RPC or queue channels—never by attaching the same database binding to multiple apps. This prevents a common mistake when agents scaffold infrastructure: accidentally creating multiple owners of the same database.

Development workflow is Makefile-driven from the repo root. Installation is make install (preferred over raw pnpm install to maintain workspace consistency). The make dev command starts all dev servers via Turborepo; scoped work uses make dev SCOPE=worker-name. Environment configuration uses .dev.vars files (from .dev.vars.example templates) for worker secrets and .env.local for frontend Vite variables. Each worker assigns its own development port from a mnemonic registry: worker-api uses 8700–8709, worker-* uses 8710–8739, queue-* uses 8740–8759, webhook-* uses 8760–8779, and mcp-* uses 8780–8789. Frontends use Vite's default 5174 (dev) and 4174 (preview). Testing service bindings between workers uses either a single multi-config wrangler dev command (wrangler dev -c apps/worker-api/wrangler.jsonc -c apps/worker-example/wrangler.jsonc, with the first config as HTTP-primary) or separate terminal runs.

Scaffolding new workers follows a copy-and-rename pattern: there is no generator CLI. A developer (or agent) copies an existing app (e.g., apps/worker-api) to a new name (e.g., apps/worker-account), updates package.json name, wrangler.jsonc name, assigns the next free port from the development registry, includes make/app.mk in the new worker's Makefile, and extends @repo/typescript-config presets. This approach is simpler for agents than template parsing and reduces misconfiguration risk. Deployment is make deploy (all workers) or make deploy SCOPE=worker-name (single worker). The template includes hooks for AI agent integration (under hooks/, not Husky) and supports a dual-handler pattern for queue-only (queue-*) and hybrid (worker-* with queues) apps, separating HTTP request handling (for local debug) from queue message consumption via queue() handlers.

The template explicitly targets AI agents as a first-class use case. Architecture constraints that might otherwise be learned through code review (exclusive database ownership, RPC-only business logic, public/private separation) are baked into the folder structure, naming conventions, and configuration patterns. The monorepo enforces these guardrails automatically, making it safer for non-human systems to modify production infrastructure without human-in-the-loop review of every change.

This monorepo starter represents a deliberate shift in how application templates are designed—moving from general-purpose scaffolding to architecture optimized for non-human agents (AI systems) modifying production codebases. The template acknowledges a real risk: when an AI agent creates a new worker or modifies existing infrastructure, it can accidentally violate architectural constraints that human developers would catch in code review (e.g., attaching the same database binding to multiple workers, or creating public routes in business logic layers).

The design solves this by making safe patterns the default and mistakes architecturally impossible. Database ownership is colocated with schema; each worker owns at most one database binding. Inter-worker communication flows through explicit RPC channels or queues, not through shared bindings. The template includes hooks specifically for agent integration, signaling that the author expects the codebase to be read and modified by non-human systems as a first-class use case.

Development experience is also optimized for agent scaffolding: instead of a code generator (which requires parsed templates and can fail silently), new workers are created by copying an existing sibling app and renaming its package.json and configuration files. This is simpler for both humans and agents to execute correctly, and the monorepo's Makefile-driven workflow (make dev SCOPE=worker-name, make deploy SCOPE=worker-name) reduces the surface area for misconfiguration. The port registry (8700–8789 for workers in defined roles) further eliminates decision-making for agents when assigning network configuration.

No comments yet. Be the first to share your thoughts!