# drivestream-lab/launchpad architecture

> Architecture diagram of the GitHub repository drivestream-lab/launchpad, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/drivestream-lab/launchpad
- Repository: https://github.com/drivestream-lab/launchpad

## Overview

1. **What this repo is**
   - Launchpad is a **Python-based factory kit** for engineering orgs.
   - It combines **configuration-driven org bootstrapping**, **SDD/harness conventions**, and **tenant-specific work seeding**.
   - Architecturally, it is not an application backend; it is a **CLI tool plus playbook/docs plus templates** that act on a separate private tenant repo.

2. **Primary runtime boundary**
   - The `launchpad/` package is the executable core, exposed through `bin/launchpad` and `launchpad.__main__`.
   - The repo itself is mostly **control plane logic**: it reads YAML/config, generates files, and talks to forge APIs when needed.
   - The “real customer data” and operating truth live outside this repo in a private `<client>-meta` tenant repository.

3. **Two main operational lanes**
   - **Factory lane**: org setup, gitflow policy, project/board bootstrapping, and work seeding into GitHub or GitLab.
   - **Harness lane**: repo-local scaffolding, harness pinning, rules/skills sync, and verification for app repositories.
   - These are separated by intent: factory commands mutate forge/tenant state, while harness commands manage the standardized repo agent surface.

4. **Tenant repository as the main data source**
   - The private tenant repo contains client-specific YAML and content under `config/`, `work/`, `prd/`, `planning/`, `programs/`, and `wiki/`.
   - Launchpad reads this tenant content to decide what to provision or publish.
   - This is a key boundary for architecture diagrams: Launchpad code is generic, while tenant repos carry org-specific truth and manifests.

5. **Configuration-driven provisioning**
   - The config subsystem centers on YAML schemas with `apiVersion: launchpad/v1`.
   - `launchpad/config.py`, `paths.py`, `clients.py`, and related modules appear to manage locating tenant roots, client registries, and file paths.
   - The architecture depends on **filesystem-based config discovery** more than long-lived server state.

6. **Forge integration layer**
   - `launchpad/github_client.py`, `github_ops.py`, and `forge.py` represent the GitHub side of the factory.
   - `launchpad/adapters/gitlab/` provides a separate adapter path for GitLab, currently described as partial support.
   - The design suggests a **forge abstraction** where GitHub is the primary implementation and GitLab is an adapter with narrower scope.

7. **Org bootstrap and policy enforcement**
   - `bootstrap_org.py`, `bootstrap_teams.py`, `gitflow.py`, and `gitflow_policy.py` implement org-level setup and enforcement.
   - These modules likely translate tenant config into forge-side resources such as org structure, teams, branch rules, and project policies.
   - In the mental model, this is the “infrastructure as code” part of the repo, except the target is an engineering org forge.

8. **Work seeding and issue creation flow**
   - `seed_work.py` is the bridge from tenant work manifests to forge issues/boards.
   - Example manifests live in `examples/tenant-meta/work/` and `examples/onboarding-*.yaml`.
   - Data flow: tenant work YAML → Launchpad parser/model → forge adapter → issues/labels/board entries.

9. **Harness subsystem**
   - `launchpad/harness.py`, `verify/`, `factory_verify.py`, `doctor.py`, `issue_types.py`, and `wiki.py` support repo conformance and publication tasks.
   - Harness commands manage pinned rules, agent skills, and repo-local metadata such as `AGENTS.md` and `.harness-pin.yaml`.
   - `verify/runner.py` and `verify/checks.py` indicate a rule/check framework that validates repo state against tenant configuration.

10. **Scaffolding subsystem**
   - `launchpad/scaffold/` is a template-driven repo/service generator.
   - `profiles.py` and `run.py` indicate profile-based scaffolds, with a CLI wrapper in `scaffold/cli.py`.
   - The fixture under `tests/fixtures/scaffold-python-minimal/` shows scaffolding is meant to produce a new service skeleton, not just modify existing repos.

11. **Onboarding subsystem**
   - `launchpad/onboarding/` is a separate workflow engine for planning and applying onboarding from an `onboarding.yaml`-style spec.
   - The presence of `interview.py`, `plan.py`, `render.py`, `templates_gen.py`, and `registry.py` suggests it collects requirements, builds an onboarding plan, and renders outputs.
   - This subsystem is distinct from factory bootstrap: it is about **client onboarding workflow**, not org resource provisioning alone.

12. **Documentation and playbook as architecture inputs**
   - `playbook/` and `docs/` are not decorative; they encode operating model, SDD rules, and repo layout expectations.
   - Templates under `templates/` define canonical repo content such as `AGENTS.md`, CODEOWNERS, issue templates, CI workflows, and harness pins.
   - For diagrams, these should be treated as **authoritative templates/standards** consumed by scaffold/sync commands, not as runtime code.

13. **Examples and tests define the contract**
   - `examples/tenant-meta/` is a full sample tenant skeleton showing the expected client-side file structure.
   - `tests/test_onboarding.py` and `tests/test_scaffold.py` indicate the two most important executable contracts are onboarding and scaffolding behavior.
   - The CI workflow in `.github/workflows/ci.yml` validates the package and these flows in automation.

14. **External services and operational dependencies**
   - GitHub is the primary forge; GitLab is supported in a narrower adapter path.
   - Private rules repositories and the external `prayog-skills` bundle are part of the harness boundary, but intentionally not shipped as plain content inside the public kit.
   - `GITHUB_TOKEN`-backed operations and multi-machine client registries indicate the tool is designed for operator-run automation, not a self-hosted daemon.

15. **The simplest architecture picture**
   - **Launchpad repo** provides CLI, templates, and policy logic.
   - **Tenant repo** provides client truth and manifests.
   - **Forge** receives generated org/project/issue state.
   - **Private rules/skills** define the agent constitution and repo behavior.
   - The key flow is: tenant config and work specs in → Launchpad transforms and validates → forge and repo artifacts out.

Main entry points: [`launchpad/forge.py`](https://github.com/drivestream-lab/launchpad/blob/main/launchpad/forge.py) (Forge), [`examples/tenant-meta/README.md`](https://github.com/drivestream-lab/launchpad/blob/main/examples/tenant-meta/README.md) (Tenant meta), [`launchpad/config.py`](https://github.com/drivestream-lab/launchpad/blob/main/launchpad/config.py) (Config), [`launchpad/seed_work.py`](https://github.com/drivestream-lab/launchpad/blob/main/launchpad/seed_work.py) (Seed work)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_cli_core["CLI Core"]
  node_node_bin_cli["launchpad<br/>CLI entrypoint"]
  node_node_main["__main__<br/>Python entrypoint<br/>[__main__.py]"]
  node_node_config["Config<br/>tenant discovery<br/>[config.py]"]
  node_node_paths_clients["Paths & clients<br/>filesystem registry<br/>[paths.py]"]
end

subgraph group_group_factory["Factory Lane"]
  node_node_forge["Forge<br/>[forge.py]"]
  node_node_github_ops["GitHub ops<br/>GitHub integration<br/>[github_ops.py]"]
  node_node_github_client["GitHub client<br/>API client<br/>[github_client.py]"]
  node_node_gitlab_adapter["GitLab adapter<br/>partial adapter<br/>[client.py]"]
  node_node_bootstrap_org["Org bootstrap<br/>org provisioning<br/>[bootstrap_org.py]"]
  node_node_bootstrap_teams["Team bootstrap<br/>rbac setup<br/>[bootstrap_teams.py]"]
  node_node_gitflow["Gitflow<br/>branch policy<br/>[gitflow.py]"]
  node_node_gitflow_policy["Policy rules<br/>enforcement<br/>[gitflow_policy.py]"]
  node_node_seed_work["Seed work<br/>issue seeding<br/>[seed_work.py]"]
end

subgraph group_group_harness["Harness Lane"]
  node_node_harness["Harness<br/>repo conformance<br/>[harness.py]"]
  node_node_verify["Verify<br/>rule checks<br/>[runner.py]"]
  node_node_scaffold["Scaffold<br/>template generator<br/>[run.py]"]
end

subgraph group_group_onboarding["Onboarding"]
  node_node_onboarding["Onboarding<br/>workflow engine<br/>[plan.py]"]
  node_node_render["Render<br/>output generation<br/>[render.py]"]
end

subgraph group_group_content["Content & Examples"]
  node_node_playbook["Playbook<br/>operating model<br/>[README.md]"]
  node_node_templates["Templates<br/>[README.md]"]
  node_node_tenant_examples[("Tenant meta<br/>sample tenant repo<br/>[README.md]")]
end

node_node_bin_cli -->|"invokes"| node_node_main
node_node_main -->|"loads"| node_node_config
node_node_config -->|"resolves"| node_node_paths_clients
node_node_config -->|"reads shape from"| node_node_tenant_examples
node_node_forge -->|"primary impl"| node_node_github_ops
node_node_github_ops -->|"uses"| node_node_github_client
node_node_forge -.->|"alternate impl"| node_node_gitlab_adapter
node_node_bootstrap_org -->|"provisions via"| node_node_forge
node_node_bootstrap_teams -->|"provisions via"| node_node_forge
node_node_gitflow -->|"enforced by"| node_node_gitflow_policy
node_node_gitflow_policy -->|"applies to"| node_node_forge
node_node_seed_work -->|"creates"| node_node_forge
node_node_seed_work -->|"consumes"| node_node_tenant_examples
node_node_harness -->|"runs"| node_node_verify
node_node_harness -->|"syncs"| node_node_templates
node_node_scaffold -->|"renders from"| node_node_templates
node_node_scaffold -->|"produces shape like"| node_node_tenant_examples
node_node_onboarding -->|"renders"| node_node_render
node_node_onboarding -->|"plans from"| node_node_tenant_examples
node_node_playbook -->|"defines"| node_node_harness
node_node_playbook -->|"guides"| node_node_bootstrap_org
node_node_templates -->|"consumed by"| node_node_scaffold
node_node_tenant_examples -->|"source data for"| node_node_seed_work

click node_node_bin_cli "https://github.com/drivestream-lab/launchpad/tree/main/bin/launchpad"
click node_node_main "https://github.com/drivestream-lab/launchpad/blob/main/launchpad/__main__.py"
click node_node_config "https://github.com/drivestream-lab/launchpad/blob/main/launchpad/config.py"
click node_node_paths_clients "https://github.com/drivestream-lab/launchpad/blob/main/launchpad/paths.py"
click node_node_forge "https://github.com/drivestream-lab/launchpad/blob/main/launchpad/forge.py"
click node_node_github_ops "https://github.com/drivestream-lab/launchpad/blob/main/launchpad/github_ops.py"
click node_node_github_client "https://github.com/drivestream-lab/launchpad/blob/main/launchpad/github_client.py"
click node_node_gitlab_adapter "https://github.com/drivestream-lab/launchpad/blob/main/launchpad/adapters/gitlab/client.py"
click node_node_bootstrap_org "https://github.com/drivestream-lab/launchpad/blob/main/launchpad/bootstrap_org.py"
click node_node_bootstrap_teams "https://github.com/drivestream-lab/launchpad/blob/main/launchpad/bootstrap_teams.py"
click node_node_gitflow "https://github.com/drivestream-lab/launchpad/blob/main/launchpad/gitflow.py"
click node_node_gitflow_policy "https://github.com/drivestream-lab/launchpad/blob/main/launchpad/gitflow_policy.py"
click node_node_seed_work "https://github.com/drivestream-lab/launchpad/blob/main/launchpad/seed_work.py"
click node_node_harness "https://github.com/drivestream-lab/launchpad/blob/main/launchpad/harness.py"
click node_node_verify "https://github.com/drivestream-lab/launchpad/blob/main/launchpad/verify/runner.py"
click node_node_scaffold "https://github.com/drivestream-lab/launchpad/blob/main/launchpad/scaffold/run.py"
click node_node_onboarding "https://github.com/drivestream-lab/launchpad/blob/main/launchpad/onboarding/plan.py"
click node_node_render "https://github.com/drivestream-lab/launchpad/blob/main/launchpad/onboarding/render.py"
click node_node_playbook "https://github.com/drivestream-lab/launchpad/blob/main/playbook/README.md"
click node_node_templates "https://github.com/drivestream-lab/launchpad/blob/main/templates/README.md"
click node_node_tenant_examples "https://github.com/drivestream-lab/launchpad/blob/main/examples/tenant-meta/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_bin_cli,node_node_main,node_node_config,node_node_paths_clients toneBlue
class node_node_forge,node_node_github_ops,node_node_github_client,node_node_gitlab_adapter,node_node_bootstrap_org,node_node_bootstrap_teams,node_node_gitflow,node_node_gitflow_policy,node_node_seed_work toneAmber
class node_node_harness,node_node_verify,node_node_scaffold toneMint
class node_node_onboarding,node_node_render toneRose
class node_node_playbook,node_node_templates,node_node_tenant_examples toneIndigo
```

## Components

### CLI Core

Executable package and shared control-plane logic.

- [launchpad](https://github.com/drivestream-lab/launchpad/tree/main/bin/launchpad): CLI entrypoint · Executable wrapper that launches the tool. · `bin/launchpad`
- [__main__](https://github.com/drivestream-lab/launchpad/blob/main/launchpad/__main__.py): Python entrypoint · Module entrypoint for running the package as a command. · `launchpad/__main__.py`
- [Config](https://github.com/drivestream-lab/launchpad/blob/main/launchpad/config.py): tenant discovery · Loads YAML config and discovers tenant/client roots. · `launchpad/config.py`
- [Paths & clients](https://github.com/drivestream-lab/launchpad/blob/main/launchpad/paths.py): filesystem registry · Resolves repository paths and client registry state. · `launchpad/paths.py`

### Factory Lane

Org bootstrap, policy, and work seeding into forge systems.

- [Forge](https://github.com/drivestream-lab/launchpad/blob/main/launchpad/forge.py): forge abstraction · Shared boundary for forge operations across providers. · `launchpad/forge.py`
- [GitHub ops](https://github.com/drivestream-lab/launchpad/blob/main/launchpad/github_ops.py): GitHub integration · Primary GitHub-side automation and mutation layer. · `launchpad/github_ops.py`
- [GitHub client](https://github.com/drivestream-lab/launchpad/blob/main/launchpad/github_client.py): API client · Low-level GitHub API client support. · `launchpad/github_client.py`
- [GitLab adapter](https://github.com/drivestream-lab/launchpad/blob/main/launchpad/adapters/gitlab/client.py): partial adapter · Narrow GitLab integration path for supported operations. · `launchpad/adapters/gitlab/client.py`
- [Org bootstrap](https://github.com/drivestream-lab/launchpad/blob/main/launchpad/bootstrap_org.py): org provisioning · Creates and configures org-level forge resources. · `launchpad/bootstrap_org.py`
- [Team bootstrap](https://github.com/drivestream-lab/launchpad/blob/main/launchpad/bootstrap_teams.py): rbac setup · Sets up teams and access structure. · `launchpad/bootstrap_teams.py`
- [Gitflow](https://github.com/drivestream-lab/launchpad/blob/main/launchpad/gitflow.py): branch policy · Defines branching conventions and operating flow. · `launchpad/gitflow.py`
- [Policy rules](https://github.com/drivestream-lab/launchpad/blob/main/launchpad/gitflow_policy.py): enforcement · Validates or applies gitflow policy constraints. · `launchpad/gitflow_policy.py`
- [Seed work](https://github.com/drivestream-lab/launchpad/blob/main/launchpad/seed_work.py): issue seeding · Transforms tenant work specs into forge issues and board entries. · `launchpad/seed_work.py`

### Harness Lane

Repo-local scaffolding, verification, and conformance management.

- [Harness](https://github.com/drivestream-lab/launchpad/blob/main/launchpad/harness.py): repo conformance · Manages repo-local harness pins, skills, and standards sync. · `launchpad/harness.py`
- [Verify](https://github.com/drivestream-lab/launchpad/blob/main/launchpad/verify/runner.py): rule checks · Runs checks against repo state and tenant expectations. · `launchpad/verify/runner.py`
- [Scaffold](https://github.com/drivestream-lab/launchpad/blob/main/launchpad/scaffold/run.py): template generator · Generates new repo/service skeletons from profiles. · `launchpad/scaffold/run.py`

### Onboarding

Spec-driven client onboarding workflow.

- [Onboarding](https://github.com/drivestream-lab/launchpad/blob/main/launchpad/onboarding/plan.py): workflow engine · Builds and applies client onboarding plans from specs. · `launchpad/onboarding/plan.py`
- [Render](https://github.com/drivestream-lab/launchpad/blob/main/launchpad/onboarding/render.py): output generation · Renders onboarding artifacts and derived files. · `launchpad/onboarding/render.py`

### Content & Examples

Playbooks, templates, and sample tenant repository structure.

- [Playbook](https://github.com/drivestream-lab/launchpad/blob/main/playbook/README.md): operating model · Human-readable operating rules and delivery conventions. · `playbook/README.md`
- [Templates](https://github.com/drivestream-lab/launchpad/blob/main/templates/README.md): authoritative templates · Canonical repo files, issue templates, and CI/workflow skeletons. · `templates/README.md`
- [Tenant meta](https://github.com/drivestream-lab/launchpad/blob/main/examples/tenant-meta/README.md): sample tenant repo · Example tenant repository structure and client-specific config layout. · `examples/tenant-meta/README.md`

## Connections

- launchpad → __main__: invokes · CLI wrapper enters the Python package.
- __main__ → Config: loads · Entrypoint initializes configuration discovery.
- Config → Paths & clients: resolves · Config uses filesystem path and client lookup helpers.
- Config → Tenant meta: reads shape from · Tenant repo structure is the source of truth for expected config layout.
- Forge → GitHub ops: primary impl · GitHub is the main forge implementation.
- GitHub ops → GitHub client: uses · Operations layer depends on API client support.
- Forge → GitLab adapter: alternate impl · GitLab is supported through a narrower adapter path.
- Org bootstrap → Forge: provisions via · Org setup translates tenant config into forge resources.
- Team bootstrap → Forge: provisions via · Team setup applies RBAC and team structure to the forge.
- Gitflow → Policy rules: enforced by · Policy module constrains branching conventions.
- Policy rules → Forge: applies to · Policy rules materialize as forge-side enforcement.
- Seed work → Forge: creates · Work manifests are converted into issues and board state.
- Seed work → Tenant meta: consumes · Example work manifests illustrate the tenant input shape.
- Harness → Verify: runs · Harness uses verification checks to confirm repo conformance.
- Harness → Templates: syncs · Harness content is anchored by canonical templates and pins.
- Scaffold → Templates: renders from · Scaffolding uses template assets to generate repos.
- Scaffold → Tenant meta: produces shape like · Scaffold fixtures show the target skeleton structure.
- Onboarding → Render: renders · Onboarding plans are turned into concrete outputs.
- Onboarding → Tenant meta: plans from · Onboarding consumes onboarding-style specs and tenant layout.
- Playbook → Harness: defines · Playbook documents the standards that harness commands enforce.
- Playbook → Org bootstrap: guides · Operational guidance informs org bootstrap flows.
- Templates → Scaffold: consumed by · Template library feeds scaffolding and generated repo artifacts.
- Tenant meta → Seed work: source data for · Tenant work and config examples drive seeding behavior.