Andreas Niemann
f18676e6b3
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>
60 lines
3.1 KiB
Markdown
60 lines
3.1 KiB
Markdown
# 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](../000_TOPOLOGY.md).
|