API Architecture¶

Status: Implemented

Overview¶

The Nivron API is the primary interface between clients and the Control Plane. It follows a versioned architecture designed to provide long-term compatibility while allowing new capabilities to evolve without breaking existing integrations.

The current implementation is based on FastAPI and is organized into logical routing layers.

Objectives¶

Provide a stable public API.
Separate public and internal endpoints.
Enable independent API evolution.
Maintain backward compatibility through versioning.
Keep routing modular and easy to extend.

Current Routing Structure¶

Path	Purpose
`api/core/`	Core platform endpoints.
`api/internal/`	Internal operational endpoints.
`api/v1/`	Versioned public API.
`main.py`	Registers routers and starts the application.

Request Lifecycle¶

flowchart LR

Client --> FastAPI
FastAPI --> Router
Router --> BusinessModule
BusinessModule --> PlatformFramework
PlatformFramework --> PostgreSQL

Current Public Endpoints¶

Endpoint	Description
`/`	Platform information page.
`/health`	Service health check.
`/ready`	Readiness check including database connectivity.
`/api/v1/platform`	Platform metadata.

Internal Endpoints¶

Internal endpoints are reserved for operational use and are protected independently from the public API.

Endpoint	Purpose
`/internal/status`	Platform operational status.

API Versioning¶

The current public version is exposed under:

/api/v1/

Future versions will be introduced alongside existing ones to preserve compatibility. Existing clients should continue to function without requiring immediate upgrades.

Design Principles¶

Stable public contracts.
Explicit API versioning.
Thin routing layer.
Business logic isolated in modules.
Shared services provided by the Platform Framework.

Control Plane
Platform Framework
Identity Foundation
Database Architecture

Next Step¶

Continue with the Architecture Decision Records (ADRs) to understand the key architectural decisions that shaped the platform.