How Spanda runs Architecture Review from proposal through merge. This process is permanent and applies to RFCs, ADRs, roadmap items, issues, and pull requests.
Parent: architecture-governance.md · Checklist: architecture-review-checklist.md
flowchart LR
A[Proposal] --> B[Duplication search]
B --> C[Architecture Review]
C --> D{Scorecard}
D -->|Strongly Recommend / Recommend| E[Implement]
D -->|Recommend Later| F[Defer to roadmap]
D -->|Needs Redesign| G[Revise proposal]
D -->|Reject| H[Close]
E --> I[PR + checklist]
I --> J[Quality gate]
J --> K[Merge]
G --> B
Architecture Review is mandatory before implementation merge for:
| Change type | Review entry point |
|---|---|
| New workspace crate | Architecture proposal issue + ADR |
| New platform service | Architecture proposal issue + ADR |
| New communication layer | Architecture proposal issue + ADR |
| New or breaking API | Architecture proposal issue + ADR |
| New SDK surface (cross-language) | Architecture proposal issue |
| New Control Center feature | Architecture proposal issue |
| New official package (platform-facing) | Package proposal + duplication section |
| New roadmap pillar or platform item | ROADMAP PR with required sections |
| Large refactor crossing layers | ADR + PR checklist |
Not required (but checklist still encouraged) for:
When uncertain, use the architecture proposal template.
| Role | Responsibility |
|---|---|
| Proposer | Complete checklist, duplication search, demo/test plan |
| Architecture reviewer | Score proposal, enforce non-duplication, recommend outcome |
| Area owner | Module owner per module-ownership.md; approves fit |
| Security reviewer | Required for trust, authority, immunity, or new external surface |
| Maintainer | Final merge authority after quality gate |
For small PRs, the PR reviewer may act as architecture reviewer if they complete the full checklist.
Open a GitHub issue using
architecture-proposal.md
or draft an ADR in docs/adr/ for decisions already agreed offline.
Include all twelve gates from architecture-review-checklist.md.
Proposer completes non-duplication-policy.md search obligations and fills section 3 of the checklist with citations.
Reviewers comment on the issue or ADR with:
Sync review is optional for large or contentious proposals.
| Outcome | Next step |
|---|---|
| Strongly Recommend / Recommend | Implement; link issue/ADR in PR |
| Recommend Later | Add to roadmap with prerequisites; do not implement |
| Needs Redesign | Revise to extend existing capability; re-review |
| Reject | Close with rationale; archive learnings in ADR if useful |
mainUse .github/PULL_REQUEST_TEMPLATE.md. Link architecture issue or ADR. Confirm quality gate items.
All items in architecture-governance.md#quality-gate must be checked. CI must pass (ci-architecture.md).
Significant decisions are recorded under docs/adr/.
docs/adr/NNNN-short-title.mdADRs are the historical record; issues track active discussion.
New items in ROADMAP.md must include the sections listed in architecture-governance.md#roadmap-rule.
Roadmap PRs without these sections should request changes before merge.
Large designs may live in docs/ or a linked gist before an ADR is accepted. RFCs must still pass
the Architecture Review Gate. Accepted RFCs should be summarized or superseded by an ADR.
Naming suggestion: docs/rfcs/ (optional) for in-progress designs; docs/adr/ for accepted
decisions.
Disagreement between proposer and reviewer:
Layer waiver requests follow dependency-rules.md and require architecture review — waivers are not a bypass for duplication policy.
PR reviewers should verify:
validate_architecture.py and relevant CI tiers greenLabel suggestion: architecture-review on issues and PRs requiring governance attention.
| Proposal size | Target review turnaround |
|---|---|
| Small (extend existing API) | 2–3 business days (async) |
| Medium (new service or crate) | 1 week |
| Large (cross-cutting platform) | 2 weeks + ADR |
Proposers should not begin large implementations before Recommend or better.
The process succeeds when: