Skip to content

🧱 Bootstrap Process

The bootstrap process is the ordered path from intent to build a new SaaS solution to a ready factory context: a project exists as the system-of-record, Azure DevOps anchors are in place, traceability identifiers are assigned, and orchestration can safely hand off to planning, template application, and service assembly. It sits immediately before the deep work described in the vision-to-production workflow and the long-form project lifecycle.

Bootstrap connects projects management—metadata, lifecycle state, and traceability—with the orchestration layer and DevOps surface so agents and pipelines operate on real repositories, boards, and conventions instead of a blank slate.

🎯 What bootstrap means here

  • System-of-record: The factory records canonical project metadata, ownership, and lifecycle position (see projects management).
  • Operational backbone: Git repositories, boards, wiki seeds, and CI/CD-oriented scaffolding are provisioned so downstream automation has stable targets (aligned with Cycle 1 and Cycle 2 in project lifecycle).
  • Traceability: projectId, traceId, and sessionId are assigned early so every later artifact and agent run can be correlated.
  • Unlock downstream work: Events signal that initialization and DevOps foundation steps are complete so coordinators and agents for planning, templates, and microservice assembly can run.

✅ Outcomes and success criteria

  • Project metadata is validated, stored, and addressable by orchestration and Studio.
  • Azure DevOps project (or equivalent, per platform support) exists with the expected repos, boards, and wiki entry points described in the lifecycle narrative.
  • Identifiers (projectId, traceId, sessionId) are assigned and propagated.
  • Events such as ProjectInitialized and DevOpsArtifactsReady have been emitted so downstream coordinators are not blocked.
  • Template and planning flows can start without re-doing structural setup (see template catalog and Phase 1 of the vision-to-production workflow).

🧭 Phased process (canonical story)

The table below uses neutral phase names. Implementation may map them to specific orchestrators or commands; see orchestration domain and Project Bootstrap Orchestrator for deeper detail.

Phase Purpose Primary ideas
1. Intent and project record Capture the decision to create a factory project and persist metadata. User or integration submits input via Studio or API; orchestration accepts CreateProjectCommand; validation and ID assignment.
2. Initialization Create the first DevOps-visible skeleton for the project. Azure DevOps project, initial repos (/src, /tests, /infra, /docs), boards and wiki seed; emit ProjectInitialized as described in project lifecycle — Cycle 1.
3. DevOps foundation Harden and complete the DevOps substrate (connections, variables, pipeline templates, trace anchors). Triggered after initialization; provision service connections, variable groups, shared YAML templates; emit DevOpsArtifactsReady per Project Bootstrap Orchestrator.
4. Handoff to planning and assembly Move from “empty but ready” to vision, architecture, and generated services. Connects to Vision to Architecture (Phase 1 of vision-to-production) and to microservice assembly patterns in orchestration domain (e.g. MicroserviceAssemblyCoordinator).

🔁 End-to-end bootstrap flow

flowchart TD
  subgraph entry [Entry]
    userAct["User or integration"]
    studio["Studio UI or API"]
  end

  subgraph record [Project record]
    pm["Projects domain and orchestration"]
  end

  subgraph ado [DevOps provisioning]
    adoWork["Azure DevOps project, repos, boards, wiki"]
  end

  subgraph signals [Signals]
    bus["Event bus"]
  end

  subgraph next [Downstream]
    planners["Planning and template flows"]
    assembly["Microservice assembly and pipelines"]
  end

  userAct --> studio
  studio --> pm
  pm --> adoWork
  adoWork --> bus
  bus --> planners
  bus --> assembly
Hold "Alt" / "Option" to enable pan & zoom

📣 Key events

Events and optional retries below are taken from project lifecycle — Cycle 1 and Project Bootstrap Orchestrator. Commands such as CreateProjectCommand are inputs to the orchestration layer, not domain events.

Event / command When it matters
CreateProjectCommand Submitted when creating a new project; orchestration validates and enriches metadata.
ProjectInitialized Emitted after initial repository, boards, and wiki setup; unlocks downstream orchestration (including further DevOps setup).
DevOpsArtifactsReady Emitted when foundational DevOps artifacts (connections, variable groups, pipeline templates, trace anchors) are in place.
RetryProjectBootstrap Optional retry if DevOps bootstrap fails or is reset.
ReconfigureDevOpsContext Optional follow-up when environments, repos, or pipelines need post-creation changes.

📦 Artifacts

The following mirror Cycle 1 artifacts in project lifecycle. Additional outputs (service connections, variable groups, YAML pipeline libraries) are detailed in Project Bootstrap Orchestrator.

Artifact Format Typical location
project-metadata.json JSON Azure DevOps docs/metadata/
Initial Wiki Home Page Markdown Azure Wiki
Azure Boards Feature Work Item JSON Azure DevOps Boards
Empty Git Repositories Git Azure DevOps Repos

🧑‍💼 Human-in-the-loop and constraints

  • Template and tooling choices: Users confirm source-control defaults and select solution templates as Cycle 2 describes in project lifecycle.
  • Azure DevOps today: For the current narrative, only Azure DevOps is assumed for Git, boards, pipelines, wiki, and reporting; other providers are future extensions (same source as Cycle 1 notes).
  • Approvals: Where the factory enforces gates, Studio or policy may require explicit confirmation before heavy provisioning or planning—without replacing the automated sequence above.

📊 Observability

Bootstrap must remain traceable end-to-end:

  • Preserve traceId (and related session context) across initialization, DevOps foundation, and the first planning handoffs.
  • Phase transitions should be observable so operators can see when initialization completed versus when DevOps artifacts became ready.
  • Durations such as time-to-ready for bootstrap align with the spirit of lifecycle and orchestration telemetry (e.g. tracking how long from project create to first downstream coordinator); exact metric names may follow your runtime implementation.

For additional orchestrator-level telemetry concepts, see the ProjectBootstrapOrchestrator and related sections in orchestration domain.

📚 Terminology and complementary docs

The Project Bootstrap Orchestrator coordinator page emphasizes Azure DevOps provisioning after a ProjectInitiator-style ProjectInitialized signal. The orchestration domain document also contains a section titled ProjectBootstrapOrchestrator that stresses planning agents (vision, enterprise architecture, microservice planning). Implementation naming may evolve; treat both pages as complementary detail on who does what after the project exists. This bootstrap process page describes the outcomes and sequence without requiring a single consolidated class name for every step.