Skip to content

docs: [#285] add Docker Compose topology refactoring plan#286

Merged
josecelano merged 1 commit into
mainfrom
285-docker-compose-topology-refactoring-plan
Jan 23, 2026
Merged

docs: [#285] add Docker Compose topology refactoring plan#286
josecelano merged 1 commit into
mainfrom
285-docker-compose-topology-refactoring-plan

Conversation

@josecelano

Copy link
Copy Markdown
Member

Summary

This PR adds a comprehensive refactoring plan for moving Docker Compose topology logic from Tera templates to the Rust domain layer.

Closes #285

Changes

New Files

  • docs/refactors/plans/docker-compose-topology-domain-model.md - Main refactoring plan (~1500 lines)
  • docs/issues/285-docker-compose-topology-refactoring-plan.md - Issue specification

Modified Files

  • docs/refactors/active-refactorings.md - Registered this refactoring as active

Plan Highlights

Domain Rules Analysis

  • ~47 domain rules identified across 6 categories:
    • Network rules (NET-01 to NET-15)
    • Service dependency rules (DEP-01 to DEP-03)
    • Port exposure rules (PORT-01 to PORT-11)
    • Volume rules (VOL-01 to VOL-07)
    • Service inclusion rules (SVC-01 to SVC-05)
    • Aggregate invariants (INV-01 to INV-05)

3-Phase Implementation

  1. Phase 0: Convert named volumes to bind mounts with BindMount domain type
  2. Phase 1: Create Network enum for type-safe network management
  3. Phase 2: Create DockerComposeTopology aggregate

Implementation Strategy

5 separate PRs planned:

PR Scope
PR 1 ADR: Bind Mount Standardization
PR 2 BUG-01: Remove invalid template branch
PR 3 Phase 0: Bind mount foundation
PR 4 Phase 1: Network domain types
PR 5 Phase 2: Topology aggregate

Issues Discovered

  • BUG-01: Template handles invalid "Grafana without Prometheus" case
  • ISSUE-01: ADR grafana-integration-pattern.md recommends named volumes (will be superseded)
  • ISSUE-03: ADR says Grafana has no healthcheck but template now has one

Checklist

  • Pre-commit checks pass: ./scripts/pre-commit.sh
  • Plan document is complete with all phases defined
  • Domain rules are documented with test specifications
  • Implementation strategy (PRs) is clear
  • Bugs and inconsistencies discovered are documented
  • Plan follows refactoring documentation conventions
  • Plan is registered in active-refactorings.md
  • All markdown linting passes

Notes

  • This is a documentation-only PR for reviewing the plan
  • The actual implementation will be tracked by a separate Epic issue after this plan is merged
  • Once merged, the Epic issue will reference this plan as the source of truth

This commit adds a comprehensive refactoring plan for moving Docker Compose
topology logic from Tera templates to the Rust domain layer.

Key contents:
- Domain rules analysis (~47 rules with test specifications)
- 3-phase implementation plan (bind mounts, networks, topology aggregate)
- 5-PR implementation strategy
- Bug discovered: template handles invalid Grafana without Prometheus case
- Issue spec document for plan review

Related: #285
@josecelano josecelano self-assigned this Jan 23, 2026
@josecelano josecelano requested a review from da2ce7 January 23, 2026 11:00
@josecelano

Copy link
Copy Markdown
Member Author

ACK 858a564

@josecelano josecelano merged commit 60190e0 into main Jan 23, 2026
34 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Review: Docker Compose Topology Domain Model Refactoring Plan

1 participant