Specification: BFDev Monolithic Git v2¶

TLDR (Solution Summary)¶

• Build bf-dev v2 as the primary BetterFleet authoring repository for multi-service development while keeping existing service repositories in place for downstream delivery during the transition.
• bf-dev repository root + host every repository currently listed in projects.txt as a first-class directory under one Git repository + developers, reviewers, and agents work from one checkout, branch, and worktree.
• Project directory to upstream binding + define one repo-owned mapping from each imported bf-* directory to its upstream repository and branch + sync remains explicit and auditable.
• Subtree synchronization path + let CI push directory-local changes from bf-dev back to the matching downstream repositories automatically on trunk merges + current deployment pipelines and infrastructure ownership remain intact during migration.
• Developer workflow + make clone, pull, branch, commit, and merge-request flows center on bf-dev rather than per-service repositories + downstream repos become an implementation detail for day-to-day authoring and vertical full-stack slices become the default working shape.
• Tooling and docs + update the bootstrap, sync, and review operating model around monolithic Git authoring + contributors understand that this is a repository-topology change, not a runtime monolith decision.

1. Summary¶

• Problem statement:
  • The current bf-dev repo is a development harness that clones multiple bf-* repositories into sibling folders, which forces full-stack work to span several independent Git histories.
  • Cross-service changes require repeated branch, commit, push, and merge-request handling per repository, which adds friction to development, review, and agent-assisted work.
  • The current model also makes multi-project worktrees awkward and discourages small vertical slices across the system.
• Goal and success criteria:
  • Define bf-dev v2 as one authoritative BetterFleet authoring repository for full-stack contribution.
  • Keep current downstream repositories functioning as the deployment, CI, and infrastructure ownership units during the transition.
  • Success is measured by:
  • a full-stack contributor being able to clone one repository and work across the repositories listed in projects.txt without additional per-service Git bootstrap;
  • one branch, one worktree, and one merge request being able to carry a product-oriented vertical slice across multiple service directories;
  • day-to-day contributor authoring no longer requiring manual branch, commit, push, and MR handling in each downstream repository;
  • downstream synchronization preserving the existing repository-level delivery model during migration;
  • repo docs making it explicit that monolithic Git authoring does not imply runtime or service consolidation;
  • the authoring model remaining compatible with a later decision to retire or absorb downstream repositories into bf-dev.
• What will be built in this phase:
  • bf-dev root workspace + import every repository listed in projects.txt as first-class bf-* directories + multi-service authoring happens in one Git tree.
  • Directory binding registry + define exact directory -> upstream repository -> branch mappings in repo-owned config + synchronization has a canonical source of truth.
  • Subtree sync workflow + have CI synchronize imported directory changes back to the matching downstream repositories on merges to trunk, with synced commits referencing the originating merge request ID + existing pipelines remain the release path during transition.
  • Developer operating model + shift clone, pull, branch, commit, worktree, and review guidance to bf-dev while keeping direct bootstrap, pull, and startup commands initially compatible + downstream repos are abstracted away from normal authoring work and full-stack delivery becomes simpler and more incremental.
  • Monolithic Git guardrails + document the distinction between authoring-repo consolidation and runtime/service consolidation + the migration does not silently redefine service architecture.
• Scope (in/out) for this phase:
  • In:
  • repository-topology consolidation for development and review;
  • subtree-backed import and sync of all repositories listed in projects.txt;
  • repo-owned mapping, documentation, and workflow changes needed to support the new authoring model;
  • compatibility with existing downstream CI, deployment, and infrastructure ownership.
  • Out:
  • consolidating BetterFleet services into one deployable runtime system;
  • removing the existing downstream repositories as deployment targets in this phase;
  • detailed implementation design for every bootstrap or CI script;
  • story slicing, rollout sequencing, and team assignment planning.
• Current baseline (as of May 4, 2026):
  • bf-dev currently acts as a harness that clones the repositories listed in projects.txt.
  • Service repositories remain separate Git roots and are gitignored from the bf-dev root repo.
  • ./init and ./pull operate per repository rather than against one source tree.
  • Root docs already describe a subtree sync mechanism, but it currently covers shared assets such as ci-templates and bf-templates, not the main product/service repositories.
• Future evolution guardrails:
  • Even though the first migration cohort is all repositories listed in projects.txt, the migration model should still allow later additions, removals, or explicit exceptions without reshaping the whole workflow.
  • The chosen sync model must not make later retirement of downstream repositories harder once delivery ownership genuinely changes.
  • As long as downstream repositories still exist, they should stay mostly invisible to normal contributor authoring flow rather than reappearing as mandatory per-service Git handling.
  • The authoring model must continue to support trunk-friendly small changes rather than encouraging oversized cross-system drops.

2. Users and Use Cases¶

• Primary personas:
  • Full-stack contributor working across backend, frontend, and integration repos.
  • Reviewer handling a change that spans multiple service boundaries.
  • Platform or release maintainer responsible for keeping downstream repository sync safe.
• High-level user stories:
  • As a full-stack contributor, I want one authoritative bf-dev repository that abstracts away downstream per-service repos while still keeping them synchronized during the transition so I can develop, review, and deliver product-oriented vertical slices with one branch, one worktree, and one merge request.
  • As a reviewer, I want one merge request that shows the whole user-visible change so I can assess the slice end-to-end.
  • As a platform maintainer, I want imported directories to sync back to their original repositories safely so current deployment pipelines can remain in place during migration.
  • As an engineering lead, I want the workflow to stay explicit about authoring-repo consolidation versus runtime consolidation so this change does not create accidental architectural drift.
• Edge cases and failure modes:
  • A change touches only one imported directory and should still flow cleanly through the monolithic authoring model.
  • A sync attempt fails for one downstream repository while other directory mappings remain valid.
  • A future exception may require temporarily deferring one repo because of size, sensitivity, or unresolved ownership rules.
  • A contributor mistakes the Git monolith proposal for a runtime monolith decision and tries to widen scope into service consolidation.

3. Conceptual Model Terms and Decisions¶

Key Terms¶

Decision Ledger¶

4. Domain Model and Eventstorming (Conceptual)¶

• Bounded context and ubiquitous language:
  • Workspace Authoring covers branching, worktrees, commits, and review inside bf-dev.
  • Repository Binding covers imported directories, upstream mappings, and subtree ownership.
  • Downstream Delivery Continuity covers sync back to the original repositories so current pipelines remain usable.
• Aggregates and entities (abstract):
  • Monolithic Workspace: the authoritative bf-dev source tree.
  • Imported Project Directory: one bf-* codebase represented inside the workspace.
  • Directory Binding Record: upstream repository URL, branch, and owned path prefix.
  • Change Set: one developer-authored cross-directory slice.
  • Sync Operation: one attempt to propagate directory changes to a downstream repository.
• Value objects:
  • Directory Prefix, Upstream Repo Ref, Branch Ref, Sync Trigger, Review Slice.
• Domain events and their triggers:
  • ProjectImportedAsDirectory when one upstream repository is introduced into bf-dev.
  • DirectoryBindingDefined when the canonical upstream mapping for a directory is recorded.
  • CrossServiceChangeCommitted when a branch includes changes across one or more imported directories.
  • SubtreeSyncRequested when CI detects changed bound directories after a merge to trunk.
  • UpstreamRepositorySynchronized when the downstream repo receives the subtree push successfully with the originating MR ID referenced in the synced commit.
  • SubtreeSyncFailed when the push cannot be completed safely.
  • CrossServiceReviewOpened when one MR presents the vertical slice for review.
• Commands, actors, and policies:
  • ImportProjectAsDirectory by platform maintainer.
  • DefineDirectoryBinding by platform maintainer or repo owner.
  • CommitVerticalSlice by developer or agent.
  • OpenCrossServiceMergeRequest by developer or agent.
  • RunSubtreeSync by CI on merges to trunk using the approved sync path.
  • InspectSyncFailure by platform maintainer when synchronization fails.
• Invariants and business rules enforced:
  • Each imported project directory maps to exactly one canonical upstream repository and branch at a time.
  • Subtree sync may only push the owned directory prefix for the bound project.
  • One change set may span multiple imported directories.
  • The initial import cohort includes every repository listed in projects.txt unless a later exception is recorded explicitly.
  • The workflow must keep downstream repositories deployable during transition.
  • Each synced downstream commit references the originating bf-dev merge request ID.
  • Docs must distinguish Git authoring consolidation from runtime/service consolidation.
  • Imported directory naming must remain consistent with ADR 0008 unless superseded explicitly.
  • Sync automation must satisfy ADR 0007 safety expectations.
• External systems and integrations:
  • GitLab repositories and merge requests for upstream delivery continuity.
  • BFDev CI for automatic subtree synchronization on trunk merges.
  • Existing downstream CI, deployment, and infrastructure pipelines.

Interaction Flow¶

flowchart LR
  Dev["Developer / Agent"] --> Branch["Create one bf-dev branch or worktree"]
  Branch --> Change["Edit one or more imported bf-* directories"]
  Change --> MR["Open one cross-service merge request"]
  MR --> Merge["Merge approved change into bf-dev trunk"]
  Merge --> Sync["CI runs subtree sync per bound directory"]
  Sync --> Core["Update upstream repository A"]
  Sync --> Web["Update upstream repository B"]
  Sync --> Connect["Update upstream repository C"]
  Core --> Pipelines["Existing downstream pipelines continue"]
  Web --> Pipelines
  Connect --> Pipelines

Event Timeline¶

timeline
  title BFDev Monolithic Git Event Timeline
  ProjectImportedAsDirectory : Source tree lands under bf-dev
  DirectoryBindingDefined : Directory to upstream mapping is recorded
  CrossServiceChangeCommitted : Vertical slice is authored in one branch
  CrossServiceReviewOpened : One MR presents the full slice
  SubtreeSyncRequested : CI triggers downstream sync after trunk merge
  UpstreamRepositorySynchronized : Existing delivery repo receives the change with MR ID traceability

Event Dictionary¶

• ProjectImportedAsDirectory: one former standalone repo becomes a first-class directory in bf-dev | creates the monolithic authoring surface | directory, upstream_repo, branch | enables single-tree development across the full projects.txt cohort.
• DirectoryBindingDefined: the sync mapping for a directory is agreed and stored | makes ownership explicit | directory, upstream_repo, branch, prefix | governs future sync operations.
• CrossServiceChangeCommitted: a developer records one vertical slice in bf-dev | turns multi-repo work into one reviewable change set | branch, directories_changed, commit_range | feeds review and sync.
• SubtreeSyncRequested: CI triggers sync for one or more bound directories after a trunk merge | begins downstream propagation | directories, target_repos, trigger, mr_id | must stay auditable.
• UpstreamRepositorySynchronized: one downstream repo received its update | preserves delivery continuity | target_repo, target_branch, result, mr_id | downstream CI can proceed and the commit stays traceable to the source MR.
• SubtreeSyncFailed: a directory could not be synchronized safely | prevents hidden drift | target_repo, failure_reason | requires operator intervention.

5. Requirements and Constraints¶

• Functional requirements:
  • FR-001: bf-dev shall host every repository listed in projects.txt as a first-class directory inside one authoritative Git repository for the initial migration cohort.
  • FR-002: Each imported directory shall have one repo-owned canonical binding that defines its upstream repository, target branch, and owned directory prefix.
  • FR-003: Contributors shall be able to create one branch or worktree in bf-dev that spans changes across multiple imported directories.
  • FR-004: Contributors shall be able to submit one merge request that represents a vertical slice across multiple imported directories.
  • FR-005: The bootstrap workflow for imported repositories shall no longer require cloning those repositories separately after bf-dev itself is cloned.
  • FR-006: The sync workflow shall propagate changes from an imported directory back to its bound upstream repository without pushing unrelated directories.
  • FR-007: The transition workflow shall preserve the role of the current downstream repositories as CI, deployment, and infrastructure ownership units.
  • FR-008: Subtree sync shall run automatically in CI when eligible changes merge to trunk.
  • FR-009: Repo documentation shall define the developer operating model for clone, pull, worktree, branch, commit, review, and sync under the monolithic Git workflow.
  • FR-010: Repo documentation shall explicitly distinguish monolithic Git authoring from runtime or service-level monolith work.
  • FR-011: The workspace shall keep direct bootstrap, pull, and startup commands initially compatible, with revised semantics documented and deeper revision deferred to later work.
  • FR-012: The repository shall define the initial synchronization registry in a code-native file or files that are reviewed along with the workflow.
  • FR-013: Each downstream synced commit shall reference the originating bf-dev merge request ID.
  • FR-014: No repository listed in projects.txt is explicitly deferred from the first migration cohort in this phase definition.
• Non-functional requirements:
  • NFR-001: The workflow shall align with ADR 0006 by making small trunk-friendly vertical slices easier rather than harder.
  • NFR-002: The sync path shall align with ADR 0007 by being safe to automate, observable, and gated enough to avoid silent destructive propagation.
  • NFR-003: Imported directory naming shall align with ADR 0008 unless a separate naming decision supersedes it.
  • NFR-004: A failed sync for one upstream repository shall not corrupt or obscure the binding state for other imported directories.
  • NFR-005: The migration language shall remain explicit that repository consolidation does not itself change runtime service boundaries.
• Constraints and assumptions:
  • Current downstream repositories remain the deployment path in this phase.
  • git subtree is the baseline synchronization mechanism for this phase, aligned with current BFDev subtree documentation.
  • The first migration cohort is the full set of repositories currently listed in projects.txt.
  • Initial testing indicates the current local orchestration commands remain compatible, even though a later formal revision is expected.
  • Any non-bf-* illustrative names are treated as non-canonical within this repo context.
• Build item coverage mapping:

• Verification notes:
  • Validate the binding model by reviewing the code-native sync registry for exact directory -> repo -> branch mappings.
  • Validate the developer workflow by proving one branch, one worktree, and one MR can cover a multi-directory change.
  • Validate delivery continuity by confirming a synced downstream repository can still run its existing CI or deployment path unchanged.
  • Validate scope clarity by checking docs and implementation notes for explicit separation between Git monolith and runtime monolith concerns.

6. Interaction and Flow¶

• User journey:
  • A contributor clones bf-dev once and gets imported BetterFleet project source as part of that checkout.
  • The contributor creates one branch or worktree and edits one or more bf-* directories for a vertical slice.
  • Review happens through one merge request in bf-dev.
  • After merge to trunk, CI pushes the owned directory changes back to the relevant downstream repositories.
  • Existing downstream pipelines continue to handle build, release, and infrastructure responsibilities during transition.

Flowchart: Authoring And Sync¶

flowchart TD
  A["Clone bf-dev"] --> B["Create branch or worktree"]
  B --> C["Edit one or more imported directories"]
  C --> D["Open one bf-dev MR"]
  D --> E{"Approved and merged?"}
  E -->|No| C
  E -->|Yes| F["CI runs subtree sync"]
  F --> G["Update bound downstream repo(s)"]
  G --> H["Run existing downstream CI / delivery"]

Sequence Diagram: Cross-Service Slice¶

sequenceDiagram
  participant Dev as Developer/Agent
  participant Mono as bf-dev
  participant CI as Sync Workflow
  participant UpA as Upstream Repo A
  participant UpB as Upstream Repo B

  Dev->>Mono: Create branch and edit directories A + B
  Dev->>Mono: Open one merge request
  Mono-->>Dev: Review and merge approved slice
  Mono->>CI: Merge to trunk triggers subtree sync
  CI->>UpA: Push owned prefix for directory A with MR ID reference
  CI->>UpB: Push owned prefix for directory B with MR ID reference
  UpA-->>CI: Accept synced commit
  UpB-->>CI: Accept synced commit

7. Non-Technical Implementation Approach¶

• Approach overview:
  • Start by defining the binding registry for every repository currently listed in projects.txt.
  • Import the projects.txt cohort into bf-dev using the approved subtree-backed approach.
  • Update the root workflow docs and operator scripts so contributors treat bf-dev as the authoring home.
  • Validate the automatic CI sync path on representative directories, then enable it across the full cohort with MR ID traceability.
• Design considerations:
  • Favor a migration that preserves current downstream delivery continuity instead of coupling this initiative to a release-platform rewrite.
  • Keep the sync mechanism reviewable and recoverable before optimizing for complete automation.
  • Keep the repository topology explicit so future retirement of downstream repos remains a conscious later decision.
• Dependencies and prerequisites:
  • Agreement on the code-native binding registry format and ownership.
  • Implementation of CI-triggered subtree sync on merges to trunk.
  • Implementation of MR ID propagation into downstream synced commits.
  • Follow-up ADR work if the team wants the monolithic authoring model itself recorded as a long-lived architectural decision.

8. Open Questions¶

• Should this initiative also create or update an ADR, given the long-lived repository-topology and workflow impact?

9. Appendices¶

• Relevant current baseline docs:
  • docs/reference/platform/ci-and-release.md
  • docs/process/product-engineering-workflow.md
• ADRs reviewed while drafting:
  • 0006 - Trunk-Based Development
  • 0007 - Generalised principle for automation
  • 0008 - Naming Repositories, Services, and URLs
  • 0014 - Service Granularity (contextual distinction between Git monolith and service monolith)