architecture-design

architecture-design — Orthogonal Decomposition Architecture Methodology

Core Idea (One Sentence)

Architecture = the orthogonal decomposition of a business system, rather than drawing architecture diagrams. The deliverable = "a core system that is as small and stable as possible + N mutually orthogonal, pluggable peripheral systems" + the interface contracts that compose them. The only fundamental solution to complexity is decomposition, and the criterion is "orthogonality" (changing A does not affect B). This skill turns this methodology into an executable design/review process.

Design Workflow (6 Steps, in Order)

Step	Action	Key Question	Completion Criterion	See Details
1	Separate true requirements from false ones	The three elements of "what kind of person / in what scenario / encountering what problem"; strip down to the essential layer, distinguishing true requirements vs surface-level demands	A one-sentence "root requirement" has been written without any technical solution, and the three elements of person/scenario/problem are all present	`references/mental-models.md` Model 7
2	Identify stable points / change points	Which requirement dimensionswill definitely not change(→ pin into the core), and which will change (→ expose as periphery/interfaces). First judge "what will not happen"	Stable points/change points have been listed as two columns, and each requirement dimension belongs to exactly one column	Model 6
3	Orthogonal decomposition	Split the business into mutually independent sub-businesses; the criterion is "changing A does not affect B", rather than slicing by technical layers	The sub-business list has been pairwise verified for "changing A does not affect B", and remaining coupling has been explicitly marked (not silently ignored)	Model 1
4	Define the minimal core + periphery	Separate outthe minimal business feature setas the core (minimized, stable), and push everything else down into orthogonal periphery/plugins	The core feature set has been finalized and contains no change points, and each peripheral feature has been placed in an independent file	Model 2
5	Design interface contracts	Define an interface for each module (which can be expressed precisely with code/pseudocode). Interface > data structure > architecture diagram. Pass the four criteria: minimal and complete / naturally orthogonal / easy to use / hides implementation	See CHECKPOINT below	`references/interface-design.md`
6	Self-check the modification impact surface	Do a thought experiment: "to add one typical new feature, how many files must be touched and how many lines of core code changed?" Ideal = 0 changes to the core (or ≤1 line) + one new independent peripheral file	The thought experiment has been run and a quantified conclusion has been given (number of core changed lines/files); if it does not meet the standard, roll back to step 2/3 and decompose again	Model 3

🔴 CHECKPOINT (before delivering the design): Step 5 must produceprecise interface definitions + core data structures(write code directly when necessary), do not accept only an architecture diagram. Architecture diagrams are imprecise and ambiguous, and can only serve as auxiliary explanation. Interfaces are the precise carrier of team consensus.

Eight Mental Models (Quick Reference)

#	Model	One sentence
1	Orthogonal decomposition	Architecture means orthogonally decomposing the business into mutually non-coupled modules (changing A does not affect B)
2	Minimal core + orthogonal periphery	Complexity grows by "adding features to the periphery" rather than "changing the core"
3	Quantifying the blast radius of a change	Architecture quality = the number of places/lines that must be changed to add one feature; the more scattered, the worse
4	Interfaces > data structures > architecture diagrams	An interface is an abstraction of the business + a precise carrier of team consensus
5	The open-closed principle copes with change	Software engineering is "the study of change"; rather than changing modules, add new business
6	Anticipate "what will definitely never happen"	The only brake against over-engineering; more important than predicting what will happen
7	The three elements of a requirement	A real requirement = which person / which scenario / which problem
8	Full-stack construction of the information world	From the underlying hardware foundation to the business top layer, the architect "rebuilds the entire system in their mind"

How each model is applied and itsfailure boundariesSee references/mental-models.md。

Judging architecture quality (four criteria + operable tests)

To evaluate whether an architecture proposal is good, pass four criteria: KISS(simple, business semantics unambiguous)/ Modularity(focus on modules rather than frameworks)/ Testable(easy to test = low coupling)/ Orthogonal Decomposition(orthogonal decomposition in place).

The table below is the operable "how to judge / how to measure" tests extracted from the models; check them one by one during review:

Test	Method
Purity of the core system	Damage value `Σ log₂(修改行数+1)`; the more places, the worse, keep each place down to a 1-line change
Module coupling	`Σ log₂(符号出现次数+1) × 不成熟度系数`; Can only compare two proposals with the same functionality
Whether it is over-engineered	"You have made full preparations for something that will not happen" = over-engineering
When to abstract a dependency	Only in the three cases of "multiple choices / removing a heavy dependency / optional components", otherwise depend directly
Whether it is a real requirement	Reduce it to the "root requirement" without any technical assumptions; user feedback often already carries a solution
Whether the requirement should converge	A subclass of requirements diverges and cannot converge → the team must reconsider its response posture
Whether it is a true global feature	Can be handled at a unified entry point / only given an auxiliary function → not a global feature, do not treat it specially
Whether the interface is good enough	Usereal codeto run through all user stories and see whether they work (code is documentation)
Whether to do a local refactor	Judge objectively based on damage value, and already be familiar with that part of the business, not out of subjective dislike
Whether the base library can be depended on	First evaluate the module's "specification maturity"; leave implementation issues to time

⚠️ Damage value / coupling formulasNo physical meaning, not comparable across features, covers only static dependencies(not including runtime call counts), used for relative comparison of two proposals with the same functionality, not an absolute score.

Worked example (applying the 6 steps to a sample)

Requirement: "Give adrawing programa feature".

Three elements of a requirement: user=designer / scenario=drawing vector graphics / problem=efficiently create, edit, and export graphics. The root requirement is "edit graphics", not "support PNG export" (that is the user's own proposed solution).
Stable points / varying points: stable point=graphics document model (add/delete/modify points/lines/shapes) → core; varying points=export formats (PNG/SVG/PDF), Undo/Redo, clipboard → periphery/interfaces. Coordinate system: judge from the standpoint of the "drawing program", not from the standpoint of the "exporter".
Orthogonal decomposition: document model ⟂ rendering ⟂ export ⟂ history (Undo) ⟂ clipboard. Verify orthogonality: adding an export format should not touch the document model.
Core + periphery: core=document model (minimal feature set: graphics CRUD + traversal). Periphery=each exporter, each rendering backend, history, clipboard, all plug-in-ized.
Interface contracts: core exposes DocumentDOM(a read-only interface for traversing graphics). Exporter Exporter.export(doc DocumentDOM, w io.Writer)—parameters use io.Writer rather than *os.File(LKP, which incidentally supports clipboard/in-memory). Use real code to connect and verify the two user stories "export SVG" and "copy to clipboard".
Modification impact self-check: adding "export PDF" = add a peripheral file implementing Exporter , core DocumentDOM 0 changes → damage value 0, design passes.
- Counterexample comparison: if adding PDF requires stuffing if format==pdf into the document model → the core is forced to change, damage value spikes, redo the decomposition.
- Undo/Redo is not solved "at the place where it happens" → sink it down to the data layer (multi-version), which also solves snapshots/async (see §A).

Failure handling (trigger → first line → fallback)

Trigger	First-line fix	Fallback when still failing
Sub-businesses cannot be orthogonal (strongly consistent transactions/shared state are inherently coupled)	Handle cross-cutting concerns with "global features": abstract core interfaces so global featuresreverse dependency(`references/decomposition-and-refactoring.md` §A), rather than stuffing them into the core	Acknowledge that there is irreducible coupling here, explicitly mark it as known technical debt, and do not create false boundaries
Requirement understanding has not converged, interfaces are uncertain	The interface itself is a varying point → defer freezing, first use the thinnest exploratory interface	Mark it as an "exploratory-phase interface, to be solidified once the business converges", and do not lock in the wrong abstraction too early
"What will not change" has a high misjudgment rate in new domains	Conservatively leave openings or defer decisions, do not gamble	Mark high-uncertainty dimensions, respond with iteration/refactoring rather than getting the design right in one shot
The core has aged, changes are constrained everywhere	Enter refactoring rather than continuing to patch; "continuously re-examine boundaries"	Boundaries are not drawn once and forever unchanged; perform orthogonal decomposition again

Applicable boundaries

This method ismost reliable in mature domains with clear constraints. In new domains/rapidly evolving domains (such as early exploratory products), "predicting what will definitely not change" has a high misjudgment rate, so one should conservatively leave openings or defer decisions. The value of the method lies injudgment logic and operable criteria(three elements / four criteria / modification impact scope measurement), not applying fixed conclusions.

Reference set (read as needed)

File	Purpose
`references/mental-models.md`	Detailed explanation of eight mental models (application/failure boundaries + impact scope formula) + decision heuristics
`references/interface-design.md`	Two interface semantics (KISS / minimal dependency) + interface/data structure/architecture diagram priorities + interface anti-patterns
`references/decomposition-and-refactoring.md`	Advanced: global functionality/cross-cutting, architectural paradigms, boundary review, architectural aging and refactoring (six steps), consensus confirmation