inter-hub/specs/GoodSoftwareArchitectureFramework_2026.md

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

# 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