Skip to main content

Split Monolith

Use this when a monolith is still primary but you are extracting one capability at a time.

Baseline migration shape​

{
  "services": {
    "db": {
      "cmd": ["postgres", "-D", "./var/db"],
      "port": 5432,
      "ready": {"type": "tcp"}
    },
    "monolith": {
      "cmd": ["go", "run", "./cmd/monolith"],
      "dependsOn": ["db"],
      "port": 8080,
      "ready": {
        "type": "http",
        "url": "http://127.0.0.1:8080/health"
      }
    },
    "billing-api": {
      "cmd": ["go", "run", "./cmd/billing-api"],
      "dependsOn": ["db"],
      "port": 8081,
      "ready": {
        "type": "http",
        "url": "http://127.0.0.1:8081/health"
      }
    }
  }
}

Why it works​

  • legacy and extracted services run together under one orchestration plan
  • both paths stay observable in one runtime session
  • dependency mistakes are visible early through startup waves

Migration checklist​

  1. Extract one bounded capability.
  2. Give it independent readiness.
  3. Keep dependencies minimal and explicit.
  4. Move one consumer path at a time.
  5. Remove monolith edges only after traffic is migrated.

Anti-pattern to avoid​

Do not keep adding every new concern to one giant stack forever. See Giant Single Stack.