- Description
- Dessin d'architecte ancien : élévations, plans d'étage et plan des fondations d'une maison, à l'aquarelle et à l'encre.
- Source
- Wilson, Neave & Berry (State Library of New South Wales) · original page
- Licence
- PD Public domain
Architecture and Design
This theme measures a software system's ability to change at bounded cost: we know where to apply a modification, we know the impact of a change before making it, and the structuring decisions…
In brief
This theme measures a software system's ability to change at bounded cost: we know where to apply a modification, we know the impact of a change before making it, and the structuring decisions are written down, dated, and reviewable. It does not judge the elegance of diagrams, but the cost of the next evolution and the speed of onboarding a newcomer.
Level: 🟢→🔴 · Theme code: ARC (DL matrix)
Why this theme#
An architecture is never “good” in absolute terms: it is either suited or not suited to the pace and nature of change. When it no longer is, every evolution touches ten places, no one dares remove anything, and knowledge of why a choice was made disappears with the person who made it. The cost is invisible at first, then exponential: velocity drops without anyone knowing why. This theme directly feeds technical debt (what we let degrade) and performance (what we can sustain under load).
In a datamart context fed by a field application (SFA), architecture also plays out in data interfaces: a staging schema, a contract view, a fact table all have consumers (reports, exports) that depend on their columns. See the related theme in the data matrix: Data Sources and Data Contracts.
What this theme measures#
- Axis: from “undescribed emerging structure” to “architecture governed by automatically verified constraints.”
- Key indicator: impact radius of a typical change (number of modules/repositories/teams affected by a common functional evolution) and newcomer onboarding time (days before first production release).
- Unit: modules affected per change; days; share of tracked structuring decisions (%).
Five-level table#
| Level | Short name | Promise | Typical indicator (order of magnitude) |
|---|---|---|---|
| 1 | Emerging | The software works, but only its authors know why and where to modify it. | Unknown impact radius; onboarding > 3 months |
| 2 | Described | You can find where a function is and who decided its shape. | High-level diagram updated < 12 months; onboarding ≈ 6 to 8 weeks |
| 3 | Bounded | A common change stays within a single module, and its side effects are known before release. | ≥ 70% of changes in 1 module; onboarding ≈ 3 to 4 weeks |
| 4 | Governed | The architecture defends itself: a violated dependency rule fails delivery, and each major decision is dated and reviewed. | 100% of key rules verified in CI; onboarding ≈ 1 to 2 weeks |
| 5 | Evolvable | An entire component is replaced, without interruption, in a few days, with immediate rollback. | Component replacement without downtime; onboarding < 1 week |
Milestones by level#
| ID | Milestone | Verifiable evidence |
|---|---|---|
| DL-ARC-1.1 | Code is in a single versioned repository per product | Each delivered component has an identified source |
| DL-ARC-1.2 | Main components are named and recognized by the team | Ask three people to name components: consistent lists |
| DL-ARC-1.3 | External dependencies (databases, services, APIs) are known | Existing list, even informal |
| DL-ARC-2.1 | A context and container diagram (C4 levels 1-2 style) exists and is < 12 months old | Date of last diagram update |
| DL-ARC-2.2 | A decisions file (even simple) tracks at least technology choices | At least 5 dated decisions with context |
| DL-ARC-2.3 | Environments and their differences are documented | Page describing dev/test/prod and differences |
| DL-ARC-2.4 | Public interfaces (APIs, views, exchange files) are listed with their known consumers | Contract inventory |
| DL-ARC-3.1 | Modules have explicit boundaries (folders, projects, schemas) and written responsibilities | Review of a recent change: impact limited to 1 module in ≥ 70% of cases |
| DL-ARC-3.2 | Module dependencies are directional (no cycles) | Dependency analysis tool: 0 cycles in the core |
| DL-ARC-3.3 | Structuring decisions go through an ADR (Architecture Decision Record) with rejected alternatives | ≥ 80% of architecture changes have an ADR |
| DL-ARC-3.4 | Interface contracts are versioned and backward compatibility is a rule | Breaking change = major version; consumer registry |
| DL-ARC-3.5 | Non-functional requirements (performance, availability, security) are quantified per component | Component budget table |
| DL-ARC-4.1 | Architecture rules are executable (architecture tests, dependency linter) and block delivery | An intentional violation causes CI to fail |
| DL-ARC-4.2 | ADRs are reviewed at due date (or on trigger) and marked replaced/obsolete | Last review < 12 months for ≥ 90% of active ADRs |
| DL-ARC-4.3 | Architectures are evaluated on quality scenarios (e.g., lightweight ATAM) before major initiatives | Dated report for each initiative > 20 person-days |
| DL-ARC-4.4 | Data schema migrations are compatible with code version N-1 (expand/contract) | Procedure replayed in testing with N and N-1 |
| DL-ARC-5.1 | A critical component is replaced incrementally (progressive strangling / strangler fig) in production, without downtime | History of one completed replacement |
| DL-ARC-5.2 | Architecture constraints are measured continuously (coupling, impact radius, change time) with trend tracking | 6-month dashboard |
| DL-ARC-5.3 | A newcomer releases to production in under a week without one-on-one support | Measurement across the last three arrivals |
| DL-ARC-5.4 | High-irreversibility choices are isolated behind interfaces and tested in “exit rehearsal” | Documented supplier/technology switch exercise |
Detailed reading by level#
🟢 Level 1 — Emerging#
- Observable signs: “ask Marc”; the diagram is in someone's head; the same concept exists under three names; a column change breaks an unlisted report.
- What you gain: initial speed, no formalism. Relevant for a disposable prototype.
- What it does not guarantee: any foreseeable evolution; newcomer onboarding; survival after an expert leaves.
- Difficulty to reach: 1/5 · Effort: 1/5.
🟢 Level 2 — Described#
- Signs: a high-level diagram exists, a “decisions” file too, and an interface inventory. Knowledge is accessible, not yet enforced.
- Gain: you quickly find where things are; onboarding goes from months to weeks.
- Does not guarantee: that code follows the diagram (documentation can lie).
- Difficulty: 2/5 · Effort: 2/5.
🟡 Level 3 — Bounded#
- Signs: clear boundaries (for example, one SQL schema per functional domain, contract views between staging and reporting), directional dependencies, systematic ADRs for structuring choices.
- Gain: the impact radius of a common change shrinks; design reviews have supporting material.
- Does not guarantee: that boundaries hold over time — without automatic verification, they erode.
- Difficulty: 3/5 · Effort: 3/5.
🔴 Level 4 — Governed#
- Signs: executable architecture tests (forbidden dependency, cycles, direct access to internal tables), N-1 database compatibility, reviewed ADRs. CI rejects what violates architectural intent.
- Gain: architecture survives team turnover; deviations are visible the same day.
- Does not guarantee: that the architecture is good — a bad architecture that is perfectly enforced is still bad. Hence scenario-based quality reviews.
- Difficulty: 4/5 · Effort: 4/5.
🔴 Level 5 — Evolvable#
- Signs: an end-to-end component is replaced in production without downtime, through progressive strangling; irreversible decisions are identified and isolated.
- Gain: freedom to switch technology or supplier without a full rewrite.
- Does not guarantee: absence of accidental complexity — each isolation layer has a cost that must be justified (never add abstraction “just in case” without an exit scenario).
- Difficulty: 5/5 · Effort: 5/5.
Partial achievement and rating#
Rate each milestone as 0, 0.5, or 1 according to the common README rule. A few reference points:
- 0.5 on DL-ARC-3.1: boundaries exist for two modules out of five; the rest is one “big block.”
- 0.5 on DL-ARC-4.1: architecture rules are executed, but only as non-blocking warnings.
- A partial 5: one component has already been replaced in production through progressive strangling and ADRs are living artifacts, but onboarding time is still two weeks.
Facade diagram. Symptom: the diagram is flawless, but the code does not follow it. Cause: no automatic verification. Remedy: only score 1 on DL-ARC-3.1 if the evidence (dependency analysis) aligns.
Moving to the next level#
Possible means (optional) — the promise matters, not the method.
- 1 → 2: a half-day workshop to draw context and containers (C4 model); a first decisions file.
- 2 → 3: isolate one domain (for example one SQL schema per domain), establish views as contracts, write ADRs throughout design reviews.
- 3 → 4: dependency analysis tools in CI, architecture tests, two-step migration (expand/contract) for the database.
- 4 → 5: choose one component to replace and do it incrementally; measure impact radius over time.
Run the “typical change test”: take the last five delivered evolutions, count how many modules were touched. That is your indicator, more honest than a diagram.
If “number of ADRs” is rewarded, you get empty ADRs. Measure their review and impact (decisions actually revisited before an initiative), not their count.
SFA datamart: the staging table exposes 80 columns to 14 reports. A rename costs 3 days (level 2). After introducing domain-versioned contract views (level 3), the same rename is handled in a single view in half a day; an N-1 compatibility test (level 4) prevents breaking the previous version of reports.
See also#
- Related themes: 02 Code Quality · 09 Technical Debt and Maintainability · 11 Performance and Scalability · 10 Documentation and Knowledge Transfer.
- Other matrices: BI — Semantic Model · Data — Modeling and Architecture · Project — Scoping and Vision (CAD).
- Practice: Branching Strategies · CI/CD · VCS and SQL/BI data · Project Management Methods Comparison.
- Glossary · Rating: How to Read Scores, Ratings, and Legend.
✻ Written by Claude Sonnet 5.5
