awesome-claude-code-toolkit/templates/claude-md/monorepo.md

Acme Platform

Monorepo for the Acme SaaS platform: web app, API server, shared libraries, and infrastructure.

Stack

• Build System: Turborepo 2.x
• Package Manager: pnpm 9.x with workspaces
• Languages: TypeScript 5.x (apps), Go 1.22 (services)
• Frontend: Next.js 15 (App Router), Tailwind CSS 4, Radix UI
• Backend: Hono (API gateway), tRPC (internal RPC)
• Database: PostgreSQL 16, Prisma ORM (shared schema)
• Cache: Redis 7 (sessions, rate limiting, pub/sub)
• Queue: BullMQ (email, notifications, reports)
• Testing: Vitest (unit), Playwright (e2e), k6 (load)
• CI/CD: GitHub Actions, Docker, AWS ECS
• Observability: OpenTelemetry, Grafana, Sentry

Commands

• pnpm install - Install all workspace dependencies
• pnpm dev - Start all apps in development mode
• pnpm dev --filter=@acme/web - Start only the web app
• pnpm dev --filter=@acme/api - Start only the API server
• pnpm build - Build all packages and apps
• pnpm test - Run tests across all packages
• pnpm test --filter=@acme/core - Run tests for a specific package
• pnpm lint - Lint all packages
• pnpm typecheck - Type check all packages
• pnpm db:migrate - Run database migrations
• pnpm db:seed - Seed database with test data
• turbo run build --graph - Visualize the dependency graph
• pnpm changeset - Create a changeset for versioning

Workspace Structure

apps/
  web/              - Next.js customer-facing web app (port 3000)
  admin/            - Next.js internal admin dashboard (port 3001)
  api/              - Hono API gateway (port 4000)
  worker/           - BullMQ background job processor
packages/
  core/             - Shared business logic, validators, constants
  db/               - Prisma client, repositories, migrations
  ui/               - Shared React component library (Radix + Tailwind)
  config-eslint/    - Shared ESLint configuration
  config-ts/        - Shared TypeScript configuration
  email/            - Email templates (React Email)
  logger/           - Structured logging (Pino)
services/
  billing/          - Go billing microservice (Stripe integration)
  search/           - Go search service (Meilisearch proxy)
infra/
  terraform/        - AWS infrastructure as code
  docker/           - Dockerfiles for all services
  k8s/              - Kubernetes manifests

Package Dependencies

• @acme/core has zero external dependencies (pure business logic).
• @acme/db depends on @acme/core for types and validators.
• @acme/ui depends on @acme/core for constants and types.
• Apps depend on packages but packages never depend on apps.
• Use workspace:* for all internal package references.

Conventions

• Changes spanning multiple packages require a changeset (pnpm changeset).
• Each package has its own tsconfig.json extending @acme/config-ts.
• Each package has its own test suite. No cross-package test imports.
• Shared types live in @acme/core/types. App-specific types stay in the app.
• Database access only through @acme/db repositories. No raw Prisma in apps.
• Feature flags managed through LaunchDarkly SDK in @acme/core/flags.

Environment Variables

• DATABASE_URL - PostgreSQL connection (used by @acme/db)
• REDIS_URL - Redis connection (used by API and worker)
• STRIPE_SECRET_KEY - Stripe API key (used by billing service)
• MEILISEARCH_HOST - Search service URL
• SENTRY_DSN - Error tracking (per-app DSN)
• LAUNCHDARKLY_SDK_KEY - Feature flags

Key Decisions

Date	Decision	Rationale
2025-08-01	Turborepo over Nx	Simpler config, native pnpm support
2025-09-15	Go for billing/search	Performance-critical, team has Go experience
2025-10-01	Prisma shared schema	Single source of truth, type-safe queries
2025-11-20	React Email over MJML	Component reuse, TypeScript support