generated from coulomb/repo-seed
Bernd Worsch
b5d73aa18b
Some checks failed
Test / test (push) Has been cancelled
Implements IHUB-WP-0009: closes four GAAF-2026 gaps before domain hub work begins. - TypeRegistry helper + controllers/views (hub_kind, hub_capability_manifest) - HubCapabilityManifest entity with validation and registry linkage - ARCHITECTURE-LAYERS.md + CI-enforced boundary contracts - Alembic migration 1743724800, fitness tests (Test/Architecture/) - GAAF spec, Operational Architecture spec, domain hub extension guide - Updates to CLAUDE.md, SCOPE.md, Schema.sql, Routes, FrontController, Types state_hub_sync: pending (tunnel was STALE at completion time; run fix-consistency) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
235 lines
12 KiB
Markdown
235 lines
12 KiB
Markdown
GoodApplicationArchitecture2026
|
||
|
||
*A guideline for building good software systems*
|
||
|
||
**Good Application Architecture Framework 2026 (GAAF-2026)**
|
||
**Standards Document**
|
||
**Version 1.0 – 31 March 2026**
|
||
|
||
### 1. Introduction
|
||
The **Good Application Architecture Framework 2026 (GAAF-2026)** is a system-theoretic standard for designing, reviewing, and continuously improving software repositories, frameworks, and products. It separates different kinds of change into distinct layers so that rigidity protects stability, malleability enables product learning, extensibility supports controlled growth, and bounded variability keeps operational risk under control.
|
||
|
||
**One-line doctrine**
|
||
Freeze the core, evolve the function, bound the customization, constrain the configuration, and govern all change through explicit contracts.
|
||
|
||
GAAF-2026 turns architecture from an implicit art into a repeatable, measurable, enforceable control system. It is deliberately practical: every concept has an associated artifact, checklist, or automated fitness function that both humans and coding agents can apply immediately. It is designed for immediate adoption in any codebase (monorepo, framework, SaaS, open-source library) and scales across entire organizations.
|
||
|
||
### 2. Core Concept
|
||
GAAF-2026 views a software system as a **cybernetic control system** for managing change. It evaluates every architectural decision across five orthogonal dimensions:
|
||
|
||
| Dimension | Purpose |
|
||
|---------------|--------------------------------------|
|
||
| **Layer** | Where the change lives |
|
||
| **Contract** | How the change is constrained |
|
||
| **Lifecycle** | When the change is allowed |
|
||
| **Validation**| How correctness is ensured |
|
||
| **Failure Mode** | What happens when things break |
|
||
|
||
This five-dimensional lens prevents layering from collapsing over time.
|
||
|
||
### 3. Layer Model (Final Form)
|
||
|
||
| Layer | Rigidity | Role | Contract Type | Lifecycle States | Defined Failure Mode | Primary Success Metric |
|
||
|------------------------|--------------|-------------------------------------------|------------------------|-----------------------------------|-----------------------------------------------|--------------------------------------------|
|
||
| **Core** | High (frozen)| Domain-agnostic primitives & invariants | Strong (versioned, immutable after v1) | Distilled only (rare promotion) | Fail-fast, never undefined behaviour | Replaceable only at major version boundaries |
|
||
| **Functional** | Medium | Value-realization modules | Medium (evolvable, versioned) | Experimental → Beta → Stable → Deprecated | Graceful degradation | Demand-driven, independently shippable |
|
||
| **Customization** | Low | Vendor/operator-controlled adaptation | Adaptive (migration-aware) | Versioned & migratable | Isolated per tenant/customer | Zero manual upgrade intervention |
|
||
| **Configuration** | Very Low | User-controlled declarative state | Schema (runtime-validated) | Dynamic but bounded | Reject invalid state BEFORE execution | Zero production incidents from bad config |
|
||
| **Extensions** (aspect)| Cross-cutting| Externally supplied Functional modules | Negotiated (manifest + capability) | Full lifecycle governed | Sandboxed (must not crash host) | Full compatibility matrix coverage |
|
||
|
||
**Dependency rule (strict)**:
|
||
Core ← Functional ← Customization ← Configuration
|
||
Extensions plug into Core or Functional only via contracts.
|
||
|
||
### 4. Contract System (First-Class Artifact)
|
||
Every compliant repository **MUST** contain a top-level folder:
|
||
|
||
```
|
||
/contracts/
|
||
core/
|
||
functional/
|
||
customization/
|
||
config/
|
||
extensions/
|
||
```
|
||
|
||
A **Contract** is a versioned artifact that defines for any public surface:
|
||
- Interface
|
||
- Invariants (what must always hold)
|
||
- Compatibility rules
|
||
- Validation rules
|
||
|
||
Contract types per layer are listed in the table above.
|
||
|
||
### 5. Architectural Laws (Hard Review Criteria)
|
||
1. Change must occur in the highest appropriate layer.
|
||
2. Lower layers define contracts; upper layers consume them (downward dependencies only).
|
||
3. The more rigid the layer, the stronger the interface discipline.
|
||
4. Variability must be explicit (who, what, guarantees, validation, upgrade path).
|
||
5. Customer-specific value must not poison product evolution.
|
||
6. Configuration must never become a second programming language by accident.
|
||
7. Extensions must use seams, not surgery.
|
||
8. **Enforcement Law**: All rules above must be automatically verified by architectural fitness functions in CI.
|
||
|
||
### 6. Evolution Model
|
||
**Promotion path** (rare, bottom-up only)
|
||
Experiment (Functional) → Stable Functional → Core
|
||
|
||
**Extraction path**
|
||
Functional → Extension (external ownership)
|
||
|
||
**Decay path**
|
||
Functional → Deprecated → Removed
|
||
|
||
**Core rule**: Core is never designed top-down; it is distilled from proven Functional patterns that have demonstrated multi-use value.
|
||
|
||
### 7. Failure Model (Per-Layer Semantics)
|
||
Every contract must explicitly document the failure behaviour for its layer (see table in §3).
|
||
|
||
### 8. Validation & Architectural Fitness Functions
|
||
Every repository **MUST** implement automated checks:
|
||
- Import / dependency graph validation (no upward dependencies)
|
||
- Core breaking-change detection
|
||
- Config schema validation before any execution
|
||
- Extension manifest + lifecycle hook presence
|
||
- Layer boundary lint rules
|
||
- Demand-signal / cost-justification check for Functional and Customization changes
|
||
|
||
### 9. Reusable 7-Phase Workplan
|
||
**Phase 0** – Scope & Inventory
|
||
**Phase 1** – Boundary & Contract Extraction
|
||
**Phase 2** – Refactoring by Relocation
|
||
**Phase 3** – Dependency Enforcement & Fitness Functions
|
||
**Phase 4** – Validation Architecture + Failure Testing
|
||
**Phase 5** – Governance & Release Discipline
|
||
**Phase 6** – Scorecard & Continuous Improvement
|
||
|
||
**Required living artifact** in every repository:
|
||
`ARCHITECTURE-LAYERS.md` (see template in §12).
|
||
|
||
### 10. Scorecard
|
||
**Scoring scale** (0–5)
|
||
0 = absent / actively harmful
|
||
1 = weak / ad-hoc
|
||
2 = partial / inconsistent
|
||
3 = adequate / workable
|
||
4 = strong / disciplined
|
||
5 = excellent / exemplary
|
||
|
||
**Default weighting** (long-term systems):
|
||
Core 30 % | Functional 20 % | Customization 15 % | Configuration 10 % | Extensions 10 % | Cross-layer 15 %
|
||
|
||
**Core criteria (C1–C9)**
|
||
C1. Minimality C2. Orthogonality C3. Stability C4. Correctness confidence C5. Performance fitness C6. Scope completeness C7. Domain neutrality C8. Contract clarity C9. Invariant definition
|
||
|
||
**Functional criteria (F1–F8)**
|
||
F1. Module isolation F2. Value efficiency F3. Maturity labeling completeness F4. Reuse of core F5. Coupling discipline F6. Change velocity fitness F7. Third-party readiness F8. Demand-signal discipline
|
||
|
||
**Customization criteria (U1–U8)**
|
||
U1. Boundary clarity U2. Upgrade safety U3. Contract discipline U4. Migration reliability U5. Quality control U6. Tenant isolation U7. Operational predictability U8. Cost justification
|
||
|
||
**Configuration criteria (G1–G7)**
|
||
G1. Schema discipline G2. Validation strength G3. Safety of defaults G4. Role & permission control G5. Auditability G6. Rollback & recovery G7. State-space boundedness
|
||
|
||
**Extensions criteria (E1–E7)**
|
||
E1. Registration quality E2. Contract clarity E3. Isolation guarantees E4. Testability E5. Version compatibility E6. Domain packaging fitness E7. Developer experience
|
||
|
||
**Cross-layer criteria (X1–X8)**
|
||
X1. Layer clarity X2. Dependency rule compliance X3. Change placement X4. Interface governance X5. Architectural test coverage X6. Operational maintainability X7. Long-term evolvability X8. Failure containment & economic alignment
|
||
|
||
**Interpretation**
|
||
≥ 4.5 = Exemplary 3.5–4.4 = Strong 2.5–3.4 = Usable but vulnerable ≤ 2.4 = Needs restructuring
|
||
|
||
### 11. Economic Alignment (Value-Driven Evolution)
|
||
- Functional modules require an explicit **demand signal**.
|
||
- Customization requires **per-instance cost justification**.
|
||
- Core changes require **proven multi-use / reuse benefit** across domains.
|
||
|
||
This ensures architecture directly supports business economics.
|
||
|
||
### 12. Practical Artifacts & Templates
|
||
|
||
#### 12.1 ARCHITECTURE-LAYERS.md Template
|
||
```markdown
|
||
# ARCHITECTURE-LAYERS.md
|
||
**Framework:** GAAF-2026
|
||
**Last reviewed:** YYYY-MM-DD
|
||
**Weighted scorecard:** XX % (see scorecard.xlsx)
|
||
**Repository purpose:** …
|
||
**Layer map:** Core: … | Functional: … | …
|
||
**Decisions log:** …
|
||
**Next review:** YYYY-MM-DD
|
||
```
|
||
|
||
#### 12.2 Standard Review Output Template
|
||
**Repository**
|
||
Name: …
|
||
Purpose: …
|
||
Maturity: …
|
||
Review date: …
|
||
|
||
**Layer map**
|
||
- Core: …
|
||
- Functional: …
|
||
- etc.
|
||
|
||
**Major findings**
|
||
Strengths / Violations / Risks / Fast wins / Strategic refactors
|
||
|
||
**Scores** (per section + weighted total)
|
||
|
||
**Priority actions** (P1–P3)
|
||
|
||
**Migration concerns**
|
||
|
||
**Decision** (Keep / Refine / Refactor / Re-architect)
|
||
|
||
#### 12.3 Good-Signs / Bad-Signs Heuristics (Quick Checklist for Humans & Agents)
|
||
**Good signs**
|
||
- Core is small and boring
|
||
- Modules are easy to add or remove
|
||
- Customer logic lives outside product code
|
||
- Config has strong validation
|
||
- Extension seams are explicit and registered
|
||
- Upgrades require zero heroics
|
||
|
||
**Bad signs**
|
||
- Core changes every month
|
||
- Features bypass core contracts
|
||
- Customers implemented as branches in code
|
||
- Config contains arbitrary expressions
|
||
- Plugins patch internal state
|
||
- Releases need manual per-customer repair
|
||
|
||
#### 12.4 Example Optimization Backlog Categories
|
||
- **Core backlog**: shrink surface, remove domain leakage, formalize invariants
|
||
- **Functional backlog**: split coupled modules, mark maturity, eliminate core duplication
|
||
- **Customization backlog**: replace forks with rules/workflows, add manifest & migration engine
|
||
- **Configuration backlog**: add typed schemas, guardrails, audit log
|
||
- **Extension backlog**: define registration API, lifecycle, compatibility matrix, test kit
|
||
|
||
### 13. Compliance Definition
|
||
A repository is **GAAF-2026 compliant** if and only if it satisfies **all** of the following:
|
||
1. Layers are separated as defined.
|
||
2. Explicit contracts exist in `/contracts/`.
|
||
3. Strict downward dependency direction is enforced.
|
||
4. Lifecycle states are declared and respected.
|
||
5. Upgradeability is guaranteed via bounded customization.
|
||
6. All user-controlled variability is validated.
|
||
7. Extensibility uses registered, contract-based mechanisms.
|
||
8. Failure is contained within defined per-layer boundaries.
|
||
9. Compliance is continuously measured via scorecard and fitness functions.
|
||
|
||
### 14. Adoption & Next Steps
|
||
- **For humans**: Use the workplan every major release or when scorecard < 3.5.
|
||
- **For agents**: Feed this entire document + the `ARCHITECTURE-LAYERS.md` into any coding or review prompt.
|
||
- **Automation**: Implement the fitness functions listed in §8 as the first CI jobs.
|
||
- **Repository starter kit**: Create the `/contracts/` folder and `ARCHITECTURE-LAYERS.md` on day one.
|
||
|
||
This document is the single source of truth for GAAF-2026. It is intentionally self-contained, versioned, and ready for inclusion in every repository, Dev Hub, or organizational standard library.
|
||
|
||
**Approved for use across all systems.**
|
||
**Next scheduled framework review: March 2027.**
|
||
|
||
xxx
|