# Templates & Examples

The fastest way to learn Sovrium is to start from a working app. Sovrium ships a set of example configurations — each a complete, runnable project that composes real features (tables, auth, pages, theme, i18n, automations) into a single config tree. The same examples double as `sovrium init` templates, so you can scaffold any of them into a new directory and start iterating immediately.

Every example is a **directory** with an `app.yaml` entry point. Anything beyond the smallest starter splits its configuration across a `config/` subtree using [`$ref`](/en/docs/configuration-files#multi-file-configs-with-ref) — one file per collection entity, one file per singleton, scalars stay inline. This mirrors the structure `sovrium init` scaffolds for you.

## Available templates

| Template          | Description                                                                                                                                                                                                                     |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **hello-world**   | Minimal starter — one page, no collections. The default for `sovrium init`. Stays a single `app.yaml` to demonstrate when _not_ to pre-split.                                                                                   |
| **landing-page**  | Bilingual marketing site with i18n, a theme, reusable components, and the home page split out for size.                                                                                                                         |
| **crud-app**      | CRUD app with tables (contacts, companies), email/password auth, a theme, and dashboard + sign-in pages.                                                                                                                        |
| **api-only**      | Headless API mode with tables (projects, tasks) and auth — no pages. Demonstrates Sovrium as a backend.                                                                                                                         |
| **member-portal** | Public marketing pages plus an auth-gated portal area with role-gated sections. Magic-link + password auth.                                                                                                                     |
| **mcp-server**    | Headless MCP server exposing tables to an LLM client via per-entity `aiAccess` — no pages. See [MCP Integration](/en/docs/mcp-integration).                                                                                     |
| **blog**          | Blog with posts (rich-text), tags, authors, and an index plus a dynamic `/blog/:slug` detail route.                                                                                                                             |
| **docs-site**     | Documentation website showcasing the markdown-pages feature: real `.md` files under `content/docs/`, a `contentDir` collection, a frontmatter sidebar, prev/next chrome, a TOC, and Shiki-highlighted code. No tables, no auth. |

Several templates ship with a paired editor agent (a Claude Code subagent definition) that `sovrium init` installs into `.claude/agents/`. See [`sovrium agents`](/en/docs/cli#sovrium-agents-list) for managing agent templates directly.

## Scaffolding a project

`sovrium init` copies a template into a new (or current) directory. With no `--template`, the minimal `hello-world` starter is used.

```bash
# Default (hello-world, no paired agent)
sovrium init my-app

# Choose a template — also installs the paired editor agent
sovrium init my-app --template crud-app
sovrium init my-app --template landing-page
sovrium init my-app --template blog
sovrium init my-app --template member-portal

# Skip the paired agent install
sovrium init my-app --template crud-app --no-agent
```

Then run the scaffolded app:

```bash
sovrium start app.yaml          # Start the dev server
sovrium validate app.yaml       # Validate without starting
```

See the [CLI Reference](/en/docs/cli#sovrium-init) for all `init` flags.

## Anatomy of an example

A non-trivial example looks like this (abbreviated `crud-app` layout):

```
crud-app/
├── app.yaml                 # Entry point — references everything via $ref
├── config/
│   ├── auth.yaml            # Singleton: auth strategies, roles
│   ├── theme.yaml           # Singleton: design tokens
│   └── tables/
│       ├── companies.yaml   # One file per table
│       └── contacts.yaml
└── public/                  # Static assets (favicon, images)
```

The `app.yaml` entry point pulls each part together with `$ref`, keeping the top-level file small and each entity in its own file:

```yaml
name: crud-app

auth:
  $ref: ./config/auth.yaml

theme:
  $ref: ./config/theme.yaml

tables:
  - $ref: ./config/tables/companies.yaml
  - $ref: ./config/tables/contacts.yaml

pages:
  - $ref: ./config/pages/dashboard.yaml
  - $ref: ./config/pages/sign-in.yaml
```

`$ref` resolution happens **before** validation: any object containing exactly one key — `$ref` whose value is a relative path — is replaced with the parsed contents of that file. A `$ref` may itself contain further `$ref`s, so configs nest to any depth. The single-file and multi-file forms are interchangeable; pick whichever keeps the project readable.

:::callout
**When to split.** Keep a config in one file while it is small (like `hello-world`). Split with `$ref` once a section grows large enough to deserve its own file — typically once you have more than one table, page, or a substantial theme. The full mechanics live in [Configuration Files → Multi-file configs](/en/docs/configuration-files#multi-file-configs-with-ref).
:::

## Learning path

A practical order for working through the examples:

1. **hello-world** — understand the minimal shape of a config and the `pages` array.
2. **landing-page** — add a theme, reusable components, and i18n with `$t:` translation keys.
3. **crud-app** — introduce tables, auth, and data-bound pages (forms + data tables).
4. **api-only** / **mcp-server** — run Sovrium headless: as a REST backend or an LLM-facing MCP server.
5. **blog** / **member-portal** / **docs-site** — combine dynamic routes, role-gated areas, and markdown content.

## Related Pages

- [Quick Start](/en/docs/quick-start) — zero to running app via YAML + CLI or TypeScript + Bun.
- [Configuration Files](/en/docs/configuration-files) — YAML, JSON, TypeScript, and `$ref` multi-file composition.
- [CLI Reference](/en/docs/cli) — `sovrium init`, `sovrium agents`, and the full command surface.
- [MCP Integration](/en/docs/mcp-integration) — the headless MCP-server template explained.