The Architecture of Mastodon

Dec 20, 2022

I was curious about how Mastodon is actually implemented. A high-level overview:

  • Web app is written in Ruby on Rails
  • Persistence layer is PostgreSQL
  • File storage/mailer is S3/SMTP agnostic
  • Redis for precomputed social feed cache and worker queue
  • Sidekiq for background processing
  • A node handler for streaming (notifications, new posts, etc.)

Looking at the code, it's definitely an interesting look into the early 2010s style of development. There's nothing wrong with it, and in fact, it's extremely effective at shipping an actual product (because the tech stack rarely is more important than distribution).

But it got me thinking about how incompatible the architecture already is with the shift to cloud and serverless. As a result, Mastodon is a bit tough to self-host. It would be hard to take advantage of the latest trends in infrastructure:

  • Modern frontend components – Rails is stuck in the world of templates compared to the declarative components that most developers use today with React. More so than the developer productivity that you get from React, Rails templates limit the amount of code that you can reuse.
  • Scaling – While Mastodon can be easily scaled in a few dimensions (e.g., Redis and PostgreSQL), the Rails monolith is harder to scale. Usually, not an issue, but when a critical path is being able to run an instance yourself, it can be difficult (and expensive) for operators. It would be difficult to transition parts of Mastodon to scale-to-zero infrastructure.
  • Serving content at the edge – While modern frontend frameworks are edge-native, it's hard to split out functionality to serve at the edge for a Rails app. You can put static assets behind a CDN, but most pages are rendered by templates in the core RoR process.
  • Developer workflow – It's hard to have cloud-native development in a monolith. Anything outside the happy path is difficult. Containerization, Kubernetes, and even the modern frontend compilation stack are difficult to work with in Rails.

This isn't meant to be a criticism of Mastodon – software that ships are better than software that doesn't. And Mastodon was originally developed in 2016. Many of the technologies I listed will likely be out of date in the next few years. It's more an observation of how quickly things change, even infrastructure. And how there are always opportunities to rewrite and optimize old tech with new infra.


Another example of this is Ghost, the blog software that I currently use to send out the newsletter. It's a heavy-weight process to run yourself – another Express monolith. I've already migrated the front end to NextJS; all that is left is to send the mail out with AWS SES (eventually!). There's probably some room in the market for a minimal blog/newsletter that is completely serverless and uses a simple SQLite backend (Ghost stopped supporting SQLite in production, a backward step, in my opinion).