Create a Project and Approve an App Blueprint

Enterprise problem: A customer can describe an application but cannot safely hand an ambiguous prompt to any coding-agent platform: an attractive result may solve the wrong job, cross a data boundary, violate a compliance obligation, or provide no objective basis for approval.

Whole-course context: This first day starts the create-to-retire journey by creating a customer organization and project; later days generate, preview, connect, identify, share, publish, change, operate, export, and retire the resulting application.

Today’s slice: The customer defines an app archetype, separates project, application, preview, runtime, and data authority, then approves a provider-neutral, versioned App Blueprint in the platform control plane.

End-of-day evidence: A reviewer can inspect blueprint version bp-1, its acceptance cases, shared-invariant probes, approval receipt, and an evidence-ledger row with immutable identifiers.

Still unsolved: No source has been generated, no preview or managed store exists, and no enterprise connector, human identity, sharing policy, production release, or operating control is implied.

The customer outcome is compile a customer job into an executable blueprint. This day makes the mechanism observable before returning to policy, failure handling, and evidence; it does not repeat a requirements catalogue.

Blueprint service owns requirements/findings; review service owns approvals; generator consumes approved digests. Compute: control-plane API and validators. Storage: PostgreSQL blueprints/approvals, object storage attachments; Redis is not an authority.

Compile typed workflows, data boundaries, integrations, acceptance cases, and exclusions. Reject missing denial cases or underspecified authority before an agent run exists.

A single architecture diagram either hides the customer outcome or overwhelms the reader with controls, so it is easy to approve a locally plausible design that fails the complete lifecycle. Follow one recurring customer example—Northstar’s Workboard app—through a sequence that expands the same system without changing its ownership rules.

Northstar wants editors to create and complete tenant-scoped Workboard todos while viewers can only read them. Today completes only create project and approve blueprint inside the full create → generate → preview/interact → managed data → enterprise connectors/private connectivity → identity → share/revoke → publish → change/redeploy/rollback → operate/support → export/retire/delete journey.

It shows the complete customer lifecycle and marks today’s exact Workboard hand-off, so an approved plan is not mistaken for running software.

If a requirement cannot name its lifecycle stage, owner, future evidence, and retirement effect, keep it unresolved rather than hiding it in today’s scope.

The blueprint already names later ownership, evidence, rollback, retention, export, and deletion expectations, but grants none of those later capabilities. Retirement and compliance are design inputs, not cleanup promises.

Northstar does not need to understand every service before deciding whether Workboard is safe to generate. The smallest complete model is one customer intent, one governed transformation, and one reviewable output that cannot be used until an authorized person approves it.

It introduces the minimum prompt-to-decision system before exposing implementation parts.

If the output lacks an immutable contract, an explicit approve-or-reject decision, or independent evidence, do not grant generation eligibility.

For Workboard, “tenant isolation” is not enough. The transformation must produce named actors, resources, scopes, denial cases, retry rules, independent oracles, and deferred risks that a reviewer can challenge.

A shared identifier can tempt a team to reuse authority across planes, turning Northstar project membership into unintended Workboard or enterprise-data access. Expand the three-box model into the provider/control-plane, hosted-runtime, generated-application, and connector/source boundaries that remain independently owned and revocable.

It separates who owns policy, execution, Workboard data, connector authority, and source truth, and makes every mapping explicitly revocable.

Treat every cross-boundary mapping as deny-by-default, least-privilege, audited, and independently revocable; a token or membership in one plane never proves authority in another.

Today creates only control-plane records. It does not create the runtime, Workboard database, connector grant, or source-account authority shown downstream.

Once the boundaries are visible, duplicated rules and services with mixed responsibilities become the next risk: a copied tenant rule can drift between the prompt parser, approval code, tests, and a future provider adapter. Expand the control-plane box into single-responsibility services, authoritative stores, provider ports, and a declarative infrastructure-as-code contract.

It assigns one reason to change per service, one authoritative owner per durable record, and one provider-neutral contract whose adapters translate capabilities without claiming Daytona and Cloudflare parity.

Keep policy and invariants in versioned declarative references, keep business decisions outside adapters, and fail closed when an adapter cannot prove a required capability.

A validated blueprint can still be approved under the wrong actor, become stale, or conceal a failed recovery, so the complete system closes the Workboard loop with observed E2E paths. Every branch begins with the customer prompt and terminates in immutable evidence rather than a model’s success claim.

It connects the customer action to positive, denial, operational failure, and recovery branches whose terminal records can be independently reviewed.

A path is complete only when expected and observed results, actor, resource, scope, precondition, environment, trusted timestamp, and immutable run, trace, source, or artifact identifiers agree.

A customer who sees sandboxes, models, and databases before seeing the application journey cannot tell what product outcome those components serve, so architecture can look complete while the customer remains unable to create anything. The product is a provider-portable enterprise coding-agent platform whose first customer action is to create a project and approve what should be built; Workboard remains only the fictional worked application.

The complete journey is create → generate → preview and interact → manage app data → connect enterprise data → configure identity → share or revoke → publish → change or roll back → operate → export → retire. Today stops at the first arrow, represented by the customer-flow diagram above before its dotted hand-off. It produces a build contract; it does not pretend that a plan is running software.

A customer organization is the billing and administrative container. A project is the control-plane record that owns one blueprint lineage, source workspace, agent runs, preview registrations, collaborators, and release policy. An app is the generated product with its own domain model, tenants or audiences, roles, and data. A preview is a non-production endpoint for one revision. A runtime is the isolated compute environment that executes an artifact. These are related identifiers, never interchangeable authority.

The primary lab creates project launch-ops for a Workboard-style workflow app. The customer supplies a job statement, selects an archetype, reviews generated requirements, changes a weak denial case, and approves bp-1. Approval is explicit and version-specific: editing the blueprint creates bp-2-draft and does not silently extend the earlier receipt.

One successful todo application cannot establish that a platform builds arbitrary applications, so a product claim based only on Workboard would be unfalsifiable and misleading. The course uses three deliberately different archetypes to test a bounded envelope; passing them supports only the named invariants and capabilities.

An identifier or token from one boundary can look reusable in another, and that confusion can turn project collaboration into data access. The blueprint therefore names ownership before it names implementation.

Natural-language intent leaves success and danger open to interpretation, so an agent and customer can both claim success while referring to different applications. An App Blueprint is the versioned control-plane contract that makes the customer job, constraints, and review oracles executable.

The blueprint contains:

• projectId, appArchetype, blueprintVersion, status, author, and approval receipt;
• job statement, users or audiences, in-scope workflows, exclusions, and material assumptions;
• domain entities, state transitions, invariants, retention class, and expected data authority;
• acceptance cases for success, denial, invalid input, retry, failure, and recovery;
• accessibility, latency, reliability, compatibility, cost, and security budgets;
• allowed dependencies, runtime needs, prospective connectors, and prohibited capabilities;
• evidence required at generation, preview, publication, and operation milestones.

An acceptance case fixes observable behaviour without prematurely choosing component names or table layouts:

id: WB-TODO-001
actor: synthetic editor scoped to app-tenant-alpha
resource: board/alpha-planning/todo
scope: app:workboard environment:preview tenant:alpha
precondition:
  - the board belongs to tenant alpha
  - the actor has editor permission for that board
action: create a todo titled Prepare launch notes twice with one idempotency key
expected:
  - one open todo is persisted in tenant alpha
  - both responses identify the same logical result
  - tenant beta observes neither the record nor its existence
oracle: API assertions, tenant-scoped database query, and browser assertion

An oracle is the rule that decides pass or fail. Exact response schemas, database constraints, accessibility-tree assertions, and measured thresholds are stronger primary oracles than the generating model reviewing its own work. Model judgement may support a human rubric for clarity, but it cannot override a deterministic tenant-isolation failure.

If approval is merely a chat message, later runs cannot prove which requirements were authorized, so revisions can acquire accidental scope. The executable workflow below makes approval a customer-visible, immutable transition.

1. Create organization northstar and project launch-ops; record the initiating administrator and control-plane scope.
2. Select the Workboard workflow archetype and describe the job: editors create and complete tenant-scoped todos; viewers read but do not mutate.
3. Generate bp-1-draft, then inspect its actors, resources, exclusions, budgets, and boundary map.
4. Reject the vague sentence “other tenants cannot access todos” and replace it with actor, resource, operation, response, no-mutation, and no-existence-leak expectations.
5. Attach the three shared-invariant probe packs: Workboard mutation, revenue-dashboard lineage, and public-intake anonymous-write isolation. The latter two are compatibility probes, not features to generate in this project.
6. Run blueprint validation: referenced scopes exist, every protected action has a denial case, every write names idempotency and validation rules, and every claim names an oracle.
7. Approve digest sha256:bp1-example as bp-1; verify bp-2-draft requires a new approval.

The customer-flow diagram above is the executable state transition for this lab: its draft, validation, revise, approval, and later-run hand-off preserve the same version boundary. The lab passes only if an unapproved draft cannot start generation, the receipt contains the blueprint digest and approver scope, and an edit invalidates the receipt. This is the day’s one primary executable workflow; connector schemas, identity protocols, and production release mechanics remain reference fields only.

A green badge detached from its actor, scope, artifact, time, and environment cannot support an enterprise decision, because it may describe a different revision or authority. Every lab observation therefore becomes an append-only evidence row whose detailed artifacts live in immutable storage.

Product claims become hard to audit when their security and quality terms come from informal summaries, so the blueprint should reference versioned primary standards. These official sources supply requirements that can be adapted into application-specific cases rather than copied as universal proof.

• NIST SP 800-218, Secure Software Development Framework 1.1 — outcome-focused secure-development practices and evidence across the software lifecycle.
• NIST AI Risk Management Framework 1.0 — governance, context mapping, measurement, and managed residual risk for AI-enabled systems.
• OWASP Application Security Verification Standard — versioned application-security requirements suitable for turning threats into testable criteria.
• W3C Web Content Accessibility Guidelines 2.2 — normative accessibility success criteria for a declared conformance target.

Without a short decision summary, reviewers can lose the product contract inside its details and approve generation against the wrong scope. Keep these governing rules visible when the blueprint moves to the agent runtime.

• The first customer milestone is an approved, versioned App Blueprint, not generated code.
• Workboard, a revenue dashboard, and a public intake app test a bounded archetype envelope; none proves universal app support.
• Project, preview, runtime, app, connector, and source-system scopes carry separate authority and data lifecycles.
• Shared invariants become credible only when each archetype has a named falsifier.
• Approval binds one digest, actor scope, policy version, and evidence record; later edits require review again.

A blueprint can look thorough while retaining vague boundaries or untestable promises, so a final customer review must try to reject it. Each checked item should point to a blueprint field or immutable evidence row.

• [ ] The customer organization and project exist with explicit owners and lifecycle states.
• [ ] The job, archetype, in-scope workflow, exclusions, assumptions, and deferred risks are explicit.
• [ ] The six authority boundaries and data owners are named without implicit token reuse.
• [ ] Workboard, revenue-dashboard, and public-intake probes challenge the shared invariants.
• [ ] Acceptance cases include success, denial, invalid input, retry, and failure observations.
• [ ] Every primary oracle is independent of the generating model.
• [ ] The approval receipt binds actor, scope, blueprint digest, policy, timestamp, and environment.
• [ ] Editing an approved blueprint creates an unapproved version rather than mutating history.
• [ ] No source generation, preview, connector, identity, share, publish, or operating claim is implied.

The first runnable building block is the control-plane approval boundary in approve-blueprint.ts. Use Northstar's supplier-onboarding workflow as the recurring product case: procurement, security, and legal approve one immutable blueprint before an agent run can start.

export class ApproveBlueprintUseCase {
  public constructor(
    private readonly repository: BlueprintRepository,
    private readonly unitOfWork: BlueprintUnitOfWork,
    private readonly clock: Clock,
    private readonly ids: IdGenerator,
  ) {}

  public async execute(context: RequestContext, command: ApproveBlueprintCommand) {
    if (!context.roles.includes('blueprint:approve')) {
      throw new BlueprintAccessDeniedError('Subject cannot approve blueprints');
    }
    const approved = approveBlueprint(
      context.tenantId,
      command,
      context.subjectId,
      this.clock.now(),
    );
    const eventId = this.ids.next();
    const event: BlueprintApprovedV1 = {
      eventId,
      eventType: 'BlueprintApproved.v1',
      schemaVersion: 1,
      occurredAt: approved.approvedAt.toISOString(),
      tenantId: context.tenantId,
      aggregateId: command.blueprintId,
      idempotencyKey: `${context.tenantId}:${command.blueprintId}:${command.version}:approved`,
      correlationId: context.correlationId,
      causationId: null,
      traceparent: null,
      payload: {
        blueprintId: command.blueprintId,
        projectId: command.projectId,
        digest: approved.digest,
        approvedBy: context.subjectId,
      },
    };
    await this.unitOfWork.commit(approved, event);
    return approved;
  }
}

The snippet's declared intent is “approve exactly one tenant-bound definition.” NestJS calls the use case, the domain function computes an immutable digest, and the unit of work changes blueprint and outbox state together. In memory this consumes the Node.js process's CPU and RAM; the production adapter maps the same ports to database disk and network I/O. The returned digest and BlueprintApproved.v1 outbox row are the observable proof.

SRP keeps authorization, domain approval, and persistence separate. DRY puts event and ID shapes in packages/contracts. IoC and DI make the repository, clock, identifier source, and unit of work replaceable. MVC keeps HTTP parsing in the controller and policy-rich work in the application/domain layers. PubSub begins with the transactional event; IaC later provisions the database and event bus without changing this use case.

Run the focused test, then the cross-service product probe:

pnpm vitest run services/control-plane/src/control-plane.test.ts
pnpm smoke:product

Falsify the claim by removing blueprint:approve, changing the workflow after approval, or reusing the blueprint ID from another tenant. Evidence passes only if access is denied without disclosure, a changed definition receives a different digest, and no second mutable approval overwrites the first. This proves the approval boundary implemented in this repository; it does not prove that every blueprint is safe or complete.