Repository Structure¶

Status: Implemented

Overview¶

The Nivron repository is organized around clear functional boundaries rather than technology-specific layers.

Each top-level directory represents a distinct responsibility within the platform. This structure allows applications, shared capabilities, deployment definitions, configuration and documentation to evolve without creating unnecessary coupling between components.

The repository is intentionally designed to support long-term growth, modular development, maintainability and controlled platform evolution.

Top-Level Structure¶

Each directory has a defined architectural responsibility. New code should be placed according to that responsibility rather than according to the language, framework or vendor technology used to implement it.

Applications¶

The apps/ directory contains executable applications that compose the Nivron platform.

Applications may depend on shared platform capabilities, but they must preserve their own runtime and deployment boundaries.

Shared Platform¶

The platform/ directory contains reusable capabilities shared across applications.

Shared platform modules must remain generic. Application-specific business logic should remain inside the application that owns it.

Deployment Definitions¶

The deploy/ directory contains deployment definitions for the different platform execution contexts.

Deployment configuration is kept separate from application code so that runtime topology, networking, secrets and infrastructure concerns do not become embedded in business logic.

Typical deployment scopes include:

• SaaS platform services;
• public-facing services;
• edge or local execution services;
• on-premises deployment models.

This separation allows the same application code to be deployed consistently across different environments.

Documentation and Governance¶

Documentation is treated as an official platform artifact.

The repository includes documentation for:

• architecture;
• platform concepts;
• operations;
• administration;
• development standards;
• technical references;
• NVR governance records.

Keeping documentation within the repository ensures that architectural decisions, implementation changes and operational guidance evolve together with the software.

Design Philosophy¶

The repository follows a modular architecture based on responsibility separation.

Placement Rules¶

When introducing a new capability, use the following rules:

• place executable product services under apps/;
• place reusable platform services and libraries under platform/;
• place deployment and runtime definitions under deploy/;
• place shared environment configuration under config/;
• place architectural, operational and governance content under docs/;
• avoid creating cross-directory dependencies that bypass defined contracts.

A new module should be introduced when an existing component would otherwise expand beyond its assigned responsibility.

Repository Evolution¶

As new capabilities are introduced, they should be added to the appropriate architectural module instead of expanding existing components beyond their responsibilities.

This approach preserves consistency, keeps the repository easy to navigate and reduces the risk of architectural drift.

Repository changes that introduce new top-level responsibilities should be treated as architectural decisions and reflected in the documentation.

Related Topics¶

• Architecture Overview
• Platform Framework
• Control Plane
• Database Architecture