Architecture Principles
Ecosystem-wide principles that govern how systems in Azwaan’s AI venture ecosystem are designed and documented. Each principle is grounded in evidence — it was either adopted from a real repository’s documented design or from this portal’s own conventions, cited below. New systems are expected to honour these unless an ADR justifies an exception.
Provenance note: Principles 1–7 were first articulated and proven in the Website Intelligence Lab (
docs/philosophy.md, its ADRs) and are generalised here to the ecosystem. Principles 8–10 come from the portal’s own charter (CLAUDE.md, ADR 0002). Nothing here is asserted beyond what those sources support.
1. Reproducibility & complete provenance
Every significant execution should be reproducible and record everything that shaped it (versions, inputs, config), so any two executions can be diffed to explain why they differ. Source: WIL ADR-0004 “Runs are immutable and fully provenanced”; WIL philosophy §6. Ecosystem application: engines, pipelines, and agents record engine/model/knowledge versions on every run.
2. Definition vs. derivation (separate inputs from outputs)
Authored inputs and machine-generated outputs never share a home. Definitions live apart from
derivations, joined by stable IDs.
Source: WIL philosophy §2 (corpus/ vs runs/).
Ecosystem application: mirrors the portal’s own split — source repos (definition) vs the portal’s digests (derivation).
3. Knowledge is referenced, never owned
External knowledge, skills, and shared resources are integrated by pinned version (immutable refs/hashes), not copied in. Zero duplicated content. Source: WIL ADR-0006; WIL philosophy §4. Ecosystem application: the portal digests link back to source repos rather than duplicating them; the Shared Skills layer is consumed, not forked.
4. Stage is state, not location
A thing’s lifecycle stage is a field, not a folder it moves through. Progression is evidenced by accumulating records, never by relocating files. Source: WIL philosophy §3; CLAUDE.md rule 5. Ecosystem application: repo/venture lifecycle is a registry field; the portal never “moves” a repo to advance it.
5. Composable, opt-in services
Capabilities are composed, not hard-wired. Core systems never depend on optional services; services
add capability additively.
Source: WIL philosophy §5 (services/).
Ecosystem application: the future orchestrator is assembled by composing existing skills; layers add capability without the base depending on them.
6. Measurement / evaluation is first-class
Decisions are evidence-based. When a choice affects quality, comparability wins over convenience — build the instrument to measure it. Source: WIL philosophy (the lab as a “scientific instrument”). Ecosystem application: prefer benchmarks and provenanced comparison over anecdote when evolving engines and products.
7. No speculative abstraction (the four-part test)
A new concept, abstraction, or domain ships only if it: (a) solves a real, present problem, (b) reduces future coupling, © has a clear owner, and (d) is explainable in one paragraph. All four, or it waits. Source: WIL philosophy “test for any new concept”; CLAUDE.md rule 6. Ecosystem application: applies to new portal pages, new skills, and new platform subsystems alike.
8. Honest realization labelling (implemented vs planned vs vision)
Documentation must distinguish what is implemented, what is planned, and what is architectural
vision. Record uncertainty explicitly; never fabricate to fill a gap (Unknown/TBD).
Source: portal ADR 0002; CLAUDE.md rule 8.
9. Layered leverage (capability flows upward)
The ecosystem is layered so that foundational capability is consumed by higher layers. Improve something once at the base and every dependent layer benefits. Source: portal Portfolio Overview; ADR 0002.
10. Phase-gated, reviewable change
Work proceeds in small, independently reviewable phases; each ends with an architecture review and does not continue until reviewed. Source: WIL implementation philosophy; portal phased plan (A–D).
11. Deterministic rules decide; AI explains
Where a decision must be defensible and repeatable, a deterministic rule engine decides and scores; an
LLM may explain the result but never forms the opinion. “Recommendations must not be based on AI
opinion. AI may explain… after the rule-based recommendation has been selected.”
Source: inexisstudios/…/assessment-engine-plan-v2.md §13 (Website Assessment engine).
Ecosystem application: scoring, qualification, and recommendation engines are rule-first; AI is the narrator, plus a human-approval gate before anything external.
12. Capabilities are first-class and repo-independent
A reusable capability is documented independently of the repositories that implement it — with explicit owners, consumers, inputs/outputs, and maturity — so cross-repo reuse and duplication are visible. Source: portal ADR 0004; the Website Assessment capability spans four repos. Ecosystem application: every major capability has a page in the Capability Registry and appears in the Reuse Map.
How to use these principles
- Cite them when writing a digest, ADR, or platform doc (e.g. “per Principle 3, knowledge is referenced”).
- Check against them in review — a change that violates a principle needs an ADR that says why.
- Extend them only via ADR. If a new principle emerges from processing a repository, add it here with its source citation and reference it from the affected pages.