jordan 8282d60c69 feat: implement composable monorepo template system with component architecture

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>

2026-01-31 19:11:42 -07:00

4.1 KiB

Raw Blame History

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

Template Provider - Current template system
Project Service - Project lifecycle
Build Orchestration - Component builds

4.1 KiB Raw Blame History