coulomb/the-custodian
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4eec96aa028c5f4d6905dfd4e03f30544c32d5ce
the-custodian/canon/standards/orthogonal-architecture_v1.0.md
tegwick 3fa58bccb7 feat(canon): add Orthogonal Architecture Standard v1.0 and schema v1.0.1 
OAS defines a multidimensional architecture model for compute systems:
- 6 canonical dimensions: Stack, Logic, Plane, Quality, Capability, Intelligence
- VSM (Viable System Model) tagging throughout
- Canonical element types and 9 relation types
- Intelligence dimension I1-I5 with governance constraint: I5 agents MUST
  operate through the control plane (P3 — directly governs Custodian design)

Schema provides two-layer validation:
- Layer 1: JSON Schema 2020-12 structural validation
- Layer 2: semantic rule profile R1-R16 (placement, governance, intelligence
  coupling, relation typing rules) + YAML machine-readable rule block
- Draft and production validation profiles

Terminology and dimensions will guide state-hub and Custodian implementation.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-09 23:32:42 +01:00

670 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
OrthogonalArchitecture
*A framework for compute systems design*
# Orthogonal Architecture Standard (OAS)
### Format Specification
**Version:** 1.0
**Status:** Draft Standard
**Scope:** Cloud-native compute systems and Kubernetes platforms
---
# 1. Introduction
*(VSM System 5 — Identity and Policy)*
The Orthogonal Architecture Standard (OAS) defines a **structured format for describing modern compute systems** using a multidimensional architecture model.
The standard establishes:
* a consistent architecture vocabulary
* a canonical set of architectural dimensions
* a modeling format for systems, services, and capabilities
* relationships between architecture components
The goal is to enable **consistent architecture descriptions across teams and organizations**.
The standard is especially suited for:
* Kubernetes-based platforms
* internal developer platforms
* SaaS architectures
* distributed systems
* AI-integrated platforms
---
# 2. Normative Principles
*(VSM System 5 — Identity and Policy)*
The Orthogonal Architecture Standard is based on the following normative principles.
### P1 Separation of Dimensions
Architecture descriptions MUST separate independent perspectives into **orthogonal dimensions**.
### P2 Stable Capability Core
Capabilities represent **stable system intent** and MUST be distinguished from implementation.
### P3 Control Plane Governance
All configuration and operational changes MUST occur through a **control plane**.
Automation and AI MUST NOT bypass governance mechanisms.
### P4 Cross-Cutting Quality Constraints
Quality properties apply across all architecture layers and MUST NOT be modeled as stack layers.
### P5 Explicit Relationships
Architecture elements MUST declare explicit relations with other elements.
---
# 3. Architecture Meta-Model
*(VSM System 3 — Internal Control)*
The meta-model defines the structural components used in architecture descriptions.
---
## 3.1 Architecture
An **Architecture** describes a system through:
* Dimensions
* Levels
* Elements
* Relations
* Quality constraints
---
## 3.2 Dimension
A **Dimension** is a classification axis used to analyze architecture.
Each dimension contains **levels**.
---
## 3.3 Level
A **Level** represents an ordered stratum within a dimension.
Example:
```
Infrastructure → Runtime → Platform Services → Applications
```
---
## 3.4 Element
An **Element** is a concrete architectural component.
Examples:
* Service
* API
* Database
* Workflow engine
* Policy engine
* AI component
---
## 3.5 Relation
A **Relation** describes how two elements interact.
Example relation types:
* realizes
* depends_on
* composes
* governs
* observes
* exposes
---
# 4. Canonical Architecture Dimensions
*(VSM System 1 — Operational Units)*
The Orthogonal Architecture Standard defines **six canonical dimensions**.
| Dimension | Purpose |
| ------------ | ------------------------------------- |
| Stack | technical hosting substrate |
| Logic | functional decomposition |
| Plane | operational responsibility |
| Quality | cross-cutting architecture properties |
| Capability | stable capability modeling |
| Intelligence | degree of intelligent automation |
Each architecture description MUST use these dimensions.
---
# 5. Stack Dimension Specification
*(VSM System 1 — Operations, System 2 — Coordination)*
The Stack dimension describes the **technical substrate of the system**.
---
## S1 Infrastructure Substrate
*(VSM System 1)*
Defines the physical or cloud infrastructure.
Examples:
* cloud accounts
* network foundations
* compute nodes
* node operating systems
* container runtimes
---
## S2 Cluster Runtime
*(VSM System 2 — Coordination)*
Defines the orchestration runtime.
Examples:
* Kubernetes scheduler
* service discovery
* ingress
* admission controllers
* service mesh
* operators
These mechanisms coordinate workload interaction.
---
## S3 Platform Services
*(VSM System 1)*
Shared services supporting workloads.
Examples:
* databases
* message brokers
* caches
* object storage
* secret management
* identity systems
---
## S4 Developer Enablement
*(VSM System 4 — Adaptation)*
Tools that allow system evolution.
Examples:
* CI/CD pipelines
* developer portals
* platform templates
* SDKs
* buildpacks
---
## S5 Workloads and Experience Endpoints
*(VSM System 1)*
Functional applications delivering value.
Examples:
* APIs
* web frontends
* workers
* integration endpoints
* administrative interfaces
---
# 6. Logic Dimension Specification
*(VSM System 1 — Operational Recursion)*
The Logic dimension describes **functional system structure**.
---
## L1 Capability Domain
*(VSM System 5 — Identity)*
Defines stable functional areas.
Examples:
* billing
* identity
* catalog
* order management
Capabilities align with **bounded contexts**.
---
## L2 Service Realization
*(VSM System 1)*
Implementation of capabilities.
Examples:
* APIs
* worker services
* event processors
* adapters
---
## L3 Composition and Integration
*(VSM System 2 — Coordination)*
Defines orchestration between services.
Examples:
* workflow engines
* orchestration pipelines
* API gateways
* integration pipelines
---
## L4 Solution Layer
*(VSM System 1)*
End-user solutions and applications.
Examples:
* SaaS products
* internal systems
* partner solutions
---
# 7. Plane Dimension Specification
*(VSM Systems 2–3)*
The Plane dimension defines **control and governance structure**.
---
## P1 Workload Plane
*(VSM System 1)*
Contains operational services and applications.
---
## P2 Control Plane
*(VSM System 3 — Internal Regulation)*
Maintains system state.
Examples:
* Kubernetes control plane
* GitOps controllers
* policy engines
* platform APIs
---
## P3 Management Plane
*(VSM System 5 — Policy & Governance)*
Provides administrative interfaces.
Examples:
* CLI tools
* web portals
* automation scripts
* audit reporting
---
# 8. Quality Dimension Specification
*(VSM Systems 3 and 3*)*
Defines cross-cutting architectural qualities.
---
## Q1 Security and Compliance
*(VSM System 5)*
Identity, access control, compliance.
---
## Q2 Observability
*(VSM System 3*)*
Telemetry and monitoring.
Examples:
* metrics
* logs
* traces
---
## Q3 Operability and Resilience
*(VSM System 3)*
Deployment, scaling, and disaster recovery.
---
## Q4 Isolation and Tenancy
*(VSM System 2)*
Workload separation strategies.
---
## Q5 Performance and Scalability
*(VSM System 3)*
Latency, throughput, and scaling.
---
## Q6 Cost and Efficiency
*(VSM System 3)*
Resource optimization.
---
## Q7 Governance and Change Management
*(VSM System 5)*
Policies and architecture governance.
---
# 9. Capability Dimension Specification
*(VSM System 5 — Identity)*
Defines capabilities as stable architectural units.
---
## C1 Capability Model
Defines purpose, scope, ownership.
---
## C2 Capability Contract
Defines interfaces:
* APIs
* events
* SLOs
---
## C3 Capability Realization
Technical implementations.
Examples:
* services
* databases
* workflows
---
## C4 Shared Platform Capabilities
Platform-level services.
Examples:
* identity
* messaging
* observability
---
## C5 Business Capabilities
Business functionality.
Examples:
* billing
* onboarding
* support
---
# 10. Intelligence Dimension Specification
*(VSM System 4 — Adaptation and Future Planning)*
Defines AI-assisted system behavior.
---
## I1 Deterministic Automation
Scripts and rule engines.
---
## I2 Language Interaction
Natural language interfaces.
---
## I3 Knowledge and Reasoning
Semantic processing and recommendation systems.
---
## I4 Assisted Adaptation
AI-assisted system configuration.
---
## I5 Agentic Delegation
Autonomous AI agents acting within governance policies.
All AI actions MUST operate through the **control plane**.
---
# 11. Canonical Element Types
*(VSM System 1)*
Standard element classifications:
* Capability
* Service
* Application
* Platform Service
* Data Store
* Control Component
* Management Interface
* Policy
* Automation
* Intelligence Component
---
# 12. Canonical Relation Types
*(VSM System 2)*
Architecture elements MUST use defined relation types.
| Relation | Meaning |
| ------------ | -------------------------- |
| realizes | implements capability |
| depends_on | requires another element |
| composes | combines multiple elements |
| exposes | provides interface |
| governs | enforces policy |
| observes | collects telemetry |
| hosted_on | runtime placement |
| isolated_by | tenancy mechanism |
| augmented_by | enhanced by intelligence |
---
# Appendix A — VSM Perspective on Kubernetes
*(Cybernetic Architecture Interpretation)*
Kubernetes can be interpreted as a **cybernetic control system**.
Mapping Kubernetes components to VSM:
| VSM System | Kubernetes Equivalent |
| ---------- | --------------------------------- |
| System 1 | application pods |
| System 2 | scheduler, networking |
| System 3 | controllers, reconciliation loops |
| System 3* | monitoring and observability |
| System 4 | autoscaling and adaptive systems |
| System 5 | governance and policy frameworks |
---
## Cybernetic Loop
Kubernetes continuously performs:
```
observe → compare → reconcile
```
This implements Beer’s cybernetic control loop.
---
## Viability Principle
The system maintains stability by balancing:
* operational workloads
* coordination mechanisms
* governance policies
* adaptive intelligence
---
## Recursion
Each subsystem can itself be a viable system.
Examples:
* a microservice architecture
* a Kubernetes cluster
* a developer platform
Each level can contain its own:
* operations
* coordination
* governance
* intelligence
---
# Appendix B — Sources and Influences
Orthogonal Architecture integrates ideas from:
* Stafford Beer — Viable System Model
* Viable System Model
* Kubernetes architecture documentation
* cloud architecture frameworks
* platform engineering practices
* capability-centric architecture approaches
Influential work includes:
* *Platform Strategy* — Gregor Hohpe
* Kubernetes architecture documentation
* cloud architecture frameworks (Google Cloud, AWS)
* Domain-Driven Design
---
# Summary
The Orthogonal Architecture Standard provides a **formal modeling specification** integrating:
* platform engineering
* cloud architecture
* capability modeling
* cybernetic governance
* AI integration
Using VSM tagging ensures that architectures remain **viable, adaptive, and governable systems**.
xxx
Reference in New Issue View Git Blame Copy Permalink