NNO Documentation

Note: Onboarding is a cross-service pipeline, not a standalone service directory. Routes live in services/registry/ at /api/v1/onboarding. This doc exists in services/ for discoverability alongside the services it coordinates.

Date: 2026-03-30 Status: Phase 1 (core pipeline) + Implemented (session tracking via onboarding_sessions) + Phase 2 (advanced flows)

1. Overview

The onboarding pipeline orchestrates new platform setup from signup to first working deployment. It is a cross-service pipeline — not a standalone service — coordinating Registry (data layer), Provisioning (CF resource creation), and CLI Service (GitHub repo + CF Pages).

Cross-reference: The onboarding_sessions table is defined in services/registry.md §1.15. The onboarding routes live in the Registry service at /api/v1/onboarding.

2. Pipeline Steps [Phase 1]

Every onboarding session follows a 5-step pipeline:

Step	Service	Description
`create_platform`	Registry	Insert platform record, generate platform ID
`provision_infra`	Provisioning	Bootstrap CF resources (auth D1, auth Worker, secrets) via `PROVISION_PLATFORM` job
`setup_repo`	CLI Service	Create GitHub repo from `nno-stack-starter` template
`deploy_services`	CLI Service	Trigger CF Pages build, provision secrets
`verify`	Registry	Confirm all resources registered, platform status `active`

3. API Surface [Phase 1]

All endpoints are proxied via Gateway at /api/v1/onboarding/* → NNO_REGISTRY.

Method	Path	Description
`POST`	`/api/v1/onboarding`	Create session — validates input, inserts default steps, optionally triggers provisioning
`GET`	`/api/v1/onboarding/:id`	Fetch session by ID
`PATCH`	`/api/v1/onboarding/:id`	Update steps, status, or provisionJobId

Request Schema (POST):

Field	Type	Required	Description
`platformName`	string	yes	Human-readable platform name
`slug`	string	yes	URL-safe identifier (validated regex)
`stackTemplateId`	string	no	Optional stack template to activate
`tier`	string	yes	Billing tier (`starter`/`growth`/`scale`)
`userId`	string	yes	User initiating onboarding

Response (202):

{
  "onboardingId": "abc123",
  "jobId": "job-xyz",
  "status": "in_progress",
  "steps": [
    { "key": "create_platform", "status": "pending", "label": "Create platform" },
    { "key": "provision_infra", "status": "pending", "label": "Provision infrastructure" },
    { "key": "setup_repo", "status": "pending", "label": "Set up repository" },
    { "key": "deploy_services", "status": "pending", "label": "Deploy services" },
    { "key": "verify", "status": "pending", "label": "Verify deployment" }
  ]
}

4. Integration Flow [Phase 1]

Console UI → Gateway /api/v1/onboarding → Registry (create session)
                                              ↓ (service binding)
                                         Provisioning /api/v1/provision/onboard
                                              ↓ (queue)
                                         Job executor (PROVISION_PLATFORM steps)
                                              ↓ (callback)
                                         Registry (update session status)

5. Session States

Status	Description
`pending`	Session created, provisioning not yet started
`in_progress`	Provisioning job running
`completed`	All steps finished successfully
`failed`	One or more steps failed

6. Phase 1 Failure Handling

In Phase 1, failed onboarding sessions remain in failed status. There is no automated resume:

Inspect: GET /api/v1/onboarding/:id — check which step failed and the error in the step's result field
Retry: Create a new onboarding session with the same parameters. Provisioning idempotency (409 Conflict = success) prevents duplicate resource creation.
Manual cleanup: If partial resources were created, use the provisioning DEPROVISION_PLATFORM job to clean up before retrying.

Automated resume from the last successful step is Phase 2.

7. Advanced Onboarding Flows

Stack-based onboarding [Phase 2]: When stackTemplateId is provided, activate stack features after platform bootstrap
Session persistence [Implemented]: onboarding_sessions D1 table for long-lived session tracking is live — the table schema is defined in services/registry.md §1.15
Resume [Phase 2]: Allow resuming a failed onboarding from the last successful step
Webhook notifications [Phase 2]: Notify external systems on onboarding completion

Onboarding Pipeline