olsitec/foundation
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
foundation/documentation/decisions/ADR_005_repo_topology.md
Andreas Niemann f18676e6b3 chore: scaffold olsitec-foundation mono-repo 
Repo topology, baseline overlay, planning docs (PLAN-001/002), ADR-004/005,
and the bootstrap/packages/documentation skeleton. Implementation (T00+) not started.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-30 17:10:46 +02:00

3.1 KiB
Raw Permalink Blame History

ADR-005 — olsitec-foundation Repository Topology & Module Distribution

Date: 2026-06-30 Status: Accepted

Context

~/work/olsitec-foundation is the home for the foundation platform. We must decide repo boundaries: what is one mono-repo vs. separate repos, where shared Pulumi modules live, and how they are consumed both at day-zero (no registry yet) and in steady state (by downstream projects). Constraints:

  • The egg must be recoverable from {VM + repo + passphrase} (PLAN-002 §6) → favours few repos.
  • Shared modules must be independently consumable by other projects, hosted via the foundation → favours independent versioning/publishing.
  • The module registry is itself part of what the foundation builds → day-zero registry paradox.

Decision

Two git repositories under a non-git workspace root.

  1. foundation/ — a mono-repo (Bun workspaces) containing bootstrap/ (the egg Pulumi project), packages/pulumi-* (shared modules), and documentation/. This is the DR unit.
  2. ai-baseline/ — a single small repo for the cross-project agentic workflow pattern (ADR-003), re-homed from gitlab.com to foundation-Forgejo.

Downstream consumer projects (the K8s platform, products) stay outside this workspace and consume the foundation's published packages.

Module lifecycle: Vendor (copy into packages/, consumed locally via Bun workspace) → Publish (@olsitec/pulumi-* to the foundation npm registry once it exists) → Consume (downstream switches imports to the published versions; old olsicloud4/pulumi/modules/* frozen then removed).

Consequences

Easier:

  • Day-zero needs no registry: bootstrap/ resolves modules from packages/* on disk (resolves the registry paradox, PLAN-002 §5.2).
  • DR = one clone of foundation → egg + exact module sources together.
  • Shared modules still get independent semver + publishing (semantic-release-monorepo, Conventional Commits — see memory olsitec-charts-conventional-commits), so downstream pins versions.
  • ai-baseline stays light and on its own cadence for all projects.

Harder:

  • A mono-repo needs workspace tooling (Bun workspaces) and per-package release config.
  • Two consumption paths for a module during transition (local workspace for the egg, published registry for downstream) — must be documented per package.

Alternatives Considered

  • One giant mono-repo (foundation + ai-baseline + everything): rejected — couples the every-project baseline to the platform's weight and release cadence.
  • Polyrepo (each module its own repo): rejected — day-zero would need to clone N repos before the registry exists; DR friction; over-fragmentation at this scale.
  • Keep modules in olsicloud4, reference from there: rejected — the foundation must own its inputs for DR-from-nothing; it cannot depend on a Layer-1 repo.

Confidence

High — directly addresses the registry bootstrap paradox and the user's stated intent (vendor a copy now, host via the foundation later, downstream switches to the foundation-hosted module). Companion: 000_TOPOLOGY.md.