kyc-backend

kyc-backend

Minimal HTTP API that embeds Maestro like a real KYC service.

This example shows how a backend service can:

• restore a workflow run per request
• submit user input into Maestro
• drive the workflow forward
• persist workflow snapshots
• return UI-friendly status responses

Unlike the smaller demos under examples/demos/, this app demonstrates a near real-world request/response integration shape.

Workflow

collect-profile -> document-upload -> run-liveness-check -> approved
                                              \-> manual-review -> approved

Passport uploads require manual review. Other document types auto-approve after liveness.

HTTP API

POST /kyc/start
GET  /kyc/{runID}
GET  /kyc/{runID}/events
POST /kyc/{runID}/profile
POST /kyc/{runID}/document
POST /kyc/{runID}/review

Mutating requests follow the same lifecycle:

restore run -> validate step -> SubmitInput -> RunUntilBlocked -> save snapshot -> return status

What this demo shows

• embedding Maestro behind REST handlers
• workflow persistence + restore per request
• SubmitInput on human steps
• app-owned business data beside workflow state
• step-to-status mapping for frontend APIs
• execution trace via /events
• workflow-first orchestration flow

Run

From the repository root:

go run ./examples/apps/kyc-backend

Server listens on :8080.

Override:

ADDR=:9000 go run ./examples/apps/kyc-backend

Example flow

Start a KYC run:

curl -s -X POST http://localhost:8080/kyc/start | jq

Save the returned run id:

export RUN_ID=run_xxxxxxxx

Submit profile:

curl -s -X POST "http://localhost:8080/kyc/${RUN_ID}/profile" \
  -H 'Content-Type: application/json' \
  -d '{
    "fullName":"Justin",
    "email":"justin@maestro.io"
  }' | jq

Submit document:

curl -s -X POST "http://localhost:8080/kyc/${RUN_ID}/document" \
  -H 'Content-Type: application/json' \
  -d '{
    "documentType":"national_id",
    "documentRef":"doc-123"
  }' | jq

Read current status:

curl -s "http://localhost:8080/kyc/${RUN_ID}" | jq

Read execution trace:

curl -s "http://localhost:8080/kyc/${RUN_ID}/events" | jq

Manual review path

Passport documents route to manual review:

curl -s -X POST "http://localhost:8080/kyc/${RUN_ID}/document" \
  -H 'Content-Type: application/json' \
  -d '{
    "documentType":"passport",
    "documentRef":"pass-456"
  }' | jq

Approve review:

curl -s -X POST "http://localhost:8080/kyc/${RUN_ID}/review" \
  -H 'Content-Type: application/json' \
  -d '{
    "approved": true
  }' | jq

Typical statuses:

awaiting_profile
awaiting_document
awaiting_review
approved

Project structure

Real-world mapping

In production:

• use pkg/run/postgres for run.Store (NewStore, SchemaDDL, or optional ApplySchema)
• replace the fake vendor with HTTP actions (examples/demos/http-runner)
• add workflow registries and versioning, auth, retries, observability, and async callbacks

Related examples

• library-basic — smallest embedding example
• embed-kyc-service — pause/resume + persistence
• http-runner — HTTP actions from workflows