The roadmap

1. Be findable

One createFederation(...) call wired into your web framework, an actor dispatcher returning a Person from your user table, a key-pairs dispatcher returning stored JWKs.

• Fedify carries — WebFinger, content negotiation, the actor JSON-LD (@context, publicKey, assertionMethod), NodeInfo routing, key generation for both RSA and Ed25519.
• You write — a database lookup, and somewhere to keep two JWKs per user.
• Checkpoint — search @you@your.domain from Mastodon and your profile appears. fedify lookup @you@your.domain shows your actor.
• Docs: tutorial/basics · manual/actor

2. Be followable

Inbox listeners — your first .on(Follow, …).

• Fedify carries — signature verification before your handler runs, typed dispatch, signing and delivering your Accept.
• You write — persist the follower, send the Accept, and the policy call: auto-accept or hold for approval (manuallyApprovesFollowers is only a label — the decision is your code).
• Checkpoint — follow yourself from a Mastodon account; it flips from "requested" to "following", and your followers collection counts one.
• Docs: manual/inbox · manual/collections

3. Speak

Your first outbound Create(Note).

• Fedify carries — fan-out to every follower in one sendActivity call, shared-inbox dedup, retries with backoff, delivery ordering (orderingKey), the outbox collection envelope.
• You write — the post model, its HTML, mentions and hashtags as tags.
• Checkpoint — you post, and it lands on your follower's Mastodon timeline. fedify inbox gives you a throwaway follower to send at while you iterate.
• Docs: manual/send · tutorial/microblog

4. Listen — the big one

Receiving Create from the network and mirroring it: remote actors and posts as rows in your database, timelines, notifications.

• Fedify carries — typed objects out of any JSON shape, document loaders, cross-origin verification of embedded objects.
• You write — the mirror: persistActor, persistPost, reply threading, timeline fan-in, notifications. This is deliberately not fedify's job, and it is the single largest bucket of federation code in every app we read. Budget most of your time here.
• Checkpoint — a Mastodon reply to your post appears in your app, threaded under the right post, and notifies the right user.
• Docs: manual/vocab — and read persistPost in Hackers' Pub before designing yours.

5. Interact

The conversational verbs, in both directions: Like, Announce, Update, Delete, Undo.

• Fedify carries — all the vocabulary and the delivery; idempotency cache on the receiving side.
• You write — state transitions with upsert-safe writes, undoing (Undo(Like) really removes the like), deletes with judgment — a Delete(Actor) that erases moderation evidence is a decision, not a default.
• Checkpoint — like and boost round-trip both ways; edit a post and the Update shows on Mastodon; delete it and it's gone there too.
• Docs: manual/pragmatics — how each verb actually renders on Mastodon.

6. Grow up

From "it federates" to "it runs".

• Fedify carries — pluggable message queues, retry policy, circuit breakers, permanent-failure reporting, authorized fetch and the instance actor, OpenTelemetry tracing.
• You write — the worker-process split (manuallyStartQueue + startQueue), failure cleanup (prune on 404, cascade on 410 Gone), moderation and block checks, monitoring dashboards.
• Checkpoint — the pre-launch checklist in manual/deploy, top to bottom.
• Docs: manual/mq · manual/access-control · manual/opentelemetry

The panorama — how far the road goes

Everything above is a microblog. The same six stages, with fedify's vocabulary and the ecosystem knowledge already in the box, extend to:

• Long-form writing — Article with multi-language content and markdown Source; Hackers' Pub federates full blog posts.
• Polls — Question, votes as replies, Update when they close.
• Emoji reactions — EmojiReact and custom Emoji, the Misskey lineage; Hollo speaks both.
• Quote posts — FEP-044f QuoteRequest / QuoteAuthorization with interaction policies — still the frontier; see Keep in mind.
• Account migration — Move, follower forwarding, aliases; both reference codebases handle it.
• Reports — Flag across servers, with Mastodon's expectations encoded.
• Relays — subscribe and serve; fedify relay in the CLI and manual/relay.
• Any runtime shape — Deno, Node, Bun; a dozen web frameworks; KV and queue adapters down to serverless.

And the honest edge of the view: persistence, timelines, notifications, media storage, client apps and their APIs are never fedify's — that's your application. The line is drawn precisely in what stays yours.

FEPs along the way

FEPs — Fediverse Enhancement Proposals — are the fediverse's shared notes on how things are actually done, one step less formal than a spec. Fedify implements a good stack of them; its FEDERATION.md is the authoritative list. The ones you'll actually meet on this road:

• Stage 1, be findable — FEP-521a (how an actor publishes its public keys) and FEP-8b32 (Object Integrity Proofs — the Ed25519 document signatures) are why fedify has you keep two key pairs. FEP-f1d5 is NodeInfo.
• Stage 2, be followable — FEP-8fcf keeps follower collections in sync across servers; FEP-5feb is the search-indexing consent flag respectful servers check before indexing your users.
• Stage 4, listen — FEP-fe34 is the origin-based security model behind the cross-origin re-fetch default you met in Keep in mind.
• The panorama — emoji reactions are FEP-c0e0; quote posts are FEP-e232 (object links) plus FEP-044f (consent-respecting quotes); relays speak FEP-ae0c; account export rides FEP-9091.
• And one for you — FEP-67ff simply says: document your federation behavior in a FEDERATION.md. Fedify keeps one; when your server grows up, keep one too.

Back to Fedify · Keep in mind