Architecture Decisions (ADRs)
ADR-002: PostgreSQL Shared-Schema Multi-Tenancy
Decision to use single-schema multi-tenancy with row-level tenant_id filtering over schema-per-tenant.
ADR-002: PostgreSQL Shared-Schema Multi-Tenancy
- Status:
ACCEPTED - Deciders: Lead Architect
- Date: September 2026
Context
We evaluated:
- Database-per-tenant (complex dynamic routing, connection pool explosion).
- Schema-per-tenant (schema migrations take hours across hundreds of tenants).
- Shared-database, shared-schema (PostgreSQL public schema with
tenant_idforeign keys).
Decision
Adopt Shared-Database, Shared-Schema Multi-Tenancy:
- Exactly one PostgreSQL database, one schema.
- Strict data layer enforcement via
TenantScopedManagerandTenantResolutionMiddleware.
Consequences
- Positive: Instantaneous database migrations across all tenants simultaneously; shared connection pooling; low infrastructure cost.
- Negative: High vigilance required to prevent queries omitting
tenant_idfilters.
ADR-001: Modular Monolith vs Microservices
Decision to structure the backend as a single cohesive modular monolith rather than distributed microservices.
ADR-003: Redis for Caching, Celery Broker & Distributed Locks
Standardizing on Redis 7 as the single multi-purpose in-memory infrastructure component.