8282d60c69
Adds the composable monorepo template system that generates project skeletons with pluggable components (service, worker, app-react, app-astro, cli). Key changes: - Monorepo skeleton templates with shared pkg/, scripts/, and git hooks - Component templates (service, worker, app-react, app-astro, cli) with Dockerfiles, CI steps, and component.yaml manifests - Component domain model with validation and dependency resolution - Component handler endpoints for CRUD and composition - Template provider extended with BuildComposableProject and component assembly - Deployer extended with composable project deployment support - Handler timeout constants (TimeoutFastLookup through TimeoutLongRunning) - envutil package for centralized env var reads with defaults - api.DecodeJSON helper for standardized request body decoding - Standardized response helpers (WriteBadRequest, WriteNotFound, etc.) - Replaced fullstack-app cookbook with composable-app cookbook - Hardened handler timeouts, logging, and error responses across all handlers Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
114 lines
4.1 KiB
Markdown
114 lines
4.1 KiB
Markdown
# 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
|