novusedge/software-architecture/architecture

Architecture reference

A sourced reference of established architecture and resilience practice. Each reference file holds principles with the same five fields: the claim, why it holds (the mechanism), when it does not apply, sources, and reviewer checks.

Highest-leverage ideas

1. Every remote call gets a timeout, capped retries at one layer, backoff with jitter, and an idempotent receiver. failure.md
2. "Exactly once" is at-least-once delivery plus deduplication at the receiver, keyed on an ID generated once per operation. data-and-events.md
3. Start as one deployable unit with enforced module boundaries; split only for a measured or structural need. start-simple.md
4. Decide reversible things fast and irreversible things slowly, and record the irreversible ones. decisions-and-documentation.md
5. Bound every queue and pool, isolate tenants and workloads, and shed load before latency exceeds client timeouts. overload.md
6. Every stored format and public contract will be read by older and newer code at once; change it in expand, migrate, contract steps. schema-evolution.md
7. Interfaces get depended on beyond what they promise; define "breaking" and test the consumers. boundaries.md, api-versioning.md
8. Latency climbs steeply as utilisation nears 100 percent; keep headroom for the largest failure at peak. queueing-and-capacity.md
9. A few user-facing SLOs and an error budget policy settle the argument between features and reliability. operations.md
10. Treat a model call as a slow, flaky, billed remote service, and its output as untrusted input validated against a schema and business rules. llm-systems.md

Reference map

Open only the files the task needs.

Rules

• Open only the references the task needs, and within them read the principles that apply.
• When a principle shapes a recommendation or decision, cite it by file and principle name, and name the source behind it.
• Source markers: [V] was verified on the cited page on the date given; [U] was not; [I] is the reference author's inference. State a [U] or [I] item as such ("reportedly", "by inference"), never as established fact.
• Quotes marked "(extraction)" passed through a summarising fetch tool. Before quoting any source in a decision record, re-open the URL and confirm the wording.
• Apply "When it does not apply" as seriously as the claim. A principle applied outside its conditions is a mistake, not rigour.
• When explaining a principle to a person, give the mechanism and a concrete example from their system, not the slogan.