Core Concepts

Understanding the foundational architecture of Minerva will help you design better applications, robust access controls, and more maintainable automations.

1. The Blueprint

At the heart of the platform is the Blueprint. The Blueprint is a single, versioned JSON document (TBlueprintPayload) that defines everything about your organization:

Collections: Your data tables, columns, and relationships.
Teams & Permissions: RBAC mappings, conditions, approvals, and redaction.
Apps & Pages: Your custom front-end applications and layout structures.
Automations: Scheduled background jobs and web scrapers.

Checkpoint Storage & Rollbacks

Every time you make a change and merge a fork, Minerva creates a new Blueprint Checkpoint. The system keeps one canonical latest payload and stores JSON Patch history for prior checkpoints and forks.

This guarantees a complete audit trail and the ability to rollback to previous versions safely.

Blueprint Forks

Because the Blueprint dictates the physical database schema, you cannot make changes to it directly. Instead, all changes happen on a Blueprint Fork.

A Fork is a secure staging branch backed by a physical clone of your live PostgreSQL database.

Safe Testing: Try columns, permissions, or UI changes without affecting production.
Validation: Run compiler and configuration checks before merging.
Atomic Merges: Apply schema updates safely with snapshotting and migration generation.

2. Multi-tenant Isolation

Each organization in Minerva gets its own isolated PostgreSQL database. All database connections are managed through PgBouncer connection pooling so performance stays predictable as usage grows.

3. Architecture Overview

Collections define the structure.
Permissions map teams to collection routes and apply conditions.
Apps & Pages read and write through sandboxed codeblocks.
AI Commander works directly with the Blueprint to accelerate configuration work.

Once you grasp that everything flows through the Blueprint, you can build complex workflows much more quickly.