monorepo-template: Instructions file for Codex

Monorepo Agent Instructions

Project Overview

A minimal, production-oriented monorepo starter built on pnpm workspaces with Turborepo, Cloudflare Workers, Hono, and a React (Vite) frontend styled with Tailwind CSS v4. front-app talks to worker-api over HTTP; service bindings are the preferred pattern for Worker-to-Worker communication when you add more Workers.

Quick Start

pnpm install    # dependencies + workspace links
pnpm login      # Cloudflare (remote Worker features)
pnpm prepare    # Vite+ pre-commit hooks
pnpm dev        # all dev servers

After scaffolding a new worker under apps/, give it a monorepo.deployOrder in its package.json (lower promotes first; gateways before the SPAs that call them) and a monorepo.healthPath (public probe path, or null for no public HTTP surface), then run pnpm install before turbo commands. Nothing else lists apps: the changeset group, the root --filter='./apps/*' scripts, and CD all discover them.

Architecture

flowchart TB
  subgraph entry [Public entry]
    direction LR
    Front["front-* :517x"]
    Ext["External providers"]
    McpClients["MCP clients"]
  end

  subgraph publicWorkers [Public Workers]
    direction LR
    Gateway["worker-api :8700"]
    Webhook["webhook-* :876x"]
    Mcp["mcp-* :878x"]
  end

  subgraph privateWorkers [Private Workers]
    direction LR
    Biz["worker-* RPC only"]
    Queue["queue-*"]
  end

  subgraph shared [Shared packages]
    direction LR
    Enums["@repo/enums-common"]
    DTOs["@repo/dtos-common"]
    Corr["@repo/correlation-id"]
    Enums --> DTOs
  end

  Front --> Gateway
  Ext --> Webhook
  McpClients --> Mcp

  Gateway --> Biz
  Webhook --> Biz
  Mcp --> Biz

  Gateway --> Queue
  Webhook --> Queue
  Biz --> Queue

  shared -.-> Front
  shared -.-> publicWorkers
  shared -.-> privateWorkers

Worker Prefixes