Database Architecture¶

Status: Implemented

Overview¶

The Nivron database architecture provides the persistent foundation for the SaaS platform.

It is designed around business domains, multi-tenant evolution and controlled schema versioning. Database changes are introduced exclusively through Alembic migrations, ensuring reproducible deployments and a complete history of structural evolution.

The database layer is shared by platform services while preserving clear ownership boundaries between domains.

Design Principles¶

Current Schemas¶

Future domains will introduce additional schemas without modifying existing ownership boundaries.

Migration History¶

Published migrations are immutable and form the authoritative history of the platform database.

Current Entity Relationships¶

erDiagram
    ORGANIZATIONS ||--o{ USERS : owns

    ORGANIZATIONS {
        uuid uuid
        string slug
        string name
        string status
    }

    USERS {
        uuid uuid
        string username
        string status
    }

The current implementation establishes the identity foundation. Additional entities will be introduced by future modules while preserving existing relationships.

Database Lifecycle¶

Database changes follow a controlled lifecycle:

1. Model definition.
2. Alembic migration generation.
3. Migration review.
4. Version control.
5. Deployment.
6. Runtime validation.

This process guarantees consistent schema evolution across all environments.

Architectural Principles¶

The database is organized around business domains rather than application features.

This approach:

• isolates responsibilities;
• reduces coupling;
• simplifies future expansion;
• enables independent module evolution;
• preserves long-term maintainability.

Applications access the database through shared platform services instead of embedding persistence conventions independently.

Related Topics¶

• Platform Framework
• Identity Foundation
• API Architecture
• Control Plane