Project layout

A project is one directory. The engine reads it from the current directory, or from the directory --project names; --config changes the configuration directory’s name from config. Everything in it is text you commit to version control, except the few local directories listed under What not to commit.

The whole treeCopy Anchor Link

Only config/engine.yaml, config/locales.yaml, one site directory and the templates its routes need are required. Every other file is optional: leave it out and the engine uses its defaults.

What reads whatCopy Anchor Link

The engine reads config/ and templates/ at start and on every check; schema apply copies the schema into the database, seed apply loads seed/ into it once, and from then on content lives in the database:

flowchart LR
  subgraph project["The project directory"]
    config["config/<br/>engine, locales, sites, schema, access"]
    templates["templates/"]
    public["public/"]
    seed["seed/"]
  end
  config -->|schema apply| db[("PostgreSQL<br/>schema copy and content")]
  seed -->|seed apply, once| db
  config --> engine["The engine<br/>serve, dev up, check"]
  templates --> engine
  public -->|served as is| engine
  db --> engine
  engine --> site["Public sites, admin, APIs"]
  config -->|guide| agents["AGENTS.md and skills"]

Who writes whatCopy Anchor Link

You write every file in the project. The tooling writes into your files in three cases only, each one a command you run on purpose, never the running engine:

• engine-dmo check --fix, the engine-dmo dev verbs and engine-dmo dev up write the id: of each configuration element that has none, and the verbs make the edit you asked for. They keep your comments and layout. See Stable ids.
• engine-dmo init and engine-dmo new write new files.
• engine-dmo config schema --write and init write the editor schemas under .meridian/schema/ and the editor settings that map them.

Content (documents, media, organisations, users) lives in the database, not in the project. The project’s seed/ holds content to load into a database, which is a one-way copy.

config/Copy Anchor Link

Configuration is YAML. Every file is validated as a whole by engine-dmo check, which reports every problem at once with its file, line and column. Secrets never appear as values: a secret key must be a bare ${VAR} reference to an environment variable. Configuration reference lists every key of every file.

Install-wide filesCopy Anchor Link

A file that belongs to a module the binary does not compile is an error at the file, naming the module. On engine-cms, config/memberships.yaml gives:

config/memberships.yaml:1:1: memberships.yaml belongs to the memberships module, which this bundle (cms) does not compile
    1 | tiers:
      | ^
      = use a bundle that compiles memberships, such as the DMO platform's bin/engine-dmo, or remove it
      = error code MRD-1006

A module’s section of engine.yaml (such as portal:) is refused the same way.

config/sites/Copy Anchor Link

One directory per site; the directory name is the site’s key. An install with one site still has config/sites/<key>/.

Sites, locales and routes explains how site.yaml and routes.yaml work together.

templates/Copy Anchor Link

Pongo2 templates (a Django-like syntax), autoescaped. templates/_shared/ holds what every site uses, and templates/<site>/ holds a site’s overrides. A site resolves each template along its chain of roots, most specific first: [<site>, _shared] unless templates.roots in site.yaml says otherwise. Every root a site names must exist as a directory.

engine-dmo check refuses a routed type with no template on a site’s chain, an index route without its index.html, and any template that does not compile, uses an unknown variable root or an unknown filter. Templates and Multisite templates cover the rest.

public/Copy Anchor Link

Static files served as they are, at the same path. A request resolves along the site’s chain: public/<site>/, then public/_shared/, then public/. Built and versioned files (under public/build/) are cached for a year, anything else for an hour; the build’s manifest is never served. public.mounts in engine.yaml serves a directory outside public/ at a path prefix.

seed/Copy Anchor Link

Content to load into a database with engine-dmo seed apply. It goes through the same validation and revision history as an editor’s save. engine-dmo seed verify checks it against the schema without a database, and is what CI runs. It needs every ${VAR} in the configuration set (a placeholder is enough), and it checks types, fields and locales, not values: a value a field would refuse fails only in seed apply.

A starter seed document:

# seed/documents/page/home.yaml
locales:
  en:
    title: Welcome
    slug: home
publish: [en]

Frontend build filesCopy Anchor Link

The starter has no frontend build: no package.json, src/ or vite.config.js, and its CSS and JavaScript, if any, go in public/. A project with its own CSS and JavaScript build keeps its sources in src/ (entries in src/entries/, one per site by default: src/entries/<site>.js), with package.json and vite.config.js at the project root. The vite extension, named in engine.yaml as extensions: [vite], runs Vite’s dev server beside engine-dmo serve --dev, and engine-dmo build runs the production build and then check. Output goes to public/build/. The frontend build covers it.

tests/Copy Anchor Link

tests/templates/*.test.yaml are template tests: pages to render through the real pipeline against the seeded database, each with what it must contain. engine-dmo template test runs them. Testing templates covers the format.

Agent and editor filesCopy Anchor Link

Regenerate AGENTS.md by hand with engine-dmo guide --out AGENTS.md, the project skill with engine-dmo guide --skill --out .claude/skills/meridian-project/SKILL.md, and the meridian skill with engine-dmo docs skill --out .claude/skills/meridian/SKILL.md. init --agents=false writes none of them.

The starter’s README.md points at this page. Its hints, and the engine’s, name handbook pages or commands. Earlier builds, including the 0.8.0 release images, also cite internal design documents in some hints, such as (27-frontend-toolkit.md) or (ADR-0019); those are not part of the handbook and not published, so search the handbook for the topic instead.

What not to commitCopy Anchor Link

The starter’s .gitignore:

/storage/
/node_modules/
/public/build/
/.meridian/
.env