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:
- Repository — add a query function in
src/db/repositories/. This is the only place SQL is written. - Service — add the business logic in
src/services/, calling the repository. NoContext, no request objects, no HTTP status codes. - Route — add the handler in
src/routes/, parse and validate input, call the service, serialize the result. - Mount — register the route file in
src/routes/index.tsif 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:
logger()andonError— always outermost.- Client CORS for bearer-token clients, then the OAuth routes
(
/.well-known/oauth-authorization-server,/oauth/*,/api/v1/*,/api/oauth/*). - Federation paths (
/.well-known/,/users/,/inbox,/nodeinfo) are intercepted before app routes when enabled. - Health routes (
/healthz,/version). - Better Auth on
/api/auth/*, with its own session handling and rate limits, ahead of the/api/*middleware. sessionMiddlewareon/api/*— so later layers can key by user.- The write throttle on
/api/*, skipped forGET/HEAD/OPTIONS, then the upload throttle on the three endpoints that store media. - 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.