Skip to content

Control Plane¶

Status: Implemented

Overview¶

The Control Plane is the central service of the Nivron platform.

It exposes the public API, coordinates shared platform capabilities, orchestrates application services and provides the execution environment for current and future platform modules.

Every external request enters the platform through the Control Plane, making it the primary orchestration layer of the SaaS architecture.

Core Responsibilities¶

Responsibility	Description
Public API	Expose versioned platform APIs.
Internal Services	Host operational endpoints used by the platform.
Application Bootstrap	Initialize the FastAPI application.
Configuration	Load shared platform configuration.
Framework Integration	Consume reusable services from the Platform Framework.
Readiness	Validate database connectivity and runtime health.
Module Hosting	Execute business modules while keeping them isolated.

Current Implementation¶

The current implementation resides under:

apps/control-plane/src/app

Directory	Responsibility
`api/`	Public and internal routers.
`api/core/`	Core platform endpoints.
`api/internal/`	Operational endpoints.
`api/v1/`	Versioned public API.
`modules/`	Business capabilities.
`main.py`	FastAPI bootstrap and router registration.

Startup Sequence¶

flowchart TD
    A[Application Startup] --> B[Load Configuration]
    B --> C[Create FastAPI Application]
    C --> D[Register Routers]
    D --> E[Initialize Platform Framework]
    E --> F[Validate Database Connectivity]
    F --> G[Ready to Serve Requests]

Request Flow¶

flowchart LR
    CLIENT[Client]
    API[FastAPI]
    ROUTER[Router]
    MODULE[Business Module]
    FRAMEWORK[Platform Framework]
    DB[(PostgreSQL)]

    CLIENT --> API
    API --> ROUTER
    ROUTER --> MODULE
    MODULE --> FRAMEWORK
    FRAMEWORK --> DB

Business Modules¶

Module	Status	Description
Organizations	Implemented	Organization management foundation.

Future modules should follow the same architectural boundaries while remaining independent from one another.

Public Endpoints¶

Endpoint	Purpose
`/health`	Health verification.
`/ready`	Readiness verification including database connectivity.
`/api/v1/platform`	Platform metadata.
`/internal/status`	Protected operational status endpoint.

Architectural Principles¶

Thin Control Plane.
Modular business capabilities.
Shared services delegated to the Platform Framework.
Explicit API versioning.
Independent evolution of platform modules.