Architecture Change Method

• Status: CANONICAL / BINDING
• Applies to: new packages, public exports, module ownership, cross-module transactions, runtime boundaries, tenant/profile resolution, architecture validators and other difficult-to-reverse structural decisions
• Product authority: ../PRODUCT.md
• Module authority: MODULE_REGISTRY.md
• Filesystem authority: SYSTEM_STRUCTURE_STANDARD.md

1. Why this method exists

More context and a longer implementation plan do not prove that the initial architectural premise is correct. A detailed plan can consistently implement the wrong boundary. Architecture work therefore separates evidence gathering, problem shaping, decision approval, implementation and verification.

The same slice may not create a production boundary and rewrite the governance or fitness function that approves that boundary.

2. Roles

Role	Responsibility	May not do
Evidence mapper	Record current source, runtime, data and caller facts	Select a target design
Shaper	Define the operator problem, appetite and no-go boundary	Implement or approve architecture
Architecture reviewer	Compare options and accept/reject the ADR	Implement the accepted option
Implementer	Deliver the accepted option inside the Task boundary	Change the ADR or architecture gate
Verifier	Try to disprove ownership, value, recovery and complexity claims	Repair the implementation while reviewing it
Release operator	Promote only verified source/runtime states	Infer acceptance from a Git ref

One person or one AI may perform several roles only in separate passes with separate evidence. The architecture reviewer and verifier must not rely on the implementer's conclusion as evidence.

3. Change-control gates

Gate 0 — Truth snapshot

Record before analysis:

master SHA
qa SHA
selected Task scope, authorized paths and evidence
current Product Reality
package/export/dependency graph relevant to the change
local or parallel work that overlaps the candidate paths

A changed base SHA invalidates an uncommitted architecture conclusion until the affected facts are re-read.

The recording location and handoff follow the Task standard.

Gate 1 — Problem shaping

State the problem without naming the solution:

operator or maintainer
current workflow/change pain
source or runtime evidence
observable result
appetite
explicit no-go

“Improve architecture”, “modularize everything”, “complete the platform” and “future-ready” are not valid problem statements.

Gate 2 — Domain discovery

For business boundaries, identify:

commands
events
records and invariants
policies
external effects
failure and recovery
bounded context and semantic owner

A tenant, customer, rollout cohort, menu alias or deployment is not a bounded context.

Gate 3 — Option comparison

At least three serious options are considered:

1. fix the problem without a structural change;
2. extract inside an existing owner/package;
3. create or change a public boundary.

For each option record ownership fit, tenant neutrality, public API delta, production-file delta, dependency delta, migration risk, removal cost, immediate consumer and verification method.

Gate 4 — ADR approval

An architecturally significant change requires an accepted ADR before the implementation slice. The ADR contains context, decision, at least three alternatives, positive and negative consequences, revisit triggers and review evidence.

An implementation slice may consume an accepted ADR, but may not edit that ADR, this method, the module registry, the filesystem standard, architecture validators or admission validators.

Gate 5 — Boundary classification

Every new structural element is classified as one of:

CORE_MODULE             shared business vocabulary/state/command/query owner
STABLE_ADAPTER           approved DB/provider/device boundary implementing a module port
COMPATIBILITY_INTERNAL   temporary Legacy bridge with no new public consumer
PROHIBITED_CUSTOMER_FORK tenant/customer/cohort-specific backend authority

A first validation tenant may prove a shared module. It never names or owns the backend boundary.

Gate 6 — Implementation

Default architecture budgets:

new packages                       0
new public exports                 0
new Product surfaces               0
new tenant-specific backend names  0
new architecture exceptions        0

A non-zero budget requires an accepted ADR and an immediate production consumer. Cleanup and architecture-repair Tasks require net production-file and public-export growth to be zero or less unless the ADR explicitly proves why replacement files are unavoidable.

Gate 7 — Independent verification

The answer, the basis and the necessary action are recorded per question. An unnecessary boundary, a tenant dependency or an unjustified increase in complexity is a signal of a problem, while a test that respects the principle and real recovery evidence is the condition for satisfaction.

Can the new file/export/package be removed while preserving the operator result?
Could the result have been delivered inside an existing semantic owner?
Did a validation tenant leak into a backend name, branch or writer?
Does the test protect a stable principle rather than the new implementation itself?
Did public API, dependency and file complexity increase without measured value?
Does a real authenticated tenant workflow reach authoritative readback and recovery?

Gate 8 — Promotion

After linking the Gate 7 review result to the evidence of the same candidate, the verification, final commit, Git delivery and return procedure of Project Operations is followed. The general work order is owned by Agent Workflow. The verification, final commit, Git delivery and return procedure of Project Operations is followed. The general work order is owned by Agent Workflow. Source, runtime, DB, provider effect, deployment and target-role acceptance remain separate facts.

4. Stable fitness functions

Architecture tests are derived from accepted Product/module principles, not from the implementation currently under development. Stable checks include:

• tenant/customer/cohort names do not create new backend paths, exports or consumers;
• modules do not depend on SQL, React or concrete providers;
• DB adapters do not own business policy;
• dependency cycles and cross-owner writes are rejected;
• an implementation Task cannot modify governance/architecture validators;
• a governance Task cannot modify Product runtime source;
• unused packages, exports, apps, registries and Product surfaces are rejected;
• public and domain identities remain UUID-only;
• evidence language does not claim acceptance above the proven level.

Existing violations are explicit debt exceptions. An exception permits no new caller and must shrink; it is not precedent for another exception.

5. Complexity report

Every structural Task reports before/after values:

production files
public exports
packages/apps
dependency edges
tenant-specific backend symbols
architecture exceptions
orphan/unconsumed source files
largest owner files

A cleanup Task that adds more structural surface than it removes fails unless an accepted ADR records the necessity and removal plan.

6. Methodology sources

This method combines selected practices rather than adopting any framework wholesale:

• Domain-Driven Design and EventStorming for semantic boundaries and business language;
• Architecture Decision Records for explicit options, consequences and supersession;
• C4 for a small, current system/container/module map;
• Evolutionary Architecture fitness functions for stable automated constraints;
• Shape Up for problem shaping, appetite and no-go boundaries;
• SAP Clean Core for core/extension/compatibility classification;
• Team Topologies for a thin platform and reduced delivery cognitive load;
• Odoo/Frappe multi-company/site patterns for separating tenant context from shared modules.

These references inform the method. Repository authority remains the accepted Product, module map, ADRs and executable fitness functions in this repository.

---

Source: new-system/docs/architecture/ARCHITECTURE_CHANGE_METHOD.md — ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged.