Domain Decomposition

Domain decomposition is the process of dividing a monolithic system into bounded contexts — self-contained areas with distinct data ownership, vocabulary, and lifecycle. The output feeds directly into ModernizeSpec’s domains.json, which AI agents use to understand where business boundaries fall in the legacy code.

Bounded Context Extraction

A bounded context is a region of the codebase where a particular domain model applies consistently. Inside the boundary, terms have precise meanings. Across boundaries, the same word may mean different things.

Signals of a Natural Boundary

Signal	What to Look For	Tool
Distinct data ownership	Tables/entities not shared with other areas	Entity relationship atlas
Separate vocabulary	Terms used only within one area of the code	Keyword frequency analysis
Independent lifecycle	Code that changes together but independently of other areas	Git co-change analysis
Minimal cross-boundary calls	Few function calls or imports crossing the proposed boundary	Dependency graph
Separate UI sections	Distinct pages, menus, or navigation groups	UI inventory

Extraction Process

1. Identify candidate boundaries using the signals above
2. Score coupling between candidates — low coupling confirms the boundary, high coupling suggests merging or different splitting
3. Validate with domain experts — boundaries should match how the business thinks, not how the code is organized
4. Record in domains.json with entities, capabilities, and coupling scores

Common Mistakes

Splitting by Layer

Separating “all controllers” from “all services” from “all repositories” creates distributed monoliths. Split by business capability, not technical layer.

Too Many Contexts

Every entity does not need its own bounded context. Group related entities that share a lifecycle and consistency boundary.

Ignoring Coupling Data

Drawing boundaries on a whiteboard without measuring actual code coupling produces aspirational architecture, not actionable extraction plans.

Aggregate Detection

An aggregate is a cluster of entities treated as a single unit for data changes. The aggregate root is the entry point — all modifications to the cluster go through it. Aggregates define transaction boundaries in the new system.

How to Find Aggregates

From Database Schema

Look for parent-child table relationships where children cannot exist without the parent:

• Parent table = aggregate root candidate
• Child tables (FK to parent, cascade delete) = aggregate members
• Reference tables (FK but independent lifecycle) = separate aggregate

Example: Invoice (root) owns InvoiceLineItem (member) and TaxDetail (member), but references Customer (separate aggregate).

From Transaction Boundaries

Examine write operations in the codebase. Code that updates multiple entities within a single transaction reveals an aggregate:

begin_transaction()
  update(invoice)
  update(invoice.items)       # Same aggregate
  update(invoice.taxes)       # Same aggregate
  update(gl_entries)          # Different aggregate -- cross-aggregate effect
commit()

The entities modified together inside a transaction are the aggregate. Cross-aggregate effects should eventually become events, not transactions.

From Delete Cascades

Ask: “If I delete entity X, what else must be deleted?” The answer defines the aggregate boundary.

• If deleting a PurchaseOrder must also delete its PurchaseOrderItem rows, they are the same aggregate.
• If deleting a PurchaseOrder should not delete the Supplier, they are separate aggregates.

Aggregate Size Guidelines

Size	Typical	Risk
1-3 entities	Healthy	None
4-7 entities	Acceptable	Monitor for unnecessary coupling
8-15 entities	Large	Consider splitting into sub-aggregates
16+ entities	Too large	Almost certainly hiding multiple concerns

Capability-Driven vs Page-Driven Organization

Legacy systems, especially web applications, are often organized around UI pages or screens. This creates modules that mix multiple business capabilities because a single page may touch invoicing, payments, customer management, and reporting.

The Problem with Page-Driven Organization

┌─────────────────────────────────────────────────┐
│              "Invoice Page" Module                │
│                                                   │
│  ┌───────────┐ ┌───────────┐ ┌────────────────┐ │
│  │ Invoicing │ │ Payments  │ │ Customer Info  │ │
│  │ Logic     │ │ Logic     │ │ Display        │ │
│  └───────────┘ └───────────┘ └────────────────┘ │
│  ┌───────────┐ ┌───────────┐                     │
│  │ Tax Calc  │ │ Reporting │                     │
│  │           │ │ Summary   │                     │
│  └───────────┘ └───────────┘                     │
└─────────────────────────────────────────────────┘

Five capabilities in one module. Extracting “Invoicing” requires untangling it from four other concerns.

Capability-Driven Reorganization

┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│  Invoicing   │ │  Payments    │ │  Taxation    │
│              │ │              │ │              │
│ Create       │ │ Record       │ │ Calculate    │
│ Submit       │ │ Allocate     │ │ Apply rules  │
│ Cancel       │ │ Reconcile    │ │ Report       │
└──────────────┘ └──────────────┘ └──────────────┘
┌──────────────┐ ┌──────────────┐
│  Customers   │ │  Reporting   │
│              │ │              │
│ Profile      │ │ Generate     │
│ Credit limit │ │ Export       │
│ History      │ │ Schedule     │
└──────────────┘ └──────────────┘

Each capability becomes a bounded context with clear data ownership. The “Invoice Page” in the new system assembles data from multiple capabilities at the UI layer.

How to Decompose

1. List every business action the system supports (create invoice, submit payment, apply tax rule)
2. Group actions by data ownership — which entity does each action primarily modify?
3. Name the capability using business language, not technical terms
4. Map existing code to capabilities — a single file may contain code for multiple capabilities
5. Record the mapping in domains.json as contexts[].capabilities[]

Domain Classification

For large codebases, manually classifying every file is impractical. Use automated classification to assign each code artifact to a business domain, then refine manually.

Classification Strategies

Strategy	How It Works	Accuracy	Effort
Namespace/path	Use directory structure as initial classification	Low-Medium	Automated
Keyword matching	Match function/class names to domain glossaries	Medium	Semi-automated
Import clustering	Group files that import each other heavily	Medium-High	Automated
Co-change analysis	Files that change together in git belong together	High	Automated (needs history)
AI-assisted	LLM reads code and assigns domain labels	Medium-High	Semi-automated

Process

1. Start with namespace classification — accounts/*.py likely belongs to the Accounts domain
2. Refine with import clustering — files in accounts/ that import primarily from stock/ may actually belong to the Stock domain
3. Validate with co-change — if accounts/tax_calculator.py always changes alongside selling/invoice.py, they may be the same bounded context
4. Flag cross-domain files — files imported by 3+ domains are candidates for a Shared Kernel or need splitting

ERPNext Example

ERPNext’s 521 doctypes are organized into 21 modules, but module boundaries do not align with domain boundaries:

Module Boundary	Domain Reality
accounts/ contains GL Entry, Tax Rule, Payment Entry	These are 3 distinct domains: General Ledger, Taxation, Payments
stock/ contains Stock Entry, Warehouse, Valuation	Valuation crosses into Accounts (it posts GL entries)
hr/ contains Payroll Entry	Payroll crosses into Accounts (it creates journal entries)
selling/ and buying/ are separate modules	Both use the same transaction controller (accounts_controller.py)

The decomposition revealed 21 modules but approximately 35 distinct bounded contexts when analyzed by actual data ownership and coupling patterns.

Controller Hierarchy Analysis

In framework-heavy systems, controller classes accumulate cross-cutting concerns through inheritance. A single controller file may contain logic for validation, calculation, persistence, authorization, and event handling — all mixed together.

Mapping the Hierarchy

1. Extract the inheritance chain — from the most derived class up to the framework base
2. Classify each method by concern (validation, calculation, persistence, event handling, framework hook)
3. Identify cross-domain methods — methods that should belong to a different bounded context
4. Mark framework methods — methods that exist only because the framework requires them (lifecycle hooks, serialization, etc.)

ERPNext Example

The controller hierarchy for a Sales Invoice spans four levels:

Level	Class	Lines	Methods	Concern
1	Document (Frappe)	~2,000	~80	Framework ORM, permissions, workflow
2	TransactionBase	~600	~25	Shared transaction logic
3	AccountsController	4,412	168	Financial calculations, GL posting, tax
4	SalesInvoice	~1,800	~60	Invoice-specific behavior

Methods in AccountsController (level 3) serve every financial transaction type — Sales Invoice, Purchase Invoice, Payment Entry, Journal Entry. This means extracting “Invoicing” as a bounded context requires untangling shared methods from invoice-specific ones.

What to Extract

Method Category	Extraction Strategy
Domain-specific (e.g., validate_invoice_dates)	Move to the target bounded context directly
Shared calculation (e.g., calculate_taxes_and_totals)	Extract as a shared domain service, referenced by multiple contexts
Framework hook (e.g., on_submit, validate)	Replace with domain events in the new system
Cross-cutting (e.g., update_stock_ledger)	Extract as an integration event between bounded contexts

Feeding the Spec

Domain decomposition produces the core data for domains.json:

Analysis Output	Spec Field	Example
Bounded context list	contexts[]	{ "id": "invoicing", "name": "Invoicing" }
Entity grouping	contexts[].entities[]	["SalesInvoice", "SalesInvoiceItem", "SalesTaxesAndCharges"]
Capability mapping	contexts[].capabilities[]	["create-invoice", "submit-invoice", "cancel-invoice"]
Coupling scores	contexts[].coupling[]	{ "target": "general-ledger", "score": 0.72 }
Cross-domain dependencies	relationships[]	{ "from": "invoicing", "to": "taxation", "type": "depends-on" }

See Also

• domains.json Specification — Schema reference for domain mapping
• Codebase Analysis — Prerequisite: understand the code before decomposing it
• Strangler Fig Pattern — Next step: extract bounded contexts incrementally
• Context Map — Interactive visualization of domain relationships