A federated social network — think Mastodon or Diaspora — where separate servers actually talk to each other.
Every social platform is a walled garden. Your account on one service can't talk to an account on another — which is insane when you think about it, because email figured this out decades ago.
Social Distribution fixes that. It's a social network where users on completely different servers can follow each other, post, like, and comment across instances — the same way you@gmail.com can email me@outlook.com without anyone caring. Under the hood it's a simplified ActivityPub-compatible protocol, built from scratch.
The short version:
- 🔗 Real federation — follow and interact with users on other servers
- ⚡ Realtime — live updates, notifications, federated inbox delivery
- 🔒 Privacy controls — per-post visibility (public / friends-only / unlisted)
- 🎨 Glassmorphism UI — dark/light, responsive, animated
- 📱 Works everywhere — mobile-first
Running locally, you'll hit:
| Frontend | Backend API | Admin |
|---|---|---|
| React App | REST API | Django Admin |
Backend — Django doing the heavy lifting, DRF for the API, Postgres for storage.
Django 5.2.1 Django REST Framework PostgreSQL / SQLite
Session Auth + CSRF ActivityPub-compatible Federation-ready
Federated inbox Binary image storage
Django==5.2.1
djangorestframework==3.16.0
django-cors-headers==4.7.0
django-allauth==65.9.0
pillow==11.2.1
psycopg2-binary==2.9.10
gunicorn==21.2.0
Frontend — React 19 + TS + Vite. Tailwind for styling, Framer Motion for the animations, plain Context for state (no Redux, didn't need it).
React 19.1.0 TypeScript 5.8.3 Vite 6.3.5
Tailwind CSS 4.1.8 Framer Motion Liquid-glass UI
Mobile-first Realtime updates Context state
react==19.1.0
typescript==5.8.3
vite==6.3.5
tailwindcss==4.1.8
framer-motion==12.18.1
react-router-dom==7.6.1
s25-project-black/
├── backend/ # Django REST API
│ ├── app/ # Main Django app
│ │ ├── models/ # Database models
│ │ ├── views/ # API endpoints
│ │ ├── serializers/ # Data serialization
│ │ ├── tests/ # Backend tests
│ │ └── utils/ # Utility functions
│ ├── project/ # Django settings
│ └── staticfiles/ # Collected static files
├── frontend/ # React app
│ ├── src/
│ │ ├── components/ # Reusable UI
│ │ ├── pages/ # Page components
│ │ ├── services/ # API layer
│ │ ├── types/ # TypeScript defs
│ │ └── utils/ # Frontend utils
│ └── dist/ # Production build
└── docs/ # Documentation
Content
- Rich posts with Markdown, image uploads, categories
- Per-post privacy controls
- Trending discovery + search
Social
- Follow system with status tracking, automatic friend detection
- Likes + threaded comments
- Realtime notifications, personalized feeds
Federation — the whole point
- Node discovery + management
- Cross-instance communication over an ActivityPub-compatible protocol
- Push-based distribution, remote following, federated inbox delivery
UI
- Liquid-glass (glassmorphism), dark/light, fully responsive, smooth transitions
The models are where the federation logic actually lives:
- Author — user accounts with federation support (extends Django's
AbstractUser) - Entry — posts, with visibility controls + multiple content types
- Follow — follow relationships with status (pending / accepted / rejected)
- Friendship — computed from mutual follows
- Comment — threaded comments
- Like — targets both entries and comments
- Inbox — activity notifications, this is what federation delivers into
- Node — a remote federated instance
Relationships in one breath: authors follow authors (local or remote), entries belong to authors, comments and likes hang off entries, the inbox stores incoming activities, and nodes hold the credentials for cross-instance links.
You need Python 3.11, Node 18+, Postgres, and Git.
git clone <repository-url> && cd s25-project-black
# Backend (terminal 1)
cd backend
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
python manage.py migrate
python manage.py createsuperuser
python manage.py runserver
# Frontend (terminal 2)
cd frontend
npm install
npm run devThen:
- Frontend → http://localhost:5173
- Backend API → http://localhost:8000
- Admin → http://localhost:8000/admin
Backend .env
SECRET_KEY=your-secret-key
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1
DATABASE_URL=postgres://user:pass@localhost/dbname
SITE_URL=http://localhost:8000
AUTO_APPROVE_NEW_USERS=TrueFrontend .env
VITE_API_URL=http://localhost:8000
VITE_ENABLE_GITHUB_ACTIVITY=true
VITE_ENABLE_FEDERATION=trueThe REST API, in the parts you'll actually reach for:
Auth
POST /api/auth/login/ # login
POST /api/auth/signup/ # register
GET /api/auth/status/ # am I logged in?
POST /api/auth/logout/ # logout
Content
GET /api/entries/ # list posts (filterable)
POST /api/entries/ # create
GET /api/entries/{id}/ # read
PATCH /api/entries/{id}/ # update
DELETE /api/entries/{id}/ # delete
Social
GET /api/authors/ # list authors
POST /api/follows/ # send follow request
POST /api/entries/{id}/likes/ # like
POST /api/entries/{id}/comments/ # comment
Federation
POST /api/authors/{id}/inbox/ # deliver an activity to an author
GET /api/nodes/ # list nodes
POST /api/nodes/add/ # connect a new node
Full reference: Backend API Documentation.
# Backend
cd backend && python manage.py test
# Frontend
cd frontend
npm run test
npx playwright test # E2EConfigured for Heroku, frontend build is automated:
npm run heroku-postbuildFor production: set your env vars, point at a real Postgres, sort out static serving, lock down CORS to your domain, force HTTPS, and wire up logging/monitoring.
A simplified, ActivityPub-compatible protocol. Four activity types cover everything:
- Create — push a new post to followers
- Follow — send a follow request to a remote author
- Like — federate a like
- Comment — federate a comment
Auth between servers is HTTP Basic with per-node credentials; local users use sessions. And the piece that makes cross-node references work — every object has a Fully Qualified ID (FQID) so there's never ambiguity about which server owns what:
http://{host}/api/{resource_path}/{uuid}
| 📖 Docs | 🎥 Media |
|---|---|
| Frontend Guide | Demo Video |
| API Reference | Project Spec |