What is System Design & Architecture Standards?

A set of universal principles and practices to guide the architecture of robust, scalable systems, covering core principles, patterns, distributed concerns, and documentation.

How do you apply SoC and SSOT in practice?

Structure the system so each concern has its own module (SoC) and maintain a single source of truth for data and contracts (SSOT) to reduce duplication and inconsistency.

How to balance CAP vs Availability in distributed systems?

Understand CAP trade-offs and design for the chosen balance, using idempotent operations, circuit breakers for resilience, and eventual consistency where appropriate.

System Design & Architecture Standards

Scanned

npx machina-cli add skill hoangnguyen0403/agent-skills-standard/system-design --openclaw

Files (1)

SKILL.md

1.5 KB

System Design & Architecture Standards

Priority: P0 (FOUNDATIONAL)

Architectural Principles

SoC: Divide into distinct sections per concern.
SSOT: One source, reference elsewhere.
Fail Fast: Fail visibly when errors occur.
Graceful Degradation: Core functional even if secondary fails.

Modularity & Coupling

High Cohesion: Related functionality in one module.
Loose Coupling: Use interfaces for communication.
DI: Inject dependencies, don't hardcode.

Common Patterns

Layered: Presentation → Logic → Data.
Event-Driven: Async communication between decoupled components.
Clean/Hexagonal: Core logic independent of frameworks.
Statelessness: Favor stateless for scaling/testing.

Distributed Systems

CAP: Trade-off Consistency/Availability/Partition tolerance.
Idempotency: Operations repeatable without side effects.
Circuit Breaker: Fail fast on failing services.
Eventual Consistency: Design for async data sync.

Documentation & Evolution

Design Docs: Write specs before major implementations.
Versioning: Version APIs/schemas for backward compatibility.
Extensibility: Use Strategy/Factory for future changes.

Source

git clone https://github.com/hoangnguyen0403/agent-skills-standard/blob/develop/.github/skills/common/system-design/SKILL.md

View on GitHub

Overview

Defines universal architectural standards to build robust, scalable, and maintainable systems. It codifies core principles (SoC, SSOT, fail fast, graceful degradation), promotes modularity with high cohesion and loose coupling, and prescribes common patterns like Layered, Event-Driven, Clean/Hexagonal, and Stateless architectures. It also covers distributed design trade-offs (CAP, idempotency, circuit breakers, eventual consistency) and vital docs and evolution practices (design docs, versioning, extensibility).

How This Skill Works

Practitioners apply the standards by structuring systems around SoC, using SSOT for data consistency, and injecting dependencies to avoid hard-coded couplings. They choose established patterns (Layered, Event-Driven, Clean/Hexagonal) and design for statelessness to improve scalability, with explicit guidance for distributed systems (CAP trade-offs, idempotency, circuit breakers, eventual consistency). Documentation and versioning anchor evolution, ensuring backward compatibility and extensibility.

When to Use It

During system design or major refactoring to ensure modularity and scalability
While defining data contracts and API boundaries to enforce SSOT and loose coupling
When building distributed services and aiming for reliability, scalability, and graceful degradation
During governance activities: documenting designs, versioning APIs/schemas, and planning extensibility
When choosing patterns (Layered, Event-Driven, Clean/Hexagonal) and ensuring statelessness for testing and scalability

Quick Start

Step 1: Define core principles (SoC, SSOT, fail fast, graceful degradation) for the project
Step 2: Choose modular structure and core patterns (Layered/Hexagonal, DI, Statelessness) and map data flows
Step 3: Document design decisions, establish API/versioning rules, and set an extensibility strategy

Best Practices

Adopt SoC and SSOT as foundational discipline to improve clarity and data integrity
Enforce high cohesion within modules and loose coupling between them; use DI to manage dependencies
Favor Layered, Event-Driven, Clean/Hexagonal patterns and maintain statelessness where possible
Understand CAP trade-offs and design with idempotency and circuit breakers for resilience; plan for eventual consistency when appropriate
Document designs before major implementations; version APIs/schemas and design extensibility with strategies like Strategy/Factory

Example Use Cases

Refactoring a monolithic app into layered architecture with DI and a single source of truth for data
Implementing event-driven microservices with asynchronous communication and eventual consistency
Introducing circuit breakers and idempotent operations to protect external service calls
Establishing a backward-compatible API versioning and schema evolution plan
Creating pre-implementation design docs to align teams on architecture decisions

Frequently Asked Questions

Add this skill to your agents