Concepts
Architecture
Learn how three Workers and Cloudflare data services handle requests, federation, and real-time events.
Three Workers
| Component | Responsibility |
|---|---|
| siliconbeest | Nuxt 4 SSR and Vue UI, unified Hono API and ActivityPub routing, OAuth, Fedify, admin API, assets, and StreamingDO |
| queue-consumer | Federation, internal, and federation-DLQ consumption; fan-out, media, notifications, Web Push, remote fetches, and DLQ parking |
| email-sender | Dedicated email queue consumption with SMTP settings read from D1 |
The main Worker responds to users quickly and sends slow or retryable work to queues. Consumers retry idempotently, and operators inspect final failures in the DLQ.
Data services
| Service | What it stores |
|---|---|
| D1 | Accounts, posts, relationships, settings, and transactional data |
| R2 | Uploaded media and generated thumbnails |
| KV | Caches, sessions, and Fedify key-value state |
| Queues | Asynchronous federation, internal job, and email messages |
| Durable Objects | WebSocket connections and real-time timeline streaming |
The lifecycle of a post
- 1 Validate the API request
Check OAuth scopes, account state, visibility, and input.
- 2 Write to D1
Persist the post and local timeline state within a transaction boundary.
- 3 Fan out internally
Enqueue follower timeline and notification work.
- 4 Deliver through federation
Fedify creates the ActivityPub object and sends signed requests to target inboxes.
- 5 Update in real time
The Durable Object sends the new event to connected clients.
Design boundaries
- Mastodon API compatibility is a contract with the client ecosystem.
- Fedify owns the WebFinger, HTTP Signature, NodeInfo, and ActivityPub protocol boundaries.
- Types, permissions, and cryptographic utilities in packages/shared are contracts between producers and consumers.
- Asynchronous messages may be delivered more than once, so consumers must remain idempotent.
- Remote content is untrusted and must pass HTML sanitization and SSRF defenses.
Want to improve this documentation?Every contribution helps.
Contribute on GitHub ↗