Platform Framework¶

Status: Implemented

Overview¶

The Platform Framework provides the shared foundation used by Nivron applications.

Instead of duplicating common functionality across services, reusable capabilities are centralized in a single framework with explicit ownership, stable interfaces and consistent behavior.

The current implementation is located under:

platform/framework/nivron_framework

It is already consumed by the Control Plane and is intended to support future Nivron applications without coupling them to application-specific implementation details.

Purpose¶

The framework exists to provide common platform capabilities that should behave consistently across services.

Its responsibilities include:

• configuration management;
• database connectivity;
• database session handling;
• internal security primitives;
• identifier generation;
• audit foundations;
• observability foundations;
• shared identity components.

Application-specific business logic must remain outside the framework.

Design Goals¶

Current Structure¶

The distinction between Implemented and Foundation is intentional. Implemented packages expose active capabilities already consumed by applications, while foundation packages establish the architectural location for capabilities that will evolve incrementally.

Framework Architecture¶

flowchart TD
    APP["Nivron Application"]

    subgraph FRAMEWORK["Platform Framework"]
        CONFIG["Configuration"]
        SECURITY["Security"]
        DATABASE["Database"]
        IDENTIFIERS["Identifiers"]
        AUDIT["Audit Foundation"]
        OBSERVABILITY["Observability Foundation"]
        IDENTITY["Identity Foundation"]
    end

    POSTGRES["PostgreSQL"]
    APIKEY["Internal API Key"]
    UUIDV7["UUID v7"]

    APP --> CONFIG
    APP --> SECURITY
    APP --> DATABASE
    APP --> IDENTIFIERS
    APP --> AUDIT
    APP --> OBSERVABILITY
    APP --> IDENTITY

    DATABASE --> POSTGRES
    SECURITY --> APIKEY
    IDENTIFIERS --> UUIDV7

The framework is consumed by applications through shared Python packages. Applications depend on framework contracts, while the framework must not depend on application code.

Shared Capabilities¶

Dependency Direction¶

The expected dependency direction is:

flowchart LR
    APP["Application"] --> FRAMEWORK["Platform Framework"]
    FRAMEWORK --> EXTERNAL["External Services and Libraries"]

The following dependency direction is not allowed:

flowchart LR
    FRAMEWORK["Platform Framework"] -. prohibited .-> APP["Application"]

This rule prevents circular dependencies and ensures that the framework remains reusable.

Application Integration¶

Applications should consume framework capabilities instead of reimplementing them locally.

For example:

• application settings should use the shared configuration layer;
• database health checks should use the shared database capability;
• internal authentication should use shared security primitives;
• platform identifiers should use the shared identifier service;
• future audit and observability behavior should be integrated through framework-owned abstractions.

This approach allows platform-wide changes to be introduced in one place while keeping application code focused on business behavior.

Ownership Boundaries¶

The framework owns reusable platform behavior.

It does not own:

• application routes;
• application-specific workflows;
• domain-specific business rules;
• user interface behavior;
• vendor-specific execution logic;
• deployment topology.

These concerns belong to their respective applications, modules, Connectors or deployment definitions.

Evolution Rules¶

New framework capabilities should be introduced only when they are:

• reusable by more than one application;
• independent from application-specific business logic;
• suitable for a stable shared interface;
• consistent with existing platform conventions;
• documented as part of the platform architecture.

A capability should remain inside an application until there is a clear architectural reason to promote it into the framework.

Architectural Principles¶

Related Topics¶

• Architecture Overview
• Repository Structure
• Database Architecture
• Identity Foundation
• Control Plane