Administration

Deployment & security

One process, one database, one instance — a deliberately boring shape with sharp edges you should know about, and a security model where deny-by-default is the default that's actually enforced.

The deployment shape

The web server, the background scheduler and the dev-session subprocesses all live in one process. That is a deliberate choice: there is no queue service, no worker fleet and no cron host to operate — and it is a real constraint: serverless hosting is out, because mail sync, the run queue, the reapers and every sweep stop when the process does.

Process

Next.js app with the scheduler started in-process; docker compose runs it as one container.

Database

One PostgreSQL database; migrations run at boot.

Disk

Durable disk required — dev sessions keep git checkouts and engine state on it.

Port

3001 by default.

Why exactly one instance

Do not run two replicas

Much of the appliance assumes one instance: rate-limit counters, dev-session approval maps and the live event bus are per-process. Two replicas against one database will double-fire schedules and strand approvals. Scale the box, not the count.

Access control

Deny by default — every route requires a session unless it is explicitly named public, so a new section is protected the day it exists.

Live re-checks — every request re-reads the user row, so a disabled account loses access on its next request, not at token expiry.

Per-section access — the employee roster grants access per section, so finance, mail and the fleet can have different audiences.

Sign-in — password, SSO, and passkeys (Face ID / Touch ID).

Secrets & the audit trail

Mail credentials, AI provider keys and connection secrets are encrypted with TALON_CONTROL_ENCRYPTION_KEY before they touch the database. Every commercially meaningful action lands in the append-only event log through a single writer — the audit trail is a property of the system, not a logging convention.

Backups

Two things hold state: the Postgres database and the dev-session disk. Back up the database like the book of record it is; treat the dev-session checkouts as reproducible (they are git clones) unless you keep long-running session state you care about.

The encryption key is the third thing, and it is not in the backup — see Backups for the nightly dump, the off-box copy and the restore drill that turns all of this from a hypothesis into a backup.