Architecture Principles

​

Overview

​

When to Use

• Phase: Phase 1 - Establish Governance
• Timing: Before requirements or design work begins
• Purpose: Define the “constitution” for architecture decisions

​

Command Usage

/arckit.principles <domain or focus>

​

Examples

# Create principles for financial services
/arckit.principles Create principles for a financial services company

# Add specific principle
/arckit.principles Add API-first principle

# Cloud migration context
/arckit.principles Cloud-first principles for AWS migration

# Update existing principles
/arckit.principles Update security principles with Zero Trust

​

What It Creates

​

Strategic Principles

• Scalability: Systems must support horizontal scaling
• Resilience: Design for failure, implement redundancy
• Interoperability: Use standard interfaces and protocols
• Security by Design: Security embedded from the start, not bolted on
• Cloud-First: Default to cloud services unless constraints exist

​

Data Principles

• Single Source of Truth: One authoritative source per data entity
• Data Quality: Accuracy, completeness, timeliness targets
• Privacy by Design: GDPR/DPA 2018 compliance from day one
• Data Sovereignty: Data residency and cross-border transfer rules

​

Integration Principles

• Loose Coupling: Minimize dependencies between components
• Standard Interfaces: REST APIs, OpenAPI specifications
• Asynchronous Communication: Event-driven patterns for resilience
• API Versioning: Backward compatibility and deprecation policies

​

Quality Attributes

• Performance: Response time targets, throughput requirements
• Availability: Uptime SLAs, MTBF/MTTR targets
• Maintainability: Code standards, documentation requirements
• Observability: Logging, monitoring, alerting standards

​

Development Practices

• Automation: Infrastructure as Code, CI/CD pipelines
• Testing: Automated testing strategies (unit, integration, E2E)
• Code Review: Peer review requirements before merge
• Continuous Improvement: Retrospectives and lessons learned

​

Technology-Agnostic Approach

​

❌ Bad (Technology-Specific)

"All applications MUST use Kubernetes for container orchestration"
"Authentication MUST use Auth0"
"Databases MUST be PostgreSQL or MySQL"
"APIs MUST use REST with JSON payloads"

​

✅ Good (Technology-Agnostic)

"All applications MUST support horizontal scaling to meet demand"
"Authentication MUST use industry-standard protocols with MFA"
"Databases MUST support ACID transactions for financial data"
"APIs MUST use standard protocols with versioning and backward compatibility"

​

Principle Structure

1. Clear Principle Statement: Using MUST/SHOULD/MAY (RFC 2119)
2. Rationale: WHY this principle matters to the organisation
3. Implications: How it affects design decisions and trade-offs
4. Validation Gates: Checklist items to verify compliance
5. Example Scenarios: Good vs bad examples (technology-agnostic)
6. Common Violations: Anti-patterns to avoid

​

Industry-Specific Customization

​

Financial Services

• Transaction integrity and ACID compliance
• Audit trails and regulatory compliance (SOX, PCI-DSS)
• Disaster recovery and business continuity
• Financial data encryption and tokenization

​

Healthcare

• HIPAA compliance and PHI data handling
• Patient consent management
• Clinical safety and data accuracy
• Interoperability with NHS/care systems

​

Retail

• Payment processing security (PCI-DSS)
• Inventory system integration
• Customer data protection (GDPR)
• Peak load handling (Black Friday)

​

Government

• Accessibility (WCAG 2.2 AA, Section 508)
• Public records and FOI compliance
• Security clearances and data classification
• Open standards and data portability

​

Exception Process

1. Request Exception: Document why principle cannot be followed
2. Risk Assessment: Evaluate impact of non-compliance
3. Approval Authority: Define who can grant exceptions
4. Time-Bound: Exceptions expire, require renewal
5. Remediation Plan: Path to full compliance

​

Output File

​

Version Detection

• v1.0: First version (no previous file exists)
• v1.1: Minor update (refreshed content, updated details, corrections)
• v2.0: Major update (new categories, removed categories, fundamentally different guidance)

​

Document Control Fields

• Document ID: ARC-000-PRIN-v1.0
• Version: Detected or 1.0 for new
• Date: Current date (YYYY-MM-DD)
• Classification: OFFICIAL (UK Gov) or PUBLIC
• Status: DRAFT for new documents

​

Dependencies

​

How Principles Are Used

• Requirements: NFRs must align with principles (e.g., scalability principle → NFR-S-001: horizontal scaling)
• Design Reviews: HLD/DLD validated against principles
• Vendor Evaluation: Vendors scored on principle compliance
• Technology Research: /arckit.research uses principles as evaluation criteria
• ADRs: Architecture Decision Records reference principles as justification

​

Quality Checks

• All principles are technology-agnostic
• Each principle has MUST/SHOULD/MAY statement
• Rationale explains business value
• Implications show design trade-offs
• Validation gates are objective and measurable
• Examples show good vs bad patterns
• Exception process is documented

​

Next Steps

1. Review with Architecture Board and CTO
2. Get executive approval
3. Publish to architecture repository
4. Run /arckit.stakeholders to analyze stakeholder drivers
5. Use principles in /arckit.requirements for NFR alignment

​

Related Commands

​

Example Outputs