Skip to main content
View as Markdown

Core Concepts

A Sovrium app is a single declarative configuration object. You describe what your application is — its data, pages, forms, authentication, automations — and Sovrium turns that description into a running, full-stack web application. There is no boilerplate, no framework scaffolding, and no build pipeline to wire up.

This page explains the anatomy of that configuration object so the rest of the App Schema reference makes sense.

The configuration object

Everything starts from one root object. Only name is required; every other section is optional and layered on as your app grows.

name: my-app # App identifier (required)
version: 1.0.0 # SemVer version
description: My application # One-line description

tables: [...] # Data models (49 field types)
pages: [...] # Server-rendered pages (~80 component types)
forms: [...] # Standalone forms that capture submissions
auth: { ... } # Authentication, roles, RBAC
theme: { ... } # Design tokens (colors, fonts, spacing, …)
languages: { ... } # Multi-language support ($t: syntax)

automations: [...] # Event-driven workflows (triggers + actions)
actions: [...] # Reusable action templates ($ref)
connections: [...] # External-service credentials
agents: [...] # AI agents acting under an auth role
buckets: [...] # Named file-storage containers

components: [...] # Reusable UI templates ($ref, $variable)
analytics: { ... } # Cookie-free, first-party analytics
env: { ... } # Declared automation env vars ($env.NAME)
scripts: { ... } # Global page scripts

The root sections

The configuration object groups its capabilities into the sections below. Each links to its dedicated reference.

Section Purpose Reference
name App identifier (npm naming rules). The only required property. App Metadata
version Semantic Versioning string. Feeds the immutable version ledger. App Metadata
description Single-line app description (max 2000 chars). App Metadata
tables Data models — the columns records can store across 49 field types. Tables Overview
pages Server-rendered pages built from a tree of component types, with SEO and i18n. Pages Overview
forms Standalone forms that capture submissions into a table or trigger an automation. Forms Overview
auth Authentication strategies, roles, RBAC, sessions, and two-factor. Auth Overview
theme Design tokens: colors, fonts, spacing, shadows, animations, breakpoints, radii. Theme
languages Multi-language support with $t: translation syntax and URL routing. Languages
automations Event-driven workflows: a trigger fires, a sequence of actions runs. Automations Overview
actions Reusable action templates referenced from automations via $ref. Automations Overview
connections Reusable credentials for external services (OAuth2, API key, basic, bearer). Automations Overview
agents AI agents that act on behalf of an auth role within a constrained tool set. AI Overview
buckets Named storage containers with per-bucket file limits and permissions. Buckets Overview
components Reusable UI templates inserted into pages via $ref with $variable substitution. Pages Overview
analytics First-party, cookie-free analytics. true for defaults or an object for options. Schema Overview
env Declared environment variables resolved at runtime, referenced as $env.NAME. Environment Variables
scripts Global scripts loaded on every page before page-level scripts. Pages Overview

Configuration-driven philosophy

Sovrium inverts the usual relationship between code and configuration. Instead of writing application code that occasionally reads a config file, you write configuration that Sovrium executes directly.

  • Declare, don't implement. You declare a relationship field; Sovrium creates the foreign key, the join queries, and the linked-record UI. You declare an automation; Sovrium wires the trigger, runs the actions, and records the run history.
  • One source of truth. The same object drives the database schema, the REST API, the MCP server, the rendered pages, and the admin dashboard. There is no second place where the shape of your data is restated.
  • Cross-section validation. Sections are validated together, not in isolation. A record automation that references a missing table, an attachment field pointing at an undeclared bucket, or a permission naming an unknown role are all rejected before the server starts — see sovrium validate.
  • Self-hostable, no lock-in. The config runs on your infrastructure against commodity storage (SQLite by default, PostgreSQL optional). Your data and your schema stay yours.

The layer model (at a glance)

Internally, Sovrium follows a four-layer architecture. You never write code in these layers for a config-only app, but the model explains why the schema is shaped the way it is.

Layer Responsibility What your config touches
Presentation Renders pages and serves the REST/MCP API. pages, forms, components, theme, scripts
Application Orchestrates workflows and use-cases. automations, actions, agents
Domain Pure business rules and the validated app schema itself. tables, auth, languages, validation
Infrastructure Talks to the database, file storage, and external APIs. connections, buckets, env

The dependency direction always flows inward (Presentation → Application → Domain ← Infrastructure), which is why declaring data and rules (tables, auth) is independent of how they are rendered (pages) or persisted (buckets).

Next steps