Architecture
How Invarn is put together, and why.
Layers
Entry points (the gateway's event listener, interactions/ in either process, and the http
process's handlers/ and jobs/) call service/, one
function per action, whichever way it's asked: a slash command, a button and a dashboard request run
the same code. Services use store/ (queries generated by sqlc) and discord/, the only package
that talks to Discord's API.
Previews
Every change to Discord goes through discord.Actions. It has two implementations: the live client,
and a recorder that writes one readable line per call instead. A preview runs the same service
function inside a database transaction that's rolled back, with the recorder; the lines are what the
dashboard shows before you apply.
Scaling
Invarn runs as two processes that scale apart and meet only in Postgres. Gateway processes each own some of Discord's gateway shards, and each server's events go to one worker in order, so in-memory state needs no locks. HTTP processes answer the dashboard and run the jobs; they hold no shards, and tell a gateway process to reload through Postgres when that's needed. Discord's interactions go to the HTTP processes when the application has an Interactions Endpoint URL, and over the gateway when it doesn't. Discord's data (roles, channels, expressions) lives in disgo's cache, filled from the gateway or over REST.
The journal
Every change is an action, written once: who made it, and enough to do it again and to take it back. Changes to members that Invarn makes are written as it makes them; the gateway writes everything else, after Discord's audit log says who made it (changes wait up to five seconds for that), and attributes Invarn's own channel, role and emoji changes to whoever asked, from the audit reason. Undo does each entry's inverse in a safe order, recreating what was deleted and remapping IDs for the entries that follow.
Moderation is a case however it was done: a ban, kick or timeout someone makes in Discord's own menus opens one too, and an unban or a lifted timeout ends the cases it lifts, wherever it came from. Lifting a case lets the member go only when no other case still holds them.
Packs
Each server converges on its packs in a job: the desired items in priority order fill the slots left by expressions in no pack. The database changes before Discord does, so the events that come back match it and nothing loops. A per-server counter makes sure a change made while a job runs is never missed.