Multi-Tenant Architecture

Executive Summary

Multi-Tenant Architecture defines how Algosure separates customer organizations, tenant context, organization context, users, data, documents, AIOS access, integrations, audit records, and entitlements.

Why This Exists

Algosure serves multiple customer organizations in one platform. Tenant isolation must be a first-order architecture constraint across APIs, Spring Boot Modulith modules, data stores, documents, events, AIOS, notifications, analytics, and integrations.

Owner

The owner is the Chief Product Officer and Enterprise Architect.

Business Value

Strong multi-tenancy prevents cross-customer data exposure, protects commercial confidentiality, supports enterprise adoption, and creates a stable foundation for scale.

Tenant Context Model

flowchart TB
    User[User Context]
    Tenant[Tenant Context]
    Organization[Organization Context]
    Membership[Organization Membership]
    Entitlement[Billing Entitlement]
    Domain[Domain-Owned Work]
    Audit[Audit Context]

    User --> Tenant
    Tenant --> Organization
    Organization --> Membership
    Membership --> Entitlement
    Entitlement --> Domain
    Domain --> Audit

Context Responsibilities

Context	Owner	Meaning
Tenant context	Organization Domain with Identity enforcement	Customer isolation boundary used by APIs, modules, data, documents, events, AIOS, and integrations.
Organization context	Organization Domain	Business organization facts, profile, operating context, and membership relationships.
User context	Identity Domain	Authenticated user identity, roles, permissions, memberships, and access state.
Entitlement context	Billing Domain	Subscription plan, feature access, limits, and commercial availability.
Audit context	Owning Domain with security governance	Who did what, under which tenant, organization, role, permission, entitlement, and approval state.

Keycloak Tenant Mapping

Keycloak can carry tenant and organization hints through roles, groups, attributes, or claims, but it is not the source of business tenant ownership.

Mapping Area	Rule
Realm	Algosure realm provides authentication boundary; it does not replace the Organization Domain.
Groups	Groups may represent enterprise structures, organizations, departments, or teams, but must be mapped into Algosure Organization and Identity records before authorization.
Roles	Roles may signal platform or client access, but Identity maps them to Algosure permissions and tenant access.
Claims	Tenant ID and organization ID claims are validated hints, not trusted source facts by themselves.
Multi-tenant users	A user may authenticate once and then operate under explicitly selected and authorized organization context.
Tenant offboarding	Removing tenant access requires Identity and Organization state changes, Keycloak mapping review, token/session revocation where required, and audit.

Multi-Tenant Rules

Rule	Requirement
Tenant context is mandatory	Customer-data access must resolve tenant context before business work.
Organization context is validated	Organization-scoped work must verify organization membership and tenant alignment.
Tenant filtering is server-side	Clients cannot be trusted to provide isolation; APIs and repositories enforce tenant scope.
Data stores preserve tenant isolation	PostgreSQL, Redis, object storage, search, vector memory, and analytics projections must carry tenant context.
Events carry tenant metadata	Domain, application, and integration events must include tenant and organization metadata where applicable.
AIOS access is tenant-scoped	AIOS receives only tenant-authorized context for approved tasks.
Integrations are tenant-bound	External credentials, consent, provider links, and data exchanges are scoped to tenant and organization.

Tenant Isolation Layers

Layer	Isolation Control
API boundary	Authentication, authorization, tenant resolution, organization checks, entitlement checks.
Application services	Tenant-aware use-case execution and approval policy.
Domain modules	Source-owned business rules and tenant-scoped lifecycle state.
Repositories	Row-level tenant filtering and no cross-module direct repository access.
Documents	Tenant-scoped metadata, access control, classification, and audit.
Events	Tenant metadata, correlation, causation, and audited consumption.
AIOS	Scoped context, governed internal APIs, memory isolation, and approval controls.

Non-Implementation Boundary

This document does not define tenancy storage strategy, schema design, Keycloak realm layout, row-level security implementation, or deployment topology.