# Composable Monorepo Templates

**Last Updated:** 2026-01-30
**Confidence:** High (Planned)

## Summary

Composable Monorepo Templates evolve rdev's project scaffolding from single templates to full monorepo architecture. Every project starts as a monorepo skeleton, with components (services, workers, apps, cli) added via API calls. Deployment can target the whole monorepo or individual components.

**Key Facts:**
- `POST /projects` creates monorepo skeleton (not single template)
- `POST /projects/{id}/components` adds services/workers/apps/cli
- Convention-based discovery: `services/*/`, `workers/*/`, `apps/*/`, `cli/*/`
- Optional `component.yaml` per component for ports, dependencies, build order
- Shared `pkg/` from Aeries chassis + Colix patterns (8 packages)
- Deployment supports whole-monorepo or individual-component targets
- **CI is template-provided** - skeleton has `.woodpecker.yml.tmpl`, components have `.woodpecker.step.yml.tmpl`

**Critical Design Decision:**
CI/CD configuration MUST come from templates, never AI-generated. Claude Code produces invalid
Woodpecker YAML when generating from scratch (broken YAML anchor syntax).

**File Pointers:**
- Plan: `tmp/template-monorepo-plan.md`
- Current templates: `internal/adapter/templates/templates/`
- Port: `internal/port/template_provider.go`

## How It Works

### Project Creation Flow

```
POST /projects {"name": "acme"}
  ↓
Creates monorepo skeleton:
  - CLAUDE.md, README.md, Procfile
  - docker-compose.yml, go.work, .golangci.yml
  - .woodpecker.yml (template-provided CI)
  - scripts/ (discover, install, quality, dev)
  - pkg/ (8 shared packages from Aeries + Colix)
  - .claude/ (guides, skills, commands)
```

### Component Addition Flow

```
POST /projects/acme/components {"type": "service", "name": "auth-api"}
  ↓
Creates services/auth-api/:
  - cmd/server/main.go
  - internal/, Makefile, Dockerfile
  - component.yaml (port, deps)
  ↓
Auto-updates:
  - Procfile (add service entry)
  - go.work (add module)
  - CLAUDE.md (add routing)
  - .woodpecker.yml (add build step for component)
```

### Monorepo Structure

```
acme/
├── CLAUDE.md                    # AI router
├── Procfile                     # Local dev (auto-updated)
├── docker-compose.yml           # Local services
├── go.work                      # Go workspace (auto-updated)
├── scripts/                     # Discovery scripts
├── pkg/                         # Shared packages (8 total)
├── services/auth-api/           # Go API component
├── workers/email-worker/        # Background worker component
├── apps/dashboard/              # Frontend component
└── cli/acme-cli/                # CLI tool component
```

## Shared Packages (pkg/)

Combines best patterns from Aeries (chassis) and Colix (modular):

| Package | Source | Purpose |
|---------|--------|---------|
| `app/` | Aeries chassis | Service bootstrapper |
| `middleware/` | Colix | HTTP middleware (CORS, recovery, request_id, logger) |
| `httpcontext/` | Colix | Type-safe context helpers |
| `httpresponse/` | Aeries+Colix | JSON helpers + envelope pattern |
| `httpvalidation/` | Colix | Request validation |
| `logging/` | Both | Structured logging (slog + env detection) |
| `config/` | Aeries | Configuration via viper |
| `httpclient/` | Both | Resilient HTTP client with retry |

## Component Types

| Type | Directory | Template | Identifier |
|------|-----------|----------|------------|
| Service | `services/` | go-api | `Makefile` or `go.mod` |
| Worker | `workers/` | worker | `Makefile` or `go.mod` |
| App | `apps/` | app-astro, app-react | `package.json` |
| CLI | `cli/` | cli | `Makefile` or `go.mod` |

## Template Migration

| Current Template | New Location | Component Type |
|------------------|--------------|----------------|
| `go-api` | `components/service/` | `services/*` |
| `astro-landing` | `components/app-astro/` | `apps/*` |
| `default` | Becomes skeleton | N/A |

## Related Topics

- [Template Provider](../services/template-provider.md) - Current template system
- [Project Service](../services/project-service.md) - Project lifecycle
- [Build Orchestration](./build-orchestration.md) - Component builds
