Skip to content
Omicron

Development

Backend guide

Working inside apps/backend — routes, services, repositories, the queue, and federation.

Hono, Fedify, Drizzle, PostgreSQL, Better Auth. Deno runs it in development and in the production container, but every command you run goes through pnpm, and the code stays runtime-agnostic: it must run unchanged on Node, Deno, and Bun.

Directory map

Directory Responsibility
src/routes/ HTTP only — parse, call a service, serialize
src/services/ Business logic — no HTTP, no SQL
src/db/ Drizzle schema, migrations, and repositories
src/federation/ ActivityPub, loaded only when federation is on
src/auth/ Better Auth setup (accounts, sessions, passkeys)
src/queue/ The queue.add(name, payload) abstraction and job handlers
src/lib/ Small shared helpers (HTTP errors, rate limiting, body caps)

Adding an endpoint

The whole loop, in order:

  1. Repository — add a query function in src/db/repositories/. This is the only place SQL is written.
  2. Service — add the business logic in src/services/, calling the repository. No Context, no request objects, no HTTP status codes.
  3. Route — add the handler in src/routes/, parse and validate input, call the service, serialize the result.
  4. Mount — register the route file in src/routes/index.ts if it is a new group.
// routes/posts.ts — thin by design
postRoutes.get("/:id", async (c) => {
  const post = await postsService.getById(c.req.param("id"), c.get("user"));
  return c.json(serializePost(post));
});

Route composition

src/routes/index.ts mounts every group under /api:

apiRoutes.route("/client", clientRoutes);
apiRoutes.route("/me", meRoutes);
apiRoutes.route("/posts", postRoutes);
// …

src/app.ts composes the whole application: the logger, the error handler, client CORS and OAuth routes, optional federation mounting, health routes, Better Auth, session middleware, the rate limiters, and finally the API.

Middleware order

It matters, and it is deliberate:

  1. logger() and onError — always outermost.
  2. Client CORS for bearer-token clients, then the OAuth routes (/.well-known/oauth-authorization-server, /oauth/*, /api/v1/*, /api/oauth/*).
  3. Federation paths (/.well-known/, /users/, /inbox, /nodeinfo) are intercepted before app routes when enabled.
  4. Health routes (/healthz, /version).
  5. Better Auth on /api/auth/*, with its own session handling and rate limits, ahead of the /api/* middleware.
  6. sessionMiddleware on /api/* — so later layers can key by user.
  7. The write throttle on /api/*, skipped for GET/HEAD/OPTIONS, then the upload throttle on the three endpoints that store media.
  8. The API routes themselves.

Rate limiting

const apiWriteLimiter = rateLimit({
  name: "api-write",
  windowMs: 60_000,
  max: config.RL_API_WRITE_MAX,
  key: (c) => {
    const user = c.get("user");
    return user ? `u:${user.id}` : `ip:${clientIp(c)}`;
  },
});

Endpoint-specific limiters (auth, registration, inbox) layer stricter caps on top of this backstop. Counters are per-process without Redis and shared with it.

The queue

queue.add("federate_post", { postId });

Handlers are registered in src/queue/handlers.ts via registerJobHandlers(), called once while building the app. Adding a job type means adding a handler there and calling queue.add from a service — never from a route.

Federation

src/federation/ is imported dynamically, only when federation is running:

File Role
mod.ts Fedify setup — actor, followers, outbox, inbox listeners, object dispatchers
actor.ts Building actor documents
article.ts Mapping posts to ActivityPub objects
note.ts Federated replies: local comments ↔ ActivityPub Notes
deliver.ts, outbound.ts Sending activities
remote.ts Resolving and caching remote actors
outboundGuard.ts, ssrf.ts Guards for remote fetches that anonymous readers can trigger
nodeinfo.ts The NodeInfo document
attribution.ts Splicing Mastodon’s attributionDomains into the actor doc
lists.ts Public reading lists as addressable objects

Health and version

healthRoutes.get("/healthz", (c) => c.json({ status: "ok" }));
healthRoutes.get("/version", …);   // name, version, federation flag

APP_VERSION lives in src/version.ts, is logged on boot, and is bumped per release.

Checks

cd apps/backend
pnpm fmt            # format first
pnpm check          # tsc, oxfmt, oxlint, and the unit tests

See Contributing for the integration suite.

Found a mistake?Edit this page on GitHub.