Core Principles

1. Do One Thing Well (Single Responsibility)

A service must focus on a single, well-defined business capability. Avoid monolithic designs that conflate multiple domains.

2. Do Not Rely on Other Services (Data Independence)

A service must own its data and cannot rely on direct synchronous data access from other services. Data sharing must be asynchronous (via events/webhooks) or through explicit API calls.

3. Idempotency and Determinism

All state-changing operations must be idempotent (safe to retry) and deterministic (same input yields the same result).

4. Standardized Authentication & ACL

All services must use the standardized authentication mechanism (e.g., JWT) and enforce Access Control Lists (ACLs) based on standardized token claims.

5. Data Storage (Isolation Requirement)

A service’s data store must be isolated and not directly accessible by other services. It must be manageable (backup, recovery) independent of the rest of the ecosystem.

6. Webhooks (Event-Driven Communication)

Services must publish relevant state changes and events via standardized webhooks to enable asynchronous communication and prevent tight coupling.

7. Documentation (OpenAPI Spec)

Every service must provide up-to-date, comprehensive documentation, including a machine-readable specification (e.g., OpenAPI/Swagger) for its public API endpoints.

8. Backward Compatibility and Standardized Versioning

Services must guarantee backward compatibility for older clients, and API changes must follow a standardized versioning scheme (e.g., Semantic Versioning).