03 Architectural Principles

🏛️ Architectural Principles

All principles organized by domain. Each principle is a paired name that carries its constraint.

_{See also: Algorithm Classes · Glossary}

---

· 🧱 Structural (Apply to all code)

Principle	What it means
SOC + Whole-System	Each module one concern, but reason about the whole system
KISS + Symbolic Compression	Simplest solution via rules/generators, not enumeration
DRY + Structure Sharing	No duplication via maximal sharing and copy-on-write
SRP + Constraint-First	One change reason, derived from invariants not features
OCP + Minimal Interfaces	Extend without modification via few composable primitives
LSP + Confluence	Substitutable components, operation order independent
ISP + Semantic Addressing	Interfaces by usage, reference by meaning not location
DIP + Homoiconicity	Depend on abstractions where code/data/state are interchangeable
Centralized + Symbol Tables	Single truth source via versioned queryable symbols
Hierarchical + Semantic Memory	Layers/trees where placement reflects meaning
Layered + Ordinal Time	Horizontal layers with logical clocks over timestamps
Reflective + Observable Execution	System observes own behavior, traces as queryable data

· ⚡ Computation (Stateless)

Principle	What it means
Immutability + Single Assignment	Data frozen, variables assigned exactly once
Stateless + Semantic Rollback	No persistent state, undo meaning not bytes
Idempotency + Crash-Only	Same result on repeat, quick recovery designed-in
Declarative + Runtime Explanation	Specify what not how, system answers "why" live
Parameterized + Deferred Naming	Behavior via inputs, names assigned when needed
Composable + Fluid Phases	Combine parts, blur compile/runtime boundaries
Traces as Objects	Execution traces queryable, replayable, first-class
Explicit Invalidity	Temporary inconsistency OK if marked
Errors as Language	Errors use system vocabulary, machine-processable

· 📦 Resource (Stateful)

Principle	What it means
Single Owner	Every resource has exactly one deterministic owner
Bounded Lifetime	Resource lifetime is a subset of owner lifetime
Enforced Symmetry	Open/Close, Subscribe/Unsubscribe guaranteed
Reachable ≠ Useful	GC frees unreachable, not unused
Structural Release	If release depends on discipline, it will leak
Teardown Path	Every long-lived component needs init/run/shutdown

· 🔀 Execution (Control flow)

Principle	What it means
DCB/CF + Execution Negotiation	No parent callbacks, execution may counter-propose
Event-driven + Interruptions as Control	Communicate via events, pause/resume is continuation
Scalable + Monotonic Growth	Handle growth via append-only, never retract
Orthogonality + Backtrack by Snapshot	Changes isolated, restore via reinstantiation
Fail Fast + Deterministic Correctness	Detect errors immediately, halt on resource inconsistency

· 🧠 Human Factors

Principle	What it means
Bounded Complexity + Partial Correctness	150 lines / 6 files, stop on uncertainty
Encapsulation + Debug-as-Normal	Hide internals but ship with live inspector
Loose Coupling + Computed Health	Minimize dependencies, diagnose symbolically
Human-in-Loop	Human is part of computation, system explains itself

· 🌱 Evolution

Principle	What it means
Modular + State Over Code	Independent swappable units, protect state first
Extendable + Deliberate Under-Spec	Add features externally, leave room for evolution
YAGNI + Explicit Non-Goals	Do not build unneeded code, document what system does NOT do

---

· ⚖️ Tension Resolutions

Tension	Resolution
Stateless vs State-Before-Mutation	Computation is stateless. Resources get snapshotted before mutation.
Immutability vs State Over Code	Computed data is frozen. Resource state is mutable but managed.
Fail Fast vs Explicit Invalidity	Resource violation halts. Computation uncertainty marks and continues.
YAGNI vs Under-Spec	No code for hypothetical features. No constraints blocking future features.
Single Owner vs Homoiconicity	Ownership applies to runtime resources. Homoiconicity applies to definitions.

---

Source: Architectural principles in the methodology