Engine Database Architecture

This document details the database persistence architecture of the Niksphere Engine, explaining how relational data storage, multi-database schema isolation, and storage drivers operate under the hood.

1. Dual-Driver Storage Architecture

The Niksphere Engine incorporates a flexible dual-driver storage abstraction supporting two distinct relational backends:

Rendering diagram...

PostgreSQL (Enterprise & Cloud Production)

• Architecture: Client-server relational database.
• Use Case: Production environments, multi-tenant cloud deployments, high-concurrency enterprise workloads.
• Features: Connection pooling, SSL/TLS transport security, online backups, horizontal read scaling.

Embedded SQLite (Zero-Config & Edge)

• Architecture: In-process, serverless CGO-free file database engine.
• Use Case: Local developer workstations, edge devices, single-tenant installations, testing environments.
• Features: Zero external installation, single-file storage (niksphere_main.db), zero network latency.

2. Multi-Database Schema Isolation

To enforce security boundaries, data integrity, and compliance, the Niksphere Engine segregates persistence into distinct functional databases (or isolated SQLite files / PostgreSQL schemas):

Database Identifier	Purpose	Storage Scope
authDB	Identity Provider (IDP Broker)	User credentials, password hashes, OAuth2/OIDC clients, active tokens, and external IDP federation configs.
engineDB	Engine Metadata & Manifests	Installed App packages, version history, effective AST layer definitions, system settings, and audit logs.
tenantDB	Business Application Data	Runtime entity records, customer data, and operational business transactions.

3. Storage Backend Decision Matrix

Criteria	PostgreSQL	Embedded SQLite
Target Environment	Self-Hosted Enterprise / Niksphere Cloud (Fully Managed)	Local Dev / Edge / Testing
Concurrent Write Performance	High (Row-level locking)	Moderate (WAL mode / file locking)
External Setup Needed	Yes (DB Server / Container)	No (Built-in file engine)
Backup Mechanism	pg_dump / Point-in-time recovery	Single file copy (.db)
Network Overhead	Low (TCP/IP socket)	Zero (In-process memory/disk)

Related Documentation

• Engine Deployment Models — Architectural overview of Self-Hosted (Docker / Standalone Binary) and Cloud (Fully Managed) deployment models.
• Layer System Concept — Core explanation of the "Everything is an App" layer principle and Base36 UIDs.
• Engine Configuration Reference — Reference for NIKSPHERE_ENGINE_DB_DRIVER and connection parameters.
• Engine Installation & Setup Guide — Quickstart guide for setting up Engine and databases.