From Monolith to Spec: Auto-Extracting Business Rules with AWS Transform custom
Turning a sample 160,000 lines of legacy Java into evidence-based, rewrite-ready documentation — without building, running, or touching a single source file.
The problem: nobody fully understands the old code anymore
Every team that owns a large, long-lived application eventually hits the same wall — whether they're rewriting it, splitting it into services, onboarding a new engineer, or just trying to assess what it would take to modernize: nobody fully understands the old code anymore.
The business rules are real — they're enforced in validators, scattered across service methods, encoded in database constraints, and implied by the way entities reference one another. But they were never written down in one place. The original authors have moved on. The "spec" is the code itself. So before you can confidently change anything, you have to do archaeology: read the code and reconstruct what the system actually does and why.
That archaeology is slow, error-prone, and the part everyone wants to skip. AWS Transform's
AWS/business-rules-extraction transformation automates it — and while a rewrite is the obvious payoff, the documentation it produces is useful well before you decide to change a single line (more on that later).What is AWS/business-rules-extraction?
AWS/business-rules-extraction is an AWS-managed transformation that runs inside AWS Transform custom . It performs deep static analysis of a codebase and produces a complete, cross-referenced set of documentation — detailed enough to rewrite a system from, but just as useful to understand or plan one: the domains, the data model, the business rules, the workflows, the cross-cutting concerns, and a machine-readable manifest that downstream tooling can consume.A bit of context on where it sits:
- AWS Transform custom uses agentic AI to perform large-scale modernization — language upgrades, SDK migrations, framework migrations, and analysis. Transformations are defined as skills (a
SKILL.mdplus areferences/folder) and executed consistently across many repositories. (docs ) - AWS-managed transformations are the pre-built, AWS-vetted ones you can run with zero setup. They show up when you run
atx custom def list, and the same catalog backs the CLI, the VS Code plugin, the agent plugin, and Kiro. (catalog ) business-rules-extractionbelongs to the codebase-analysis family of managed transformations — the ones that produce reports and do not modify your code. It's a sibling of things likeAWS/comprehensive-codebase-analysisand the modernization-readiness analyzers.
The defining constraints of this transformation — the rules it never breaks — are worth stating up front, because they're what make the output trustworthy:
Static analysis only. It NEVER builds, compiles, executes, or runs tests.
Read-only. It NEVER modifies your source.
Language-agnostic. Output uses generic vocabulary ("ORM entity", "service component", "controller") so the spec can be rewritten in any language.
Evidence-based. Every claim references a real file, table, or entity. "Absence is evidence" — if there are no tests, jobs, or events, it says so explicitly rather than guessing.
How confident can you be in the result?**** The transformation doesn't just generate documents and call it done — it holds itself to a set of mechanical exit criteria that are run, not eyeballed: the manifest is validated against a JSON schema, every database table must trace to an owning domain, every entity must map to a domain, the dashboard's numbers are reconciled against the markdown, and no stub or empty files are allowed through. A run that can't satisfy these gates is flagged incomplete rather than passed off as finished — so the output you get is internally consistent and grounded in the actual code.
In short: it reads your code the way a careful senior engineer would on their first week, and writes down everything they learned — but exhaustively, and in a few minutes.
What does it actually do?
The transformation runs in two modes that share a single contract (a JSON manifest):
| Mode | What it produces | How often it runs |
|---|---|---|
decomposition (Mode A) | The full business-rules-extraction blueprint for the whole repo — domains, schema, cross-cutting docs, manifest, and an interactive dashboard | Once per repository |
detailed-spec (Mode B) | An exhaustive, language-neutral rewrite spec for one domain — detailed enough to rebuild that domain from scratch without the original source | Once per domain (N runs) |
Mode A writes the manifest; Mode B reads it. This blog focuses on the decomposition mode, because that's the run I performed on OpenMRS and it's the natural starting point.
A decomposition run does the following, in order:
- Discovery — statically scans the full directory tree, counts modules, controllers, entities, and services, and builds a complete service/component inventory.
- Schema extraction — reconstructs the global database schema from ORM annotations, Hibernate mappings, and migrations — preserving column types verbatim (a dropped
IGNORECASEor a roundedDECIMALprecision can silently change behavior, so it doesn't normalize). - Business-logic extraction — for every domain, writes
overview.md,features.md,business-rules.md,workflows.md,validations.md,integrations.md, plus three Mermaid diagrams. - Domain decomposition (DDD) — identifies bounded contexts, recommends microservice boundaries, and assigns every table to exactly one owning domain (or marks it shared-kernel — no orphans).
- Cross-cutting & shared detection — auth, error handling, events, caching, shared entities.
- Coupling & dead-code notes — but only the parts relevant to decomposition decisions.
- Manifest generation — a strict, schema-validated
domain-manifest.jsonthat is the machine-readable handoff to Mode B. - Execution order — a dependency-ordered plan for which domain to extract first.
- Interactive dashboard — a self-contained 5-tab HTML report.
- Guide & master index — the human entry points.
A real run: OpenMRS Core
To show real output, I ran the decomposition mode against OpenMRS Core — the open-source electronic medical record platform. It's a genuinely large, mature Java/Spring/Hibernate monolith, which makes it a good stress test.
Here's what the run found, at a glance:
| Metric | Value |
|---|---|
| Source files | 849 Java files |
| Total LOC | 160,212 |
| Database tables | 118 |
| Domains identified | 17 |
| Shared entities | 5 |
| Foreign keys / indexes reconstructed | 446 FKs / 462 indexes |
…and it produced 204 documentation files organized into a single
business-rules-extraction/ tree. No source file was modified; nothing was built or run.The top-level structure:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
business-rules-extraction/
├── 00-master-index.md ← metrics + domain table (start here)
├── 00-guide.md ← how to use the output, by role
├── database-documentation/ ← 00-global-schema.sql, 00-seed-data.json
├── detailed-domain-bre/ ← one folder per domain (17 of them)
│ └── domain-{slug}/
│ ├── overview.md, features.md, business-rules.md,
│ ├── workflows.md, validations.md, integrations.md
│ └── diagrams/ (sequence, component, workflow — Mermaid)
├── domain-decomposition-overview/ ← bounded contexts, data ownership,
│ ├── domain-manifest.json ← the machine-readable contract
│ ├── execution-order.md ← what to extract first
│ └── service-{slug}.md ← one per domain
├── cross-cutting-documentation/ ← auth, errors, events, caching, shared entities
├── reference-documentation/ ← API catalog, integrations, inventories
├── diagrams/ ← system-wide architecture / sequence / ER
└── analysis-dashboard.html ← the interactive reportSample output
Let me walk through the artifacts that matter most, with the actual content the run generated.
1. The master index — your starting point
The
00-master-index.md gives the whole-system summary and a domain table — the first thing a tech lead reads. For OpenMRS it laid out all 17 domains with their complexity, table count, feature count, and rule count:
Notice that the boundaries aren't arbitrary —
concept (medical terminology) is correctly flagged as the largest/most foundational context with 26 tables, while condition-diagnosis is deliberately merged into a single context because both represent clinical assessments sharing the same service concerns.2. Business rules — the part nobody wrote down
This is the headline artifact. For each domain,
business-rules.md extracts the testable rules implied by the code. Here's the patient domain:
These are the rules a rewrite must preserve — and the ones nearly impossible to recover by reading 160K lines manually. Look at BR-4 in the screenshot: identifier uniqueness flips between global and per-location depending on a type flag (
locationBehavior=REQUIRED). That kind of conditional invariant is exactly what silently breaks in a naive rewrite, and exactly what you want written down before you start.3. Workflows and diagrams
Each domain also gets workflows in prose and three Mermaid diagrams (sequence, component, and workflow). The order domain's workflows, for example, capture the full new-order / revise / discontinue / fulfillment lifecycle. Every domain ships a sequence diagram derived from the actual call flow — here are the patient registration and patient-merge sequences:
Because these are generated from real service/DAO call paths, they reference actual components by name (
PatientService, HibernatePatientDAO, PersonService) rather than generic boxes.4. The reconstructed database schema
database-documentation/00-global-schema.sql is a full DDL reconstruction — 118 CREATE TABLEs rebuilt from Hibernate/Liquibase mappings, with column types preserved exactly:1
2
3
4
5
6
7
8
9
10
11
12
-- OpenMRS Core Global Schema (extracted from liquibase-schema-only-2.9.x.xml)
-- 118 tables, 446 foreign keys, 462 indexes
CREATE TABLE allergy (
allergy_id INT AUTO_INCREMENT NOT NULL PRIMARY KEY,
patient_id INT NOT NULL,
severity_concept_id INT DEFAULT NULL,
coded_allergen INT NOT NULL,
...
uuid CHAR(38),
encounter_id INT DEFAULT NULL
);5. Data ownership & execution order — the decomposition payoff
The whole point of decomposition is answering "if we split this up, who owns what, and what do we build first?" The transformation answers both.
Data ownership assigns every one of the 118 tables to exactly one domain (no orphans):
| Table | Owning Domain |
|---|---|
| patient | patient |
| patient_identifier | patient |
| person | person |
| concept | concept |
| concept_name | concept |
| … | … |
Execution order then turns the dependency graph into a concrete extraction sequence — dependency-free contexts first (
concept, location), then everything that builds on them, grouped into tiers:
6. The machine-readable manifest
domain-manifest.json is the strict, schema-validated contract — 17 domains, 5 shared entities, 3 shared-kernel components, 6 cross-cutting concerns, and the full execution order — all in a form Mode B (or your own tooling) can consume programmatically:1
2
3
4
5
6
7
8
9
10
11
12
13
{
"schema_version": "1.0.0",
"project": {
"name": "OpenMRS Core",
"primary_languages": ["Java"],
"total_source_files": 849,
"total_loc": 160212
},
"execution_order": ["concept", "location", "person", "user-role",
"provider", "patient", "form", "encounter", "visit", "obs",
"order", "cohort", "program", "condition-diagnosis", "hl7",
"notification", "scheduler"]
}7. The interactive dashboard
Finally, everything is rolled into a single self-contained
analysis-dashboard.html — no CDN, no external dependencies, just open it in a browser. It has five tabs.The Overview tab leads with the headline stats and a "What this dashboard tells you" callout that surfaces the key decomposition insights:
The Business Logic tab breaks down features and rules per domain, plus cross-domain features:
The Domain Decomposition tab renders the dependency graph and the recommended extraction order:
The Shared Kernel tab lists the shared entities and the cross-cutting concerns (auth, error handling, events, caching, logging):
…and the Data Ownership tab shows the full table-to-domain map:
It's not only about rewrites
It's tempting to file
business-rules-extraction under "migration tooling," but a rewrite is just one thing you can do with the output. The artifacts answer "what does this system actually do, and how is it structured?" — and that question matters long before, and entirely apart from, any decision to rewrite. A few other ways teams use it:- Onboarding & knowledge transfer. It's the documentation that should have existed but never did. A new engineer — or a team inheriting an orphaned system — gets domain boundaries, business rules, and workflows without spelunking through the source. Valuable even with zero intent to change a line of code.
- Capturing tribal knowledge before it walks out the door. When the people who understood the system are leaving, this pulls what's in their heads into durable, evidence-based docs. It's a hedge against key-person risk.
- Modernization assessment, not just execution. The decomposition overview, coupling hotspots, and execution order let you scope and de-risk a modernization decision — what's coupled, what's foundational, what order to tackle things — before committing to rewrite, re-platform, or leave-as-is.
- Carving one service out of a monolith you're keeping. Not a full rewrite — just a strangler-fig extraction of a single bounded context. The data-ownership map and dependency-ordered plan are exactly what that needs.
- A characterization-test spec. The numbered, testable business rules (BR-4, BR-8, …) are a ready-made checklist for regression tests against the existing system — useful for any refactor or upgrade.
- Audit & domain-expert review. Rules surfaced in plain language let compliance staff and subject-matter experts (clinical SMEs, in the OpenMRS case) check what the code actually enforces against what policy says it should — catching drift between code and intent.
- Grounding for AI coding agents. The machine-readable manifest and language-neutral specs are accurate, structured context to feed code assistants working on the codebase, instead of raw source.
A simple way to frame it: the output supports a spectrum — understand → plan → change — and only the far end is "rewrite."
Why this matters
What used to be weeks of manual code archaeology — and the single biggest source of risk in any modernization — becomes a repeatable, evidence-based artifact you can run in minutes and re-run whenever the code changes. Concretely,
business-rules-extraction gives you:- A shared source of truth the whole team can read, instead of tribal knowledge locked in a few people's heads.
- The actual business rules, extracted from validators and service logic, ready to become test cases — for a rewrite, a refactor, or regression coverage on the system you're keeping.
- A defensible decomposition — every boundary backed by code evidence, every table owned, with a concrete extraction order.
- A machine-readable handoff (
domain-manifest.json) that feeds the per-domaindetailed-specmode or your own tooling.
And because it's a managed transformation, it's vetted by AWS, requires no setup, and continually improves — AWS Transform's continual-learning system captures learnings from each execution as knowledge items that sharpen future runs.
Try it yourself
business-rules-extraction is an AWS-managed transformation, so there's nothing to author — just run it:1
2
3
4
5
6
7
# List available managed transformations (look for AWS/business-rules-extraction)
atx custom def list
# Execute the decomposition on your repo
atx custom def exec \
--transformation-name AWS/business-rules-extraction \
--code-repository-path ./your-monolithYou can tailor it to your organization with the
additionalPlanContext parameter (for example, to select the decomposition vs detailed-spec mode, or to feed in supplementary DDL / OpenAPI specs). See the AWS Transform custom documentation and the managed-transformations catalog to get started. For runnable examples and authoring patterns, the aws-transform-custom-samples repository on GitHub is a great go-to resource.If you're staring down a monolith you're afraid to touch — start by understanding it. Let the agent do the archaeology.
Outputs in this post were generated by running
AWS/business-rules-extraction (decomposition mode) against the open-source OpenMRS Core repository. No source files were modified, and no code was built or executed during analysis.Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article