Mastodon Project Structure

The decentralized social network server. A massive Ruby on Rails application that uses Node.js for streaming and React for the frontend.

Updated 2025-12-30

#mastodon #ruby #rails #react #nodejs #activitypub #federation

PNG PDF

Project Directory

mastodon/

app/

Main Rails Application

models/

ActiveRecord models

account.rb

status.rb

services/

Business logic & Federation

activitypub/

post_status_service.rb

process_mentions_service.rb

controllers/

API & Web Controllers

api/

javascript/

React Frontend

mastodon/

Main SPA source

packs/

Webpack entry points

lib/

activitypub/

Protocol implementation

streaming/

Node.js WebSocket Server

index.js

package.json

config/

Configuration

routes.rb

URL routing

sidekiq.yml

Job queue config

spec/

RSpec Tests

Gemfile

Ruby dependencies

package.json

JS dependencies

docker-compose.yml

Dev infrastructure

Repository Info

Repository-mastodon/mastodon
Stars-45k+
License-AGPL-3.0
Last Analyzed-December 2025

Tech Stack

Backend-Ruby on Rails
Frontend-React + Redux
Streaming-Node.js (WebSockets)
Database-PostgreSQL
Queue-Sidekiq (Redis)
Search-ElasticSearch

Architecture Notes

Mastodon is a monolithic Rails application for the most part. However, it offloads real-time updates (streaming timeline) to a separate Node.js service located in the streaming/ directory. This hybrid approach allows it to leverage the rich Rails ecosystem for business logic while using Node's event loop for high-concurrency connections.

Key Directories

app/services/-This is where the magic happens. Mastodon relies heavily on Service Objects to handle complex actions like PostStatusService (posting a toot) or ProcessMentionsService.
app/lib/activitypub/-The implementation of the ActivityPub protocol. This code handles the serialization and deserialization of JSON-LD messages that allow Mastodon to talk to other servers.
app/javascript/mastodon/-The React frontend. It's a Single Page Application (SPA) that communicates with the Rails backend via the REST API.

Why This Structure?

Mastodon is the reference implementation for the ActivityPub protocol. Its codebase is a great resource for understanding how to build federated social networks and how to structure a large-scale Rails application with a modern frontend.

Share this template