Official architecture for the Spanda Autonomous Systems Platform — layered structure, dependency governance, ownership boundaries, and validation tooling.
Related: layered-architecture.md · dependency-rules.md · module-ownership.md · design-principles.md
For compiler/runtime pipeline diagrams, see architecture.md. For lean-core extraction history, see lean-core.md.
Spanda has grown from a language and compiler into a complete autonomous systems platform:
Architecture consistency is now as important as adding features. This document establishes the official platform architecture, dependency rules, and ownership boundaries without removing existing functionality or redesigning working components.
Spanda implements a Cognitive & Resilience Architecture —
a functional view of platform responsibilities inspired by proven engineering principles from
biological nervous systems. Eleven functional domains (strategic planning, operational coordination,
reflex & safety, homeostasis, platform immunity, sensory fusion, attention, operational memory,
adaptive learning, damage risk, maintenance) map to existing platform services via the
responsibility matrix. Implementation: spanda-autonomy crate.
Prior naming: bio-inspired-architecture.md (retained, backward compatible).
flowchart TB
subgraph L6 [Solution Blueprints]
BP[Warehouse · SAR · ADAS · Healthcare · …]
end
subgraph L5 [Interfaces]
IF[Control Center · SDKs · REST · gRPC · CLI · VS Code]
end
subgraph L4 [Platform Services]
PS[Readiness · Assurance · Diagnosis · Recovery · Trust · Health · Security · Telemetry · Policy]
end
subgraph L3 [Core Platform]
CP[Entity Model · Device Registry · Capabilities · Hardware · Config · Providers · Packages · Transport]
end
subgraph L2 [Language Runtime]
RT[Scheduler · Triggers · Interpreter · Concurrency · Comm · Safety · HAL]
end
subgraph L1 [Compiler]
CO[Lexer · Parser · AST · Type Checker · SIR · LLVM · WASM]
end
subgraph L0 [Foundation]
FU[Audit · Connectivity types · HTTP deploy · Regex · Serialization · Diagnostics]
end
L6 --> L5 --> L4 --> L3 --> L2 --> L1 --> L0
| Layer | Responsibility | Must not |
|---|---|---|
| Solution Blueprints | Compose existing capabilities for an industry vertical | Introduce new platform features |
| Interfaces | Human and machine entry points (CLI, API, SDK, IDE) | Embed domain logic that belongs in services |
| Platform Services | Reusable operational services (readiness, trust, telemetry, …) | Duplicate entity model or compiler internals |
| Core Platform | Canonical data model, registries, transport, fleet/OTA infrastructure | Implement industry-specific workflows |
| Language Runtime | Execute .sd programs — scheduler, triggers, interpreter, comm |
Own REST APIs or blueprint logic |
| Compiler | Parse, type-check, optimize, codegen | Execute live missions or fleet operations |
| Foundation | Shared primitives with no platform semantics | Depend on compiler or runtime |
The Entity Model (spanda-config) is the single canonical data model. Everything in Spanda
ultimately derives from Entity:
| Specialized entity | Role |
|---|---|
| Robot | Physical or simulated autonomous agent |
| Mission | Operational task with lifecycle and verification |
| Package | Installed Spanda package with provenance |
| Provider | Runtime provider implementation |
| Human | Operator, expert, or team member |
| Device | Hardware node in device tree |
| Fleet | Coordinated group of robots/devices |
| Wearable | Body-worn sensor or display |
| Facility | Building, zone, or site |
No duplicate models (RobotRecord, DeviceRecord, …) should evolve independently. See
entity-model.md.
Each platform service has a single clear responsibility. See platform-services.md.
| Service | Crate(s) | Responsibility |
|---|---|---|
| Readiness | spanda-readiness |
Operational go/no-go |
| Assurance | spanda-assurance |
Deployment evidence |
| Diagnosis | spanda-explain, spanda-runtime-faults, spanda-graph, spanda-diff |
Explain failures and impact |
| Recovery | Runtime + readiness hooks | Plan and execute recovery |
| Trust | spanda-trust |
Confidence and authenticity |
| Health | spanda-readiness (entity health), runtime HAL |
Operational state |
| Security | spanda-security, spanda-tamper, spanda-threat |
Identity, secrets, tamper |
| Telemetry | spanda-telemetry-store |
Metrics, logs, traces, events |
| Policy | spanda-policy |
Operational policy evaluation |
All subsystems publish events on a common schema. See event-model.md.
Examples: EntityCreated, HealthChanged, ReadinessChanged, MissionStarted,
RecoveryTriggered, PackageInstalled, TrustUpdated, TamperDetected.
Events underpin telemetry, replay, Control Center, audit, and notifications.
| Surface | Versioning | Shared models |
|---|---|---|
| CLI | Semver via spanda --version |
Entity/readiness JSON mirrors REST |
| REST | /v1/* path prefix |
EntityRecord, readiness reports |
| gRPC | Proto semver from GET /v1/version (currently 1.0.14, 164 RPCs) |
Parity with REST entity RPCs |
| SDKs | crates.io / npm / PyPI semver | Generated from OpenAPI/proto |
Avoid duplicated DTOs — SDKs, REST, and gRPC share entity and readiness payloads.
Solution blueprints under examples/solutions/ compose platform capabilities. They must not
introduce new platform features. If a blueprint needs a capability, add it to the platform first,
then reference it from the blueprint.
Architecture governance is enforced by scripts/validate_architecture.py in CI Fast
(lint-rust). Tier map: ci-architecture.md.
| Check | Behavior |
|---|---|
| Module classification | Every workspace crate must appear in scripts/architecture-manifest.yaml |
| Layer violations | Upward Rust dependencies fail CI Fast; dependency_waivers is empty (0 baseline) |
| Circular dependencies | Any new strongly connected component in production deps fails CI Fast |
| Duplicate entity types | Warn if forbidden types appear outside spanda-config |
| TypeScript layer imports | Fail on new upward imports; typescript_dependency_waivers is empty (0 baseline) |
| Manifest YAML/JSON sync | Fail when .json is stale |
| Blueprint governance | Fail when blueprints contain forbidden artifacts |
| Public API docs | Covered by scripts/validate_documentation.py |
# Local validation
python3 scripts/validate_architecture.py --verbose
# Regenerate machine-readable manifest after editing YAML
scripts/sync_architecture_manifest.sh
# Generate dependency graph (Graphviz)
python3 scripts/validate_architecture.py --write-graph docs/architecture-dependency-graph.dot
dot -Tsvg docs/architecture-dependency-graph.dot -o docs/architecture-dependency-graph.svg
Dependency graph artifact: architecture-dependency-graph.dot.
The lean-core refactor (Phases 1–17) established workspace crate boundaries documented in crates/README.md. Platform Architecture v2.0 extends that model with:
As of Phase 8 (Platform Architecture v2.1), the production Rust and TypeScript graphs have zero upward dependency waivers and zero SCC waivers. Any new upward edge or circular strongly connected component fails CI Fast unless an architecture review adds a tracked waiver with a ticket ID. See architecture-waiver-burn-down.md for the completed burn-down history.
| Document | Contents |
|---|---|
| layered-architecture.md | Layer definitions, rationale, diagrams |
| dependency-rules.md | Allowed edges, waiver process, anti-patterns |
| module-ownership.md | Full ownership matrix (crates, packages, blueprints) |
| platform-services.md | Service responsibilities and boundaries |
| event-model.md | Common event schema and publishers |
| design-principles.md | Guiding principles for contributors |
| architecture-waiver-burn-down.md | Completed waiver burn-down history (Phases 1–8) |
| cognitive-resilience-architecture.md | Functional responsibility domains |
| functional-domains.md | Eleven domain definitions |
| responsibility-matrix.md | Capability ownership matrix |
| bio-inspired-architecture.md | Prior bio-inspired naming (redirects to cognitive-resilience) |