Permanent engineering governance for the Spanda Autonomous Systems Platform. Every architectural change, platform capability, crate, package, provider, plugin, service, API, SDK, or roadmap proposal must pass Architecture Review before it is accepted.
Related: architecture-review-checklist.md · non-duplication-policy.md · design-review-process.md · platform-architecture.md · design-principles.md · adr/README.md
Spanda has grown from a language and compiler into a full autonomous systems platform — entity model, recovery, distributed decisions, Control Center, SDKs, packages, providers, and solution blueprints. Without deliberate governance, platforms accumulate duplicate capabilities, inconsistent abstractions, and unmaintainable surface area.
Architecture governance exists to:
This is a permanent rule — not a one-time initiative.
Architecture Review applies to:
| Category | Examples |
|---|---|
| Platform architecture | New layers, services, cross-cutting frameworks |
| Roadmap | New pillars, blueprint capabilities, platform expansions |
| Design proposals | RFCs, design docs, spike outcomes |
| ADRs | Significant architectural decisions (docs/adr/) |
| Pull requests | New crates, services, APIs, SDK methods, Control Center features |
| Crates | Workspace members under crates/ |
| Packages | Official and community packages under packages/registry/ |
| Providers | Provider traits and dispatch paths |
| Plugins | Governance, compliance, and extension plugins |
| SDKs | Rust, Python, TypeScript client surfaces |
| Control Center | REST v1, desktop shell, operator workflows |
| APIs | REST, gRPC, CLI JSON contracts |
| CLI | New commands, flags, and output formats |
| Documentation | Architecture diagrams, capability claims, roadmap items |
When in doubt, open an architecture proposal rather than skipping review.
Every proposal must answer the twelve gate questions documented in architecture-review-checklist.md:
Proposals that cannot justify duplication or architecture fit should be rejected or redesigned to extend existing capabilities.
Reviewers score each proposal across dimensions such as problem clarity, architecture fit, entity integration, security, maintainability, testability, documentation, backward compatibility, performance, and complexity.
Overall recommendations:
| Score | Meaning |
|---|---|
| Strongly Recommend | Clear problem, strong fit, low duplication risk — proceed |
| Recommend | Acceptable with documented tradeoffs — proceed with conditions |
| Recommend Later | Valid idea, wrong timing or missing prerequisites — defer |
| Needs Redesign | Duplication or fit issues — extend existing capability instead |
| Reject | Insufficient justification or misaligned with platform vision |
See design-review-process.md for reviewer roles and workflow.
These principles are permanent and override local convenience:
| Principle | Guidance |
|---|---|
| Extend before creating | Prefer extending an existing service, crate, or API over a new subsystem |
| Reuse before duplicating | Search crates, packages, providers, and docs before adding parallel paths |
| Compose before coupling | Wire capabilities through traits, events, and entity metadata — not hard imports |
| Prefer providers over forks | Domain integrations belong in packages implementing provider traits |
| Prefer plugins over core changes | Optional governance/compliance behavior via plugins when possible |
| Prefer packages over platform expansion | Keep the workspace lean; see lean-core.md |
| Prefer Entity integration | Operate on EntityRecord and entity kinds — avoid parallel object models |
| Prefer additive changes | Stable APIs evolve additively; breaking changes require ADR and migration |
| Keep the core small | Language, compiler, runtime, entity infrastructure stay in workspace |
| Keep APIs stable | CLI JSON, REST, gRPC, and SDKs share models — see design-principles.md |
| Every feature must be demonstrable | Example, CLI path, or Control Center view required |
| Every capability must be testable | CI-covered tests planned before merge |
| Every architectural decision must be documented | ADR for significant changes; user docs for visible behavior |
These complement — not replace — design-principles.md and dependency-rules.md.
No architecture proposal may merge unless all of the following are complete:
CI enforcement (layer validation, documentation audit) remains in place; this gate adds human review for intent and duplication.
Every new roadmap item in ROADMAP.md must include:
Items missing these sections should not be accepted into the canonical roadmap until completed. Use the architecture proposal template as a starting point.
Significant architectural changes require an ADR under docs/adr/.
Required when:
Template sections: Problem, Decision, Alternatives, Tradeoffs, Consequences, Compatibility, Migration, Rejected Alternatives.
| Action | Entry point |
|---|---|
| Propose new platform capability | Architecture proposal issue |
| Implement after approval | Pull request — PR template |
| Record a major decision | docs/adr/ |
| Check duplication | non-duplication-policy.md |
| Review a proposal | architecture-review-checklist.md |
See CONTRIBUTING.md for contributor requirements.
Architecture governance extends existing enforcement — it does not replace it:
| Mechanism | Role |
|---|---|
scripts/validate_architecture.py |
Layer classification, dependency waivers (CI) |
| dependency-rules.md | Allowed dependency directions |
| module-ownership.md | Crate and module ownership |
| design-principles.md | Day-to-day decision checklist |
| governance.md | Operational governance framework (runtime) |
| Architecture governance (this doc) | Intent, duplication, and cross-cutting review |
Spanda establishes a permanent architecture governance process that:
The process is part of engineering culture, documentation, roadmap planning, and code review.