# Build Orchestration

**Last Updated:** 2025-01
**Confidence:** High (Planned - see address-the-gaps.md)

## Summary

Build orchestration enables structured build specs for bot-driven development. Bots submit build requests with prompts, workers execute, and callbacks notify completion.

**Key Facts:**
- Build spec includes template, prompt, variables, auto_deploy flag
- Enqueues as work task for worker pool
- Auto-deploy commits, pushes, triggers Woodpecker CI
- Callback URL notified on completion with artifacts

**File Pointers:**
- Service: `internal/service/build_service.go`
- Handler: `internal/handlers/build.go`
- Work queue: `internal/port/work_queue.go`

## Build Spec Schema

```go
type BuildSpec struct {
    Template    string            `json:"template"`
    Prompt      string            `json:"prompt"`
    Variables   map[string]string `json:"variables"`
    AutoDeploy  bool              `json:"auto_deploy"`
    CallbackURL string            `json:"callback_url"`
}
```

## API Endpoint

```
POST /project/{name}/build
{
    "template": "astro-landing",
    "prompt": "Create a coming soon page with dark theme and threesix.ai branding",
    "auto_deploy": true,
    "callback_url": "https://pantheon.orchard9.ai/webhooks/build-complete"
}
```

## Orchestration Flow

1. Bot calls `POST /project/{name}/build`
2. BuildService validates project exists
3. Creates WorkTask with build spec
4. Enqueues to work queue
5. Returns task ID immediately
6. Worker picks up task:
   - Clones repo
   - Runs Claude with prompt
   - Commits and pushes (if auto_deploy)
7. Woodpecker builds and deploys
8. Callback notified with result

## Callback Payload

```json
{
    "task_id": "uuid",
    "project_id": "myapp",
    "status": "completed",
    "result": {
        "output": "...",
        "artifacts": {
            "commit_sha": "abc123",
            "deploy_url": "https://myapp.threesix.ai"
        }
    }
}
```

## Related Topics

- [Work Queue](../services/work-queue.md)
- [Worker Pool](../services/worker-pool.md)
- [Template Provider](../services/template-provider.md)