Skip to content

ADR-0001: Adopt Microservices Based on Business Capabilities

Status: Accepted Date: 2026-09-04 Decision Owners: Zelvoryqa Architecture Technical Area: System Architecture Related ADRs: ADR-0002: Adopt Multi-Tenant SaaS Architecture

Context

Zelvoryqa is intended to provide an intelligent, cloud-native, multi-tenant SaaS operations platform for inventory, warehousing, logistics, purchasing, fulfillment, delivery, and operational intelligence.

The platform contains several distinct business capabilities with different responsibilities, workflows, data requirements, scaling characteristics, and operational concerns.

Zelvoryqa must also support multiple independent organizations using the platform while maintaining clear logical isolation of organization-owned users, data, configuration, permissions, events, analytics, and operational activity.

The Zelvoryqa goals establish the following architectural requirements:

  • Clear business capability boundaries
  • Multi-tenant SaaS operation
  • Tenant isolation
  • Independent recovery
  • Event-driven operations
  • Explicit data ownership
  • Organization-aware authorization
  • Operational visibility
  • Independent scalability
  • Resilience and failure isolation
  • API-first integration
  • Portability
  • Automated software delivery

The architecture therefore needs to establish a service model that allows business capabilities to evolve and operate independently while avoiding unnecessary coupling.

That service model must also support organization-aware processing without allowing tenant concerns to collapse service boundaries or create shared data ownership.

The primary architectural options considered are:

  1. A traditional monolithic application
  2. A modular monolith
  3. A microservices architecture organized around business capabilities

Decision

Zelvoryqa will use a microservices architecture organized around business capabilities.

Each significant business capability will be implemented as an independently deployable service with responsibility for its own:

  • Business logic
  • APIs
  • Operational data
  • Events
  • Tests
  • Deployment
  • Operational telemetry

Initial business services include:

  • Customer Service
  • Inventory Service
  • Warehouse Service
  • Purchasing Service
  • Order Service
  • Fulfillment Service
  • Shipping Service
  • Notification Service
  • Operations Intelligence Service

Service boundaries will be established around meaningful business responsibilities rather than technical layers.

A service may communicate with other services through explicit synchronous APIs or asynchronous events, depending on the requirements of the interaction.

Services must not share internal implementation details or directly access another service's persistence.

The architecture will favor independent deployment, scaling, monitoring, and recovery of services.

Organization Context Is Part of the Service Boundary

Services that operate on organization-owned resources must be organization-aware.

Organization context must be preserved where required across:

  • External API requests
  • Service-to-service communication
  • Business events
  • Background processing
  • Data access
  • Audit records
  • Operational telemetry

A service must not treat the absence of organization context as implicit permission to access organization-owned resources.

Services are responsible for enforcing authorization and tenant isolation within their own business boundary.

An API gateway, identity provider, or upstream service may participate in establishing organization context, but downstream services must not blindly rely on upstream components as the sole enforcement mechanism.

The detailed organization model, membership model, tenant-isolation strategy, and context-propagation mechanisms are defined separately through the multi-tenancy architecture decision.

Rationale

Business Capability Alignment

Zelvoryqa represents multiple distinct operational capabilities.

Organizing services around those capabilities creates boundaries that correspond to the business domain rather than arbitrary technical decomposition.

For example, inventory management and order management have different business responsibilities even though both may require persistent data and APIs.

Multi-tenancy does not change those business boundaries.

The Inventory Service remains responsible for inventory behavior across organizations, while organization context determines which organization's inventory is being accessed.

Independent Deployment

A business capability should be capable of changing without requiring the entire platform to be deployed as a single unit.

This supports smaller and more controlled releases.

Organization-specific behavior should generally be implemented through configuration, authorization, or organization-owned data rather than requiring separate application builds or deployments for each organization.

Independent Scaling

Different capabilities may experience different workloads.

For example, order processing may require substantially different scaling characteristics from notification processing or analytical workloads.

A microservices architecture allows those workloads to scale independently.

The architecture also provides a foundation for addressing organizations with significantly different workload patterns without requiring the entire platform to scale uniformly.

Fault Isolation

A failure in one capability should not automatically require the entire platform to fail.

Separating services provides a foundation for isolation, graceful degradation, and independent recovery.

Failure handling must preserve organization context and tenant isolation.

Where practical, workload or configuration failures associated with one organization should not unnecessarily affect other organizations.

Explicit Ownership

Business capability boundaries provide a natural foundation for explicit ownership of data, APIs, events, and operational responsibilities.

Zelvoryqa distinguishes between two forms of ownership:

  • Service ownership identifies which service is authoritative for a type of business data.
  • Organization ownership identifies which organization owns a particular business resource.

For example, the Inventory Service owns inventory operational data as a business capability, while individual inventory records belong to specific organizations.

Event-Driven Integration

Microservice boundaries support asynchronous integration through business events.

A service publishes events representing changes within the business capability it owns.

Other services independently consume only the events relevant to their responsibilities.

A service may therefore act as both an event producer and an event consumer.

Organization-scoped events must contain sufficient organization context for consumers to process them within the correct tenant boundary.

The detailed event architecture is defined separately.

Operations Intelligence

Operations Intelligence has fundamentally different workload characteristics from transactional business services.

Separating it as an independent service allows analytics, forecasting, recommendations, and future AI capabilities to evolve without placing analytical responsibilities inside transactional services.

Operations Intelligence must remain organization-aware so that organization-specific analytics and insights remain within the appropriate tenant boundary.

Alternatives Considered

Alternative 1: Monolithic Architecture

A single application would contain all Zelvoryqa business capabilities.

Advantages

  • Simple initial deployment
  • Simple local development
  • Straightforward in-process communication
  • Lower initial operational overhead
  • Easier transactional coordination

Disadvantages

  • Business boundaries can become difficult to enforce
  • Changes to one capability require deploying the entire application
  • Scaling occurs at the application level
  • Failures have greater potential blast radius
  • Data ownership becomes harder to enforce
  • Analytics and transactional workloads can become tightly coupled
  • Tenant-aware authorization and data boundaries may become more difficult to enforce consistently as the application grows

Reason Not Selected

A monolithic architecture does not align well with Zelvoryqa's goals around independent deployment, scaling, recovery, explicit service boundaries, distributed-system engineering, and long-term SaaS scalability.

Alternative 2: Modular Monolith

A single deployable application would contain strongly separated internal modules representing business capabilities.

Advantages

  • Stronger boundaries than a traditional monolith
  • Lower operational complexity than microservices
  • In-process communication
  • Easier transactional workflows
  • Simpler deployment

Disadvantages

  • Modules still share a deployment lifecycle
  • Independent scaling is not possible
  • Failure isolation is limited
  • Service boundaries are architectural rather than operational
  • Distributed-system behavior is not exercised by the architecture itself
  • Tenant-specific workload isolation is more difficult to introduce independently by capability

Reason Not Selected

A modular monolith would provide useful domain separation, but it would not demonstrate or provide the independent deployment, scaling, recovery, service-level operational characteristics, and distributed-system behavior that are central to Zelvoryqa.

Alternative 3: Microservices Based on Business Capabilities

Each major business capability is represented by an independently deployable service.

Advantages

  • Clear business boundaries
  • Independent deployment
  • Independent scaling
  • Improved fault isolation
  • Explicit service data ownership
  • Independent service lifecycle
  • Supports asynchronous event-driven integration
  • Supports organization-aware processing within explicit service boundaries
  • Enables workload-specific technology decisions when justified
  • Provides a foundation for tenant-specific workload isolation when required

Disadvantages

  • Increased operational complexity
  • Network communication introduces failure modes
  • Distributed transactions become more difficult
  • Testing becomes more complex
  • Observability becomes more important
  • Service coordination introduces additional engineering overhead
  • Organization context must be propagated and validated consistently across distributed boundaries

Reason Selected

This approach best aligns with the stated architectural goals and the purpose of Zelvoryqa as a production-oriented, multi-tenant distributed platform.

Consequences

Positive

  • Business capabilities have explicit architectural boundaries.
  • Services can be deployed independently.
  • Services can scale according to workload.
  • Service failures can be isolated more effectively.
  • Service data ownership can be enforced at service boundaries.
  • Organization ownership can be preserved within service-owned data.
  • Event-driven integration becomes a natural architectural pattern.
  • Organization context can be enforced consistently across service boundaries.
  • Operations Intelligence can evolve independently from transactional workloads.
  • The architecture provides a foundation for future organizational, operational, and tenant-specific scaling.

Negative

  • Zelvoryqa will have greater operational complexity than a monolith.
  • Network communication introduces latency and failure modes.
  • Debugging requests across services requires distributed tracing and correlation.
  • Data consistency across service boundaries requires deliberate design.
  • Integration and end-to-end testing become more important.
  • Running the full system locally requires multiple infrastructure dependencies.
  • Organization context must be correctly propagated through synchronous and asynchronous workflows.
  • Authorization and tenant isolation must be tested across multiple distributed boundaries.

Risks

  • Poorly defined boundaries could create a distributed monolith.
  • Excessive synchronous communication could create tight runtime coupling.
  • Excessive service decomposition could increase complexity without meaningful benefit.
  • Shared databases could undermine service ownership.
  • Inconsistent contracts could make services difficult to evolve independently.
  • Inconsistent organization-context handling could result in cross-tenant data exposure.
  • Services could incorrectly assume that upstream authentication or gateway validation is sufficient for organization-level authorization.
  • Background jobs, retries, or event replay could lose organization context if tenant awareness is not treated as part of the service boundary.

Implementation Considerations

Services should be decomposed according to business capabilities rather than technical concerns.

Each service should have a clearly defined:

  • Responsibility
  • API contract
  • Event contract
  • Operational data ownership boundary
  • Organization-context requirements
  • Authorization boundary
  • Deployment boundary
  • Operational responsibility

Services should prefer asynchronous integration when direct synchronous coupling is not required.

Synchronous communication should be used when an immediate response is necessary.

Organization context should be treated as part of the execution context for organization-scoped operations.

Service implementations should establish consistent patterns for:

  • Resolving organization context
  • Validating organization membership and authorization
  • Accessing organization-owned data
  • Propagating organization context through synchronous calls
  • Including organization context in business events
  • Preserving organization context in background processing
  • Auditing organization-scoped operations
  • Testing tenant isolation

The exact mechanisms used to implement these patterns are outside the scope of this ADR.

Service boundaries should remain subject to reevaluation as domain understanding develops.

Changes to significant service boundaries should be documented through additional ADRs.

Operational Considerations

The microservices architecture requires platform capabilities for:

  • Service discovery
  • Health checking
  • Centralized observability
  • Distributed tracing
  • Centralized or aggregated logging
  • Metrics collection
  • Configuration management
  • Secrets management
  • Automated deployment
  • Failure detection
  • Recovery
  • Capacity management
  • Organization-aware operational investigation
  • Tenant-isolation validation

Each service should expose sufficient telemetry to determine its health and behavior independently.

Logs and traces should preserve organization context where appropriate to support tenant-specific operational investigation.

Organization identifiers should not automatically be attached as dimensions to all metrics because uncontrolled tenant-level metric dimensions can create high-cardinality operational data.

Operational tooling must avoid exposing one organization's sensitive information while investigating another organization's activity.

Validation

The decision will be validated through implementation of the initial Zelvoryqa services and representative business workflows.

Validation should demonstrate:

  • Services can be built independently.
  • Services can be tested independently.
  • Services can be deployed independently.
  • Individual services can be scaled independently.
  • A service failure does not necessarily require complete platform failure.
  • Services can communicate through explicit APIs and events.
  • Service-owned operational data boundaries can be maintained.
  • Organization context can be preserved across service boundaries.
  • Organization-owned resources cannot be accessed without appropriate organization context and authorization.
  • Events can preserve organization context through asynchronous processing.
  • Background processing can preserve tenant isolation.
  • Cross-tenant access attempts can be detected and rejected.

The architecture should also be evaluated for signs of excessive coupling as implementation progresses.

Follow-Up

This decision establishes the architectural foundation for subsequent Zelvoryqa decisions.

Follow-up ADRs should be created in dependency order so that each decision builds on architectural constraints established by the preceding decisions.

Core Application Architecture

The first follow-up decisions establish the core application architecture:

  1. ADR-0002: Adopt Multi-Tenant SaaS Architecture

    • Define organization and tenant terminology.
    • Define user-to-organization membership.
    • Define organization context.
    • Define tenant-isolation requirements.
    • Define platform-level versus organization-owned resources.
    • Define logical versus physical tenant isolation boundaries.

  2. ADR-0003: Define Service Data Ownership and Tenant Data Isolation

    • Define service-owned operational data.
    • Define organization ownership within service-owned data.
    • Prohibit direct cross-service database access.
    • Define the initial tenant data-isolation strategy.
    • Define how service ownership and organization ownership interact.

  3. ADR-0004: Adopt Event-Driven Integration

    • Define event producer and consumer responsibilities.
    • Define event ownership.
    • Define event contracts.
    • Define subscriptions and consumers.
    • Define delivery semantics.
    • Define idempotency requirements.
    • Define retry and dead-letter behavior.
    • Define ordering requirements where applicable.
    • Define organization-context propagation through events.

  4. ADR-0005: Define Synchronous Service Communication

    • Define when synchronous communication is appropriate.
    • Define service-to-service communication expectations.
    • Define timeout and retry requirements.
    • Define error contracts.
    • Define request correlation.
    • Define organization-context propagation across synchronous boundaries.

  5. ADR-0006: Define Authentication, Organization Membership, and Authorization

    • Define authentication responsibilities.
    • Define identity-provider boundaries.
    • Define organization membership validation.
    • Define organization selection and trusted organization context.
    • Define roles and permissions.
    • Define service-level authorization responsibilities.
    • Define authentication versus organization-level authorization.

  6. ADR-0007: Define API Gateway and External API Architecture

    • Define external API entry points.
    • Define gateway routing responsibilities.
    • Define authentication integration.
    • Define organization-context establishment and propagation.
    • Define rate-limiting responsibilities.
    • Define request validation and tracing responsibilities.
    • Define which security controls remain the responsibility of downstream services.

Platform and Infrastructure Architecture

After the core application architecture is established:

  1. ADR-0008: Adopt Containerized Service Deployment
  2. ADR-0009: Adopt Kubernetes for Service Orchestration
  3. ADR-0010: Adopt Infrastructure as Code
  4. ADR-0011: Define Secrets and Workload Identity Management
  5. ADR-0012: Define Observability Architecture
  6. ADR-0013: Define Service Reliability and Resilience Patterns
  7. ADR-0014: Define Backup, Restore, and Disaster Recovery Strategy

Software Delivery Architecture

After the runtime and infrastructure foundations are established:

  1. ADR-0015: Define CI/CD Architecture
  2. ADR-0016: Define Deployment Strategy
  3. ADR-0017: Define API and Event Contract Versioning
  4. ADR-0018: Define Database Migration Strategy

Supporting Platform Capabilities

Supporting capabilities should be introduced when their requirements become concrete:

  1. ADR-0019: Define Caching Strategy
  2. ADR-0020: Define Operations Intelligence Data Architecture
  3. ADR-0021: Define Search Architecture
  4. ADR-0022: Define Object Storage Strategy
  5. ADR-0023: Define Local Development Environment
  6. ADR-0024: Define Configuration Management
  7. ADR-0025: Define Audit Logging Architecture
  8. ADR-0026: Define Rate Limiting, Quotas, and Tenant Fairness
  9. ADR-0027: Define Service-Level Objectives and Reliability Targets
  10. ADR-0028: Define Analytics and AI Isolation Requirements

Not every later ADR needs to be written before implementation begins.

The first seven ADRs establish the core architectural model and should be completed before substantial implementation of business services:

ADR-0001  Microservices
     |
     v
ADR-0002  Multi-Tenant SaaS Architecture
     |
     v
ADR-0003  Service Data Ownership
           and Tenant Data Isolation
     |
     v
ADR-0004  Event-Driven Integration
     |
     v
ADR-0005  Synchronous Service Communication
     |
     v
ADR-0006  Authentication, Membership
           and Authorization
     |
     v
ADR-0007  API Gateway and External APIs

Later ADRs should be created when the corresponding architectural decision becomes necessary rather than documenting speculative implementation choices prematurely.

Service-specific architecture documentation should be created as implementation of each business capability begins.

References