ADR-0002: Adopt Multi-Tenant SaaS Architecture
Status: Accepted Date: 2026-10-05 Decision Owners: Zelvoryqa Architecture Technical Area: Multi-Tenancy / System Architecture Related ADRs: ADR-0001: Adopt Microservices Based on Business Capabilities
Context
Zelvoryqa is designed as a multi-tenant SaaS operations platform supporting inventory, warehousing, purchasing, order management, fulfillment, shipping, notifications, and operational intelligence.
The platform must support multiple independent customer organizations using the same Zelvoryqa platform while maintaining clear boundaries between their users, operational data, configuration, permissions, workflows, events, analytics, and operational activity.
An organization may contain:
- Multiple users
- Multiple locations
- Multiple warehouses or facilities
- Organization-specific roles and permissions
- Organization-specific configuration
- Inventory
- Customers
- Suppliers
- Purchase orders
- Orders
- Fulfillment activity
- Shipments
- Operational analytics and intelligence
A user may also need to belong to more than one organization.
Multi-tenancy therefore cannot be implemented solely as a user-interface concern or as a convention applied independently by individual services.
Organization identity and tenant isolation must be foundational properties of the architecture.
The architecture must answer several fundamental questions:
- What represents a customer within Zelvoryqa?
- What constitutes a tenant?
- How are users associated with organizations?
- How is the organization for an operation established?
- How is organization context preserved across distributed system boundaries?
- Which resources belong to organizations?
- Which resources are platform-level?
- How is unauthorized cross-organization access prevented?
- How should logical tenant isolation relate to physical infrastructure and data isolation?
- How can stronger isolation be introduced later without redesigning the business services?
These decisions must be established before detailed data ownership, authentication and authorization, API, event, and persistence decisions are made.
Decision
Zelvoryqa will be designed as a multi-tenant SaaS platform in which each customer organization represents a logical tenant boundary.
The product-level term organization will represent the business or customer using Zelvoryqa.
The technical term tenant will describe the isolation boundary associated with an organization.
In the initial architecture:
One organization corresponds to one tenant.
This relationship defines the logical security and isolation boundary. It does not imply that each organization receives dedicated service instances, databases, schemas, Kubernetes namespaces, or other physical infrastructure.
Business services will operate across multiple organizations while maintaining logical isolation between organization-owned resources.
Multi-tenancy will be treated as a cross-cutting architectural property rather than as functionality owned by a single business service.
Organization
An organization represents a customer, company, or independent business entity using Zelvoryqa.
An organization may own or contain:
- Users through organization membership
- Roles and permissions
- Locations
- Warehouses and facilities
- Customers
- Suppliers
- Inventory
- Purchase orders
- Orders
- Fulfillment activity
- Shipments
- Organization-specific configuration
- Operational workflows
- Analytics
- Intelligence and recommendations
- Audit activity
Warehouses, locations, departments, and similar organizational structures do not represent separate tenants merely because they require their own operational boundaries.
For example:
Organization A
|
+-- Chicago Warehouse
|
+-- Atlanta Warehouse
|
+-- Dallas Warehouse
All three warehouses belong to the same organization and therefore remain within the same tenant boundary.
Tenant
A tenant represents the technical isolation boundary associated with an organization.
The distinction between organization and tenant is intentional:
- Organization is the business and domain concept.
- Tenant is the architectural and security isolation concept.
Application APIs, domain models, and user-facing functionality should generally use organization terminology when describing business behavior.
Architecture, security, data isolation, infrastructure, and operational documentation may use tenant terminology when discussing isolation characteristics.
User Membership
A user may belong to one or more organizations.
Authentication of a user does not by itself grant access to organization-owned resources.
Access to an organization requires a valid relationship between:
User
|
v
Organization Membership
|
v
Organization
A membership associates a user with an organization and provides the basis for evaluating organization-specific authorization.
Conceptually:
User
|
+---- Membership ----> Organization A
|
+---- Membership ----> Organization B
The same authenticated identity may therefore operate within different organization contexts.
Permissions within those organizations may differ.
For example, a user could potentially be:
Organization A
Warehouse Administrator
Organization B
Read-Only Analyst
The detailed role and permission model will be defined by the authentication and authorization ADR.
Organization Context
Every operation involving organization-owned resources must execute within an explicit and validated organization context, regardless of whether the operation was initiated by a user, service, event consumer, scheduled process, or other workload.
Organization context identifies the organization on whose behalf an operation is being performed.
Conceptually:
Authenticated User
|
v
Organization Membership
|
v
Selected / Resolved Organization
|
v
Authorization
|
v
Organization Context
|
v
Business Operation
Authentication answers:
Who is making the request?
Organization context answers:
Which organization are they acting for?
Authorization answers:
What are they allowed to do within that organization?
These are separate concerns.
A service must not assume that an authenticated user is authorized to access every organization.
Similarly, an authenticated service or workload identity does not by itself grant unrestricted access to organization-owned resources. Non-user workloads must operate within an explicitly authorized organization context when accessing organization-owned resources.
The detailed representation of identities, service identities, workload identities, organization membership, roles, and permissions will be defined by the authentication and authorization ADR.
Organization Context Validation
Organization context supplied by a client must not automatically be trusted.
The platform must establish that:
- The caller has an authenticated identity.
- The requested organization exists.
- The identity has valid membership or other authorized access to that organization.
- The requested operation is permitted within that organization.
- The requested resource belongs to the expected organization where applicable.
Conceptually:
Request
|
v
Authentication
|
v
Organization Resolution
|
v
Membership Validation
|
v
Authorization
|
v
Service Validation
|
v
Organization-Scoped Resource
An API gateway or other platform component may assist in establishing organization context.
However, organization context is not considered secure merely because it passed through a trusted gateway.
Business services remain responsible for enforcing the organization boundary appropriate to the resources they own.
The exact mechanism for representing and propagating organization context will be defined in subsequent ADRs.
Organization Context Across Distributed Boundaries
Organization context must be preserved whenever organization-scoped work crosses an architectural boundary.
This includes:
- External API requests
- Synchronous service-to-service requests
- Business events
- Event consumers
- Background jobs
- Scheduled processing
- Retry operations
- Dead-letter processing
- Analytical processing
- Audit records
- Relevant logs and traces
For example:
Organization A Request
|
v
Order Service
|
| OrderCreated
| Organization A
v
Event Bus
|
+----> Inventory Service
|
+----> Fulfillment Service
|
+----> Operations Intelligence
Consumers processing OrderCreated must retain the organization context associated with the event.
A retry, replay, or delayed execution must not cause the operation to lose its tenant boundary.
The exact event envelope and synchronous context-propagation mechanisms are outside the scope of this ADR.
Organization-Owned Resources
Business resources belong to an organization unless explicitly defined as platform-level resources.
Examples of organization-owned resources include:
- Inventory
- Warehouses
- Locations
- Customers
- Suppliers
- Purchase orders
- Orders
- Fulfillment records
- Shipments
- Organization-specific configuration
- Organization-specific analytics
- Organization-specific forecasts and recommendations
Organization ownership must be explicit enough for services to enforce tenant isolation.
For example:
Order Service
|
v
Order Operational Data
|
+---- Order 1001 ---> Organization A
+---- Order 1002 ---> Organization A
+---- Order 2001 ---> Organization B
The Order Service remains authoritative for all order data.
Organization A owns its order records.
Organization B owns its order records.
Organization ownership therefore does not imply ownership of the service itself.
Resource identifiers do not grant access to resources. Possession or discovery of an identifier for an organization-owned resource must not bypass organization membership, authorization, resource ownership validation, or tenant isolation.
For example, knowing the identifier of an order owned by another organization does not authorize access to that order.
Platform-Level Resources
Some resources may exist at the Zelvoryqa platform level rather than belonging to an individual organization.
Examples may include:
- Platform configuration
- Supported system capabilities
- Global service metadata
- Platform administration data
- Platform-wide operational configuration
Platform-level resources and operations must explicitly be defined as platform-level.
The absence of organization context does not imply platform-level access. An operation involving organization-owned resources that requires organization context must fail if valid organization context is unavailable.
Platform-level operations must use separate, explicitly authorized execution paths and must not rely on a missing organization identifier as the mechanism for bypassing tenant isolation.
Conceptually:
Organization-Scoped Operation
|
| organization context missing
v
REJECT
Explicit Platform-Level Operation
|
| platform authorization
v
ALLOW
Organization Lifecycle
Organizations will have a lifecycle that may include creation, activation, suspension, deactivation, migration, and eventual deletion or retention.
The exact organization lifecycle model and lifecycle states are outside the scope of this ADR.
Organization lifecycle operations must preserve tenant isolation.
Suspension, deactivation, deletion, migration, or other lifecycle changes must not cause organization-owned resources to lose their organization ownership, become implicitly platform-level, or become accessible to another organization.
Organization lifecycle processing must also preserve applicable authorization, auditability, data-retention, and isolation requirements.
Tenant Isolation
Zelvoryqa will require logical tenant isolation across organization-owned resources.
A user or workload operating within Organization A must not be able to access Organization B's resources unless an explicitly designed and authorized cross-organization capability permits that interaction.
Tenant isolation applies across:
- APIs
- Service operations
- Data access
- Events
- Background processing
- Caches
- Search
- Analytics
- AI and machine-learning processing
- Audit records
- Operational tooling
Tenant isolation is a system property and must not depend solely on:
- User-interface filtering
- Client-provided identifiers
- Developer convention
- API gateway filtering
- Database query conventions without validation
- Authentication alone
Isolation must be enforceable and testable at appropriate system boundaries.
Cross-tenant access must be denied by default.
Any capability that intentionally accesses, aggregates, transfers, or shares information across organization boundaries must be explicitly designed and authorized as a cross-organization capability.
Such capabilities must not bypass the tenant model. They must define the authorization, resource ownership, data-sharing, auditing, and isolation rules required for the cross-organization interaction.
Defense in Depth
Tenant isolation should use multiple enforcement layers where appropriate.
Conceptually:
Client
|
v
Authentication
|
v
Organization Membership
|
v
Authorization
|
v
Service Boundary
|
v
Organization-Scoped Data Access
Failure or bypass of one layer should not automatically expose another organization's resources.
For example, a malformed or malicious request containing another organization's resource identifier should still be rejected by the service responsible for that resource.
Tenant isolation must therefore be enforced at the resource-owning service boundary rather than relying exclusively on upstream validation.
Logical and Physical Isolation
Zelvoryqa distinguishes between logical tenant isolation and stronger forms of infrastructure isolation.
Logical isolation means that organization-owned resources remain securely separated even when organizations share application or infrastructure resources.
Stronger infrastructure isolation means that some tenant resources are separated through dedicated or independently isolated infrastructure boundaries, such as databases, compute, or other infrastructure components.
Zelvoryqa requires logical tenant isolation from the beginning.
Zelvoryqa will not require dedicated infrastructure for every organization by default.
The architecture must allow stronger infrastructure isolation to be introduced where justified by:
- Security requirements
- Regulatory requirements
- Enterprise customer requirements
- Workload characteristics
- Performance requirements
- Data residency requirements
- Operational risk
Possible future deployment models may include:
Shared Infrastructure
|
+---- Organization A
+---- Organization B
+---- Organization C
or:
Hybrid Infrastructure
Shared Environment
+---- Organization A
+---- Organization B
Dedicated Environment
+---- Organization C
Business services should not depend unnecessarily on the physical tenant-storage or deployment topology.
The specific persistence, tenant data-partitioning, and persistence-isolation strategy will be decided in ADR-0003.
Multi-Tenancy and Microservices
Multi-tenancy does not alter the business-capability boundaries established by ADR-0001.
A separate instance of each business service will not be created for every organization by default.
Instead:
Inventory Service
+----------+----------+
| | |
v v v
Org A Org B Org C
Inventory Inventory Inventory
The Inventory Service remains the authoritative service for inventory behavior across organizations while enforcing isolation between organization-owned inventory.
The same principle applies to other business services.
Multi-Tenancy and Events
Business events representing organization-owned activity must preserve organization context.
A producer owns the business fact being published.
Consumers independently determine whether and how to process the event according to their responsibilities.
Conceptually:
Order Service
|
| OrderCreated
| Organization A
v
Event Bus
|
+----> Inventory Service
|
+----> Fulfillment Service
|
+----> Operations Intelligence
Consumers must not infer organization context from unrelated state when the event represents organization-scoped activity.
An organization-scoped event that lacks required organization context must not be processed as though it were platform-level activity.
Detailed event-envelope, delivery, subscription, retry, idempotency, ordering, and dead-letter decisions will be defined by ADR-0004.
Multi-Tenancy and Operations Intelligence
Operations Intelligence will be organization-aware by default.
Analytics, forecasts, optimization results, recommendations, and AI-generated insights derived from organization-owned data must remain within the corresponding organization boundary.
Conceptually:
Organization A Events
|
v
Operations Intelligence
|
v
Organization A Analytics
Organization B Events
|
v
Operations Intelligence
|
v
Organization B Analytics
Cross-organization analytics are not implicitly permitted simply because Operations Intelligence receives data from multiple organizations.
Any future platform-wide or cross-organization analytics capability must explicitly define:
- Authorization
- Data aggregation
- Privacy
- Anonymization where required
- Tenant isolation
- Permitted data usage
Such functionality requires a separate architectural decision if introduced.
Rationale
SaaS Scalability
A shared multi-tenant architecture allows Zelvoryqa to support multiple organizations without requiring a separate application architecture for each customer.
Organizations can be onboarded, configured, operated, and scaled without creating unique application builds.
Explicit Security Boundary
Making organization context foundational establishes a clear boundary for authorization and resource ownership.
This reduces the risk of treating tenant isolation as an implementation detail added independently by individual services.
Support for Multi-Organization Users
Separating authenticated identity from organization context allows a single user identity to participate in multiple organizations without requiring separate user accounts.
Consistency Across Services
A common organization model provides a consistent basis for service APIs, events, data access, background processing, analytics, authorization, and observability.
Service Independence
Multi-tenancy remains compatible with the business-capability service boundaries established by ADR-0001.
Services remain independently deployable and authoritative for their business data while supporting multiple organizations.
Infrastructure Efficiency
Logical isolation allows organizations to share infrastructure where appropriate, avoiding the operational and financial cost of dedicated infrastructure for every tenant.
Future Isolation Flexibility
Separating the logical tenant model from physical deployment topology allows Zelvoryqa to introduce stronger isolation for selected organizations later without changing the fundamental organization model.
Fail-Closed Security Model
Requiring explicit organization context for organization-owned resources ensures that missing, malformed, or untrusted organization information does not implicitly grant broader access.
Platform-level access must be explicitly defined and separately authorized.
Support for Future Cross-Organization Capabilities
Denying cross-tenant access by default does not prevent Zelvoryqa from supporting legitimate future workflows involving multiple organizations.
Cross-organization capabilities can be introduced deliberately with explicit authorization, sharing, auditing, and isolation rules without weakening the default tenant security model.
Alternatives Considered
Alternative 1: Single-Tenant Architecture
Each Zelvoryqa deployment would serve one organization.
Advantages
- Simple tenant isolation
- Simple authorization model
- Reduced risk of cross-tenant data exposure
- Straightforward data ownership
- Easier per-customer customization
Disadvantages
- Separate deployments required for each customer
- Higher infrastructure cost
- Greater operational overhead
- More difficult platform-wide upgrades
- More complex customer onboarding
- Poorer infrastructure utilization
- Does not align with the intended SaaS model
Reason Not Selected
Zelvoryqa is intended to operate as a SaaS platform supporting multiple organizations through a common architecture.
Requiring a separate deployment for every organization would significantly increase operational complexity and limit platform scalability.
Alternative 2: Multi-Tenancy as an Application Convention
Services would support organization identifiers where necessary, but Zelvoryqa would not establish a platform-wide tenant model.
Advantages
- Minimal upfront architectural work
- Individual services can implement tenancy independently
- Fewer initial platform concepts
Disadvantages
- Inconsistent tenant handling
- Increased risk of cross-tenant access
- Different services may interpret tenant boundaries differently
- Event processing may lose organization context
- Background processing may bypass tenant rules
- Authorization becomes inconsistent
- Tenant isolation becomes difficult to test as a system property
Reason Not Selected
Tenant isolation is too important to security and data ownership to depend on conventions independently implemented by each service.
Alternative 3: Dedicated Deployment Per Organization
Each organization would receive dedicated application services and infrastructure.
Advantages
- Strong infrastructure isolation
- Reduced cross-tenant data exposure risk
- Independent infrastructure scaling
- Easier organization-specific infrastructure requirements
Disadvantages
- Significantly higher infrastructure cost
- Increased deployment complexity
- Increased operational overhead
- More difficult upgrades
- More environments to monitor and maintain
- Inefficient for smaller organizations
Reason Not Selected
Dedicated deployments may be appropriate for specific future requirements, but they should not be the default SaaS model.
The architecture should permit stronger isolation without requiring it for every organization.
Alternative 4: Shared Multi-Tenant Platform with Logical Isolation
Organizations share Zelvoryqa services and infrastructure while organization-owned resources remain logically isolated.
Advantages
- Efficient infrastructure utilization
- Centralized platform upgrades
- Easier organization onboarding
- Common operational model
- Supports users belonging to multiple organizations
- Compatible with independent microservices
- Supports stronger infrastructure isolation when needed
- Appropriate for SaaS scaling
Disadvantages
- Tenant isolation requires careful engineering
- Authorization becomes more complex
- Cross-tenant access vulnerabilities become a significant security risk
- Tenant context must be preserved across distributed boundaries
- Testing must include tenant-isolation scenarios
- Noisy-neighbor risks must eventually be addressed
Reason Selected
This model best aligns with Zelvoryqa's SaaS goals while preserving the ability to introduce stronger infrastructure isolation for organizations that require it.
Consequences
Positive
- Zelvoryqa has an explicit tenant model.
- Customer organizations have clearly defined logical boundaries.
- Users may participate in multiple organizations.
- Organization context becomes a consistent distributed-system concept.
- Business resources have explicit organization ownership.
- Tenant isolation becomes a testable architectural requirement.
- Business services can serve multiple organizations without losing service ownership.
- Organization-aware events and analytics have a consistent foundation.
- Shared infrastructure can be used efficiently.
- Stronger infrastructure isolation can be introduced later.
- Platform-level operations are explicitly separated from organization-scoped operations.
- Future cross-organization capabilities can be introduced without weakening the default isolation model.
Negative
- Every organization-scoped workflow must correctly preserve organization context.
- Authorization becomes more complex than authentication alone.
- Services require tenant-aware data access.
- Events require organization awareness.
- Background processing must preserve organization context.
- Service and workload identities require organization-aware authorization when operating on tenant resources.
- Caches and analytical systems must enforce tenant boundaries.
- Testing complexity increases.
- Operational tooling must account for tenant boundaries.
- Organization lifecycle operations require tenant-aware handling.
Risks
- Missing organization filters could expose another organization's data.
- Trusting client-provided organization identifiers could allow unauthorized access.
- Services could incorrectly assume gateway validation is sufficient.
- Event consumers could process data under the wrong organization context.
- Retries or background jobs could lose organization context.
- Service or workload identities could accidentally receive overly broad organization access.
- Resource identifiers could be used to attempt unauthorized cross-tenant access.
- Caches could return data belonging to another organization if cache keys are not tenant-aware.
- Search indexes or analytical stores could expose cross-tenant data.
- Operational telemetry could unintentionally expose sensitive organization information.
- AI or analytical processing could combine organization data without appropriate authorization.
- Organization lifecycle operations could incorrectly alter ownership or isolation.
- A high-volume organization could negatively affect other organizations sharing infrastructure.
Implementation Considerations
Multi-tenancy should be incorporated into common service patterns rather than implemented differently by every business service.
Implementation must eventually establish consistent approaches for:
- Organization identifiers
- Organization creation and lifecycle
- User membership
- Service and workload identity
- Organization selection
- Organization-context representation
- Organization-context propagation
- Authorization
- Organization-scoped data access
- Resource ownership validation
- Tenant-aware caching
- Tenant-aware event processing
- Tenant-aware background jobs
- Tenant-aware analytics
- Cross-organization capabilities
- Auditability
- Isolation testing
Business services should not encode assumptions about whether an organization's data is stored in shared tables, separate schemas, separate databases, or dedicated infrastructure.
Those persistence and infrastructure decisions should remain behind service-owned boundaries where practical.
Cross-tenant access must be denied by default.
Any future workflow that intentionally crosses organization boundaries must define explicit authorization, data-sharing, ownership, and auditing rules rather than bypassing tenant isolation.
Platform-level operations must be explicitly distinguished from organization-scoped operations.
Missing organization context must not be used as a mechanism for obtaining platform-level access.
Operational Considerations
Operational systems must support investigation of organization-specific issues without weakening tenant isolation.
Observability must preserve sufficient organization context to support tenant-aware operational investigation. Logs and distributed traces may include organization identifiers and other relevant organization context where appropriate.
Metrics must be emitted within the correct operational context, but organization identifiers should be used as metric labels or dimensions only when necessary. Unbounded organization-level labels can create excessive metric cardinality and increase observability storage, query, and operational costs.
Tenant-specific business and operational metrics that require organization-level analysis should be handled through appropriate tenant-aware analytical capabilities rather than requiring every platform observability metric to include an organization identifier.
Platform operators may require privileged capabilities for support and incident response.
Such access must be explicitly authorized and auditable rather than implemented as an implicit tenant bypass.
Capacity planning must eventually account for:
- Tenant workload differences
- Noisy-neighbor behavior
- Resource quotas
- Rate limiting
- Tenant fairness
- Organizations requiring stronger isolation
Organization lifecycle operations must account for data retention, backup, restoration, auditability, and isolation requirements.
Backup, restoration, replay, migration, and disaster-recovery procedures must preserve tenant boundaries.
Restoration or migration of one organization's data must not overwrite, expose, or otherwise compromise another organization's resources.
Validation
The multi-tenant architecture will be validated through representative scenarios involving multiple organizations.
At minimum, validation should demonstrate:
- Multiple organizations can exist simultaneously.
- A user can belong to more than one organization.
- A user can operate within an explicitly selected organization context.
- Authentication alone does not grant access to every organization.
- Organization membership can be validated.
- Organization-owned resources are associated with the correct organization.
- Organization A cannot access Organization B's resources without explicit authorization.
- Possession of another organization's resource identifier does not permit access to that resource.
- Missing organization context causes organization-scoped operations to fail.
- Missing organization context does not implicitly grant platform-level access.
- Platform-level operations require explicitly authorized platform-level execution paths.
- Services preserve organization context across synchronous communication.
- Business events preserve organization context.
- Organization-scoped events without required organization context are rejected or otherwise prevented from being processed as platform-level activity.
- Event consumers process data within the correct organization.
- Background processing preserves organization context.
- Service and workload identities remain constrained to explicitly authorized organization contexts.
- Analytical results remain scoped to the correct organization.
- Tenant isolation remains intact during retries and failure recovery.
- Tenant isolation remains intact during organization lifecycle operations.
- Invalid or manipulated organization context is rejected.
- Shared services can support multiple organizations without requiring separate service deployments.
- Cross-organization access is denied unless an explicitly designed and authorized capability permits it.
Tenant-isolation tests should become part of automated integration and end-to-end testing.
Follow-Up
This decision establishes the tenant model required by subsequent Zelvoryqa architectural decisions.
The next decisions should be created in the following order:
- ADR-0003: Define Service Data Ownership and Tenant Data Isolation
- Define service-owned operational data.
- Define organization ownership within service-owned data.
- Select the initial tenant data-partitioning strategy.
- Define the isolation spectrum between shared and dedicated persistence.
- Define how shared and dedicated persistence may coexist.
-
Define data-access isolation requirements.
-
ADR-0004: Adopt Event-Driven Integration
- Define event producers and consumers.
- Define event ownership.
- Define event contracts and envelopes.
- Define organization-context propagation.
-
Define delivery semantics, retries, idempotency, ordering, and dead-letter behavior.
-
ADR-0005: Define Synchronous Service Communication
- Define when synchronous communication is appropriate.
- Define service-to-service communication expectations.
- Define organization-context propagation.
-
Define timeout, retry, error, and correlation requirements.
-
ADR-0006: Define Authentication, Organization Membership, and Authorization
- Define identity-provider responsibilities.
- Define user, service, and workload identities.
- Define organization membership.
- Define organization selection.
- Define roles and permissions.
- Define trusted organization context.
- Define service-level authorization responsibilities.
-
Define platform-level authorization.
-
ADR-0007: Define API Gateway and External API Architecture
- Define external API entry points.
- Define gateway responsibilities.
- Define authentication integration.
- Define organization-context establishment and propagation.
- Define which authorization and tenant-isolation responsibilities remain with business services.
Later ADRs will define physical infrastructure, deployment, observability, resilience, CI/CD, analytics, and other implementation-specific decisions.