claude-foundations/platformhub/process-template-patterns.md

# Process Template Patterns

Proven patterns for different deployment types, extracted from the PlatformHub-Demo project (30 microservices, 3 clouds, 8 teams).

## Design Principles

1. **One template per deployment pattern**, not per cloud or per service. Use parameters to vary behaviour.
2. **Parameters for everything that varies** between consuming projects: cloud target, language, database type, target tags.
3. **Sensible defaults** on parameters to reduce friction — consuming projects only override what differs.
4. **Every template needs a `worker_pool` parameter** (type `WorkerPool`) — this is mandatory.
5. **Inline scripts, not step template references** — process templates can't see step templates in other spaces.

## Template Catalogue

### Standard Go Service Deploy

**Use for:** Go microservices without special compliance or database requirements.
**Steps:** Unit tests → Security scan → Container image scan → Helm deploy → Monitoring
**Parameters:** `target_tags`, `cloud_target` (default: gcp), `worker_pool`
**Services example:** listing-service, search-service, category-service, config-service, order-service

Key characteristics:
- Go test output with race detection and coverage
- Semgrep SAST + Trivy SCA
- Distroless base image scan + SBOM generation
- Helm upgrade with cluster mapping by cloud target
- Prometheus ServiceMonitor + Grafana dashboard + SLO alerting

### Python ML Service Deploy

**Use for:** Python services, especially ML/data pipeline services with model dependencies.
**Steps:** Unit tests → Integration tests → Security scan → Container image scan → Helm deploy → Monitoring
**Parameters:** `target_tags`, `cloud_target` (default: gcp), `worker_pool`
**Services example:** recommendation-service, fraud-service, moderation-service, ml-platform, analytics-pipeline

Key characteristics:
- pytest with coverage table
- Docker-compose integration tests (model validation, data pipeline tests)
- Python-specific SAST (Semgrep + Bandit) + SCA (Safety + pip-audit)
- GPU resource requests in Helm deploy
- ML-specific monitoring: inference latency, model drift, batch queue depth

### Payment Service Deploy

**Use for:** Payment-path services requiring PCI-DSS compliance and zero-downtime deployment.
**Steps:** Unit tests → Security scan → Container image scan → PCI-DSS check → Blue-green deploy → Monitoring → Rollback check
**Parameters:** `target_tags`, `cloud_target` (default: aws), `worker_pool`
**Services example:** payment-gateway, wallet-service, ledger-service, payout-service, escrow-service

Key characteristics:
- Enhanced security scan with Gitleaks secret detection
- 6-check PCI-DSS compliance gate (image signature, SBOM, secrets, TLS, network policy, audit logging)
- Blue-green deployment with canary traffic phases (10% → 100%)
- 4-nines SLO (99.99%), payment-specific alerting (circuit breaker, refund rate)
- Post-deploy health validation with automatic rollback decision

### Database Service Deploy

**Use for:** Services with database dependencies requiring schema migrations.
**Steps:** Unit tests → Security scan → Database migration → Container image scan → Helm deploy → Monitoring
**Parameters:** `target_tags`, `cloud_target` (default: gcp), `database_type` (default: postgres), `language` (default: go), `worker_pool`
**Services example:** user-service, ledger-service, order-service (any service with a DB)

Key characteristics:
- Language-aware unit tests (Go/Python/Node switch)
- SQL injection-focused security rules
- Pre-migration snapshot with cloud-appropriate tooling (pg_dump, mysqldump, mongodump)
- Versioned migration with per-migration timing
- Post-migration validation (schema version, constraint check, data integrity)
- DB-specific monitoring: connection pool, slow queries, migration version mismatch

### Node.js Service Deploy

**Use for:** Node.js services including API gateways, messaging, and notification services.
**Steps:** Unit tests → Security scan → Container image scan → Helm deploy → Feature flag seeding → Monitoring
**Parameters:** `target_tags`, `cloud_target` (default: azure), `worker_pool`
**Services example:** messaging-service, notification-service, api-gateway

Key characteristics:
- Jest-style test output with coverage table
- npm audit + Trivy SCA
- Feature flag seeding with environment-aware rollout percentages
- Cloud-specific secrets manager integration (Azure Key Vault / AWS SM / GCP SM)
- Node.js-specific monitoring: event loop lag, heap usage, WebSocket connections

## How Projects Consume Templates

In a project's `deployment_process.ocl`:

```hcl
process_template "deploy-listing-service" {
    name = "Deploy Listing Service"
    process_template_slug = "standard-go-service-deploy"
    version_mask = "1.X"    # Auto-update minor/patch

    parameter "target_tags" {
        value = "gke-marketplace"
    }

    parameter "cloud_target" {
        value = "gcp"
    }

    parameter "worker_pool" {
        value = "WorkerPools-1"
    }
}
```

## Choosing the Right Template

```
Does the service handle payments or financial data?
  └── YES → Payment Service Deploy

Does the service have database migrations?
  └── YES → Database Service Deploy

Is the service Python-based (ML, data, analytics)?
  └── YES → Python ML Service Deploy

Is the service Node.js-based?
  └── YES → Node.js Service Deploy

Default → Standard Go Service Deploy
```

## Template-to-Service Mapping (PlatformHub-Demo)

| Template | Services |
|----------|----------|
| Standard Go Service | listing, search, search-indexer, category, media, config, event-bus, shipping, observability-collector, reporting, review, dispute |
| Python ML Service | recommendation, fraud, moderation, ml-platform, analytics-pipeline |
| Payment Service | payment-gateway, wallet, ledger, payout, escrow, kyc |
| Database Service | user, auth, user-activity, order (overlay with others) |
| Node.js Service | messaging, notification, api-gateway |

Note: Some services (like `order-service`) could use either Standard Go or Database Service depending on whether DB migrations are part of the deployment process.