Architecture

Mellow is a single Go binary. Everything runs in one process: the Discord gateway connection, background jobs, and the HTTP API.

Packages

cmd/mellow           entry point: load config, migrate, wire everything, run
internal/
  config             environment parsing
  logger             slog setup
  crypto             AES-256-GCM per-field encryption (wire-compatible with the old JS scheme)
  db
    migrations        golang-migrate SQL files (embedded)
    queries           sqlc source SQL
    gen               sqlc-generated query code (committed)
    store.go          wraps generated queries, applies encryption on read/write
  ai                 Anthropic client, prompts, crisis screening, coping, history, fun, meme, wordgame
  discord            disgo client, command registry, routers, embeds, message handlers
  server             chi HTTP API (health, stats, testimonials, chat, feedback) + OpenAPI/Scalar
  services
    syslog            SystemLog writer + fan-out to a Discord log channel
    reminder          check-in reminder ticker
    presence          status rotation + external status posting
    statusposter      posts bot status to the website
    omniplexsync      Omniplex integration sync
  github             release lookups for /version and update checks
  changelog          reads PATCHNOTES.md for the /changelog command
  omniplex           Omniplex API client

Startup sequence

1. Load .env and the environment.
2. Run embedded database migrations. Exit here if MELLOW_MIGRATE_ONLY is set.
3. Open a pgxpool and build the Store.
4. Build the AI client from the Mellow config row.
5. Build the disgo client with cache for guilds, channels, and roles only; intents Guilds | GuildMessages | DirectMessages.
6. Register global commands (bulk overwrite) and owner commands to PRIVATE_GUILD_ID.
7. Open the shard manager (auto-scaling).
8. Start background services and the HTTP API.
9. Block until SIGINT/SIGTERM, then shut down gracefully.

Discord layer

• No privileged intents. Message content is available only for DMs and messages that mention or reply to the bot.
• Commands are described by a Command struct (name, options, category, cooldown, required permissions, Private/OwnerOnly, Run). The registry builds disgo command payloads from these.
• Routing applies guild-only checks, permission checks, owner checks, per-user cooldowns, lazy user/guild upsert, command logging, and a generic error reply.
• Crisis screening is a two-stage local-then-constrained-AI classifier; see
  Crisis Safety

  Crisis Safety

  How Mellow screens for crisis and why it responds the way it does.

  .

Data layer

• sqlc generates typed query methods from hand-written SQL. No ORM.
• Store is the only thing the rest of the app talks to; it encrypts sensitive fields on write and decrypts on read.
• Migrations are embedded and forward-only in practice (down files exist for local use).

Licence

AGPL-3.0. Copyright Pixelated (CodeMeAPixel), https://codemeapixel.dev. See LICENSE and NOTICE in the repository.