# 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 |