The ecosystem map¶

The estate is a set of git repositories, the programs that read and write them, and the machines those programs run on. This page places each of them and says whether it exists today. Every concept named here has its own page; this one only connects them.

The corpora¶

A corpus is a git repository the estate reads or writes. Git is the system of record: every database the programs build is a view that can be dropped and rebuilt from corpus commits. Each corpus has a kind, and the repositories keep their Polish repozytorium-* names.

Kind	Holds	Dev repository	Production repository
`lore`	the human Markdown narrators write: characters, NPCs, groups, locations, maps, items, sessions	`repozytorium-fabularne-prodkopia`, a mirror of production nothing here writes back to	`repozytorium-fabularne`, the campaign's record
`metadata`	what the tools know about each lore page: ids, aliases, tag histories, consent policies, rules; one YAML per lore page	`repozytorium-metadanych-prodkopia`, created and empty	created with the production site
`moderation`	the moderators' roster, the regulations and the sanction ledger; encrypted and never shipped off its site	`repozytorium-moderatorskie-dev`	created with the production site
`transcripts`	the archived chat of every session, one file per transcript	`repozytorium-transkryptow-dev`	created with the production site
`annotations`	labelled samples over corpus spans, the input of training	`repozytorium-adnotacji-dev`	created with the production site
`works`	external and player-written works, one directory per source with its owner's consent	`repozytorium-dziel-dev`	created with the production site

A seventh kind, events, is ruled and not created: repozytorium-zdarzen will carry authored facts as signed events for instances that share no database. The lore repository holds Markdown and nothing else; anything a tool writes about a page goes to the metadata corpus.

The programs¶

Repository	What it is	Today
Nerthus.Platform	one package, one image, one command line: fetch, derive, API, dashboard host, Discord bot, jobs, the language pipeline	being built; runs in CI and on laptops, no site runs it
Nerthus.Config	configuration management: declarations, observed state, plans, drift, host cookbooks, hardening	being built; applied from a laptop
Nerthus.Infra	Config's declarations and state, and no code	in use
Nerthus.Dashboard	the dashboard, rebuilt against Platform's API and served by it	ruled; the repository does not exist yet
Nerthus.Texts	the catalogue of every string the estate shows, in Polish and English	ruled; the repository does not exist yet
the game add-on	a browser add-on that brings a live scene into the game, speaking Platform's bridge contract	ruled; not started
Nerthus.Docs	this site	in use

Nerthus.Core, Nerthus.Core.Dashboard, Nerthus.Lang and Nerthus.Lang.Annotations are what runs today, and the estate replaces them; they are described in Nerthus.Core (until cutover).

Platform: sites, hosts, instances, roles¶

A site is one Postgres and the instances that share it. A host is a machine, and a site may span several hosts over a WireGuard mesh. An instance is one nerthus serve process, and it runs one or more roles:

Role	Does
`fetch`	keeps a clone of every corpus converged with its remote, on a webhook or a tick
`load`	parses corpus commits into the `derived` schema
`read`	serves the API and the dashboard
`write`	the one writer: commits approved changes to a corpus
`worker`	runs queued jobs: annotation, export, training, verification
`bot`	the Discord bot
`migrate`	applies schema migrations once per rollout

live and bridge are reserved for the game add-on. The database has two schemas: derived, rebuilt from corpus commits by nerthus derive, and authored, the facts only the site holds (pending changes, jobs, grants, rulings, audit), backed up nightly. An instance on someone's own machine is a client: a full local site that pulls from a shared one and never writes for it.

A site has an environment, prod, dev or staging. No production site exists. How to configure an instance is Configure a Platform instance; what the database holds is The database.

Config: declarations and state¶

Nerthus.Config reads three things and compares them: the declaration in Nerthus.Infra (inventory/, sites/<name>/, pins/, hardening/), the state it last observed or made (state/, written only by apply, import and drift), and what the providers (Cloudflare, GitLab, R2) and the hosts report live. The difference is a plan; a plan run on a schedule is drift, and drift is reported, never fixed. Hosts converge themselves: an agent on each pulls Nerthus.Infra and applies its role's cookbook. Read a plan is where to start.

How they connect¶

flowchart LR
    corpora["the corpora<br/>(GitLab)"]
    subgraph site["a Platform site"]
        fetch["fetch"] --> pg[("Postgres<br/>derived + authored")]
        pg --> read["read: API, dashboard"]
        pg --> write["write"]
        pg --> bot["bot"]
    end
    corpora --> fetch
    write -->|"approved changes"| corpora
    bot --> discord["Discord"]
    read --> people["narrators, players, Council"]
    texts["Nerthus.Texts"] -.->|"strings"| read
    addon["game add-on"] <-.->|"bridge contract"| read
    infra["Nerthus.Infra<br/>(declarations, state)"] --> config["nerthus-config"]
    config -->|"plan, apply"| providers["Cloudflare, GitLab, R2"]
    infra -->|"pulled by the agent"| hosts["hosts"]
    hosts --- site

Public addresses¶

Address	Serves
`cognition.nerthus.pl`	this site
one origin per site	the site's API and dashboard, behind a Cloudflare tunnel

Core's own addresses are listed in Publish the API.