Splitter

Federated social media platform built with Go, ActivityPub, and Next.js. Run your own instance and communicate across the network.

Live Demo: https://splitter-red-phi.vercel.app
Backend API: https://splitter-m0kv.onrender.com/api/v1/health

Overview

Splitter is a full-stack federated social network. Each instance is independent but communicates with others via the ActivityPub protocol — users on one instance can follow and exchange content with users on any other Splitter (or compatible) instance.

Core Features:

Federated social graph — follow, posts, boosts, replies across instances
End-to-end encrypted DMs — Ed25519 key-pairs per device; server never sees plaintext
Dual authentication — password/JWT and DID (Decentralized Identity) cryptographic login
Hashtag trending — regex extraction + real-time trending tab backed by PostgreSQL full-text search
AI @split bot — mention @split in any post to receive a synchronous AI reply (Gemini 1.5 Flash / GPT-4o-mini)
Automated bot population — GitHub Actions cron job seeds the network with realistic content every 30 minutes
Circle visibility — posts visible only to curated "circle" members
Admin & moderation — role management, content reports, AI-assisted screening

Architecture

┌─────────────────────┐     HTTPS      ┌─────────────────────┐
│  Next.js Frontend   │ ◄────────────► │  Go/Echo Backend    │
│  (Vercel)           │                │  (Render)           │
│  React + Tailwind   │                │  REST API + AP      │
└─────────────────────┘                └──────────┬──────────┘
                                                   │ pgx/v5
                                       ┌───────────▼──────────┐
                                       │  PostgreSQL 15        │
                                       │  (Neon — serverless)  │
                                       └───────────────────────┘

Federation:
  Instance 1  ◄──── ActivityPub (HTTP Signatures) ────►  Instance 2
  splitter-m0kv.onrender.com                             splitter-2.onrender.com

Component	Technology
Backend API	Go 1.24 / Echo v4
Database	PostgreSQL 15 (Neon serverless)
ORM / Driver	jackc/pgx v5
Frontend	Next.js 16 / React 19 / Tailwind CSS
Auth	bcrypt + JWT (RS256) / Ed25519 DID keypairs
Federation	ActivityPub (W3C), HTTP Signatures, WebFinger
AI	Google Gemini 1.5 Flash / OpenAI GPT-4o-mini
Bots	Python 3 + GitHub Actions cron
Hosting	Render (backend) + Vercel (frontend) + Neon (DB)

Project Structure

splitter/
├── cmd/
│   ├── server/             # Main server entrypoint
│   └── migrate/            # Standalone migration runner
├── internal/
│   ├── auth/               # DID keypair generation & verification
│   ├── config/             # Environment-based configuration
│   ├── db/                 # Database connection (Neon + SSL)
│   ├── federation/         # ActivityPub delivery, signatures, peer health
│   ├── handlers/           # HTTP request handlers (one file per domain)
│   ├── helpers/            # Shared utility functions
│   ├── middleware/         # JWT auth, optional auth, CORS
│   ├── models/             # Domain model structs
│   ├── repository/         # Data-access layer (pgx queries)
│   └── server/             # Router setup & middleware wiring
├── migrations/             # Ordered SQL migration files
├── scripts/
│   └── bots/               # Python bot population scripts
├── tests/
│   ├── docs/               # Testing documentation (01–08)
│   ├── unit/               # Unit tests (auth, posts, replies, users, security)
│   ├── integration/        # Integration test suite
│   ├── e2e_test/           # End-to-end tests
│   ├── load/               # Load tests (k6 / Go)
│   ├── seeder/             # Test data seeder
│   └── results/            # Captured test output
├── diagrams/               # Architecture, ER, sequence, class diagrams (Mermaid)
├── .env.example            # Environment variables template
├── Dockerfile              # Multi-stage Docker build
├── docker-compose.instances.yml  # Two-instance local federation setup
├── Makefile                # Common dev commands
└── go.mod

Quick Start

Prerequisites

Tool	Version	Notes
Go	1.21+	go.dev/dl
Node.js	18+	nodejs.org
Docker	Any	For running `psql` migrations
Neon account	—	Free tier at neon.tech

1. Clone & Configure

git clone <repository-url>
cd splitter
cp .env.example .env

Edit .env with your Neon credentials:

DB_HOST=ep-your-endpoint.region.aws.neon.tech
DB_PORT=5432
DB_USER=neondb_owner
DB_PASSWORD=your-password
DB_NAME=neondb
PORT=8000
ENV=development
BASE_URL=http://localhost:8000
JWT_SECRET=change-this-to-a-secure-random-string

2. Apply Database Migrations

docker run --rm postgres:15 psql \
  'postgres://USER:PASS@HOST/DBNAME?sslmode=require' \
  -f migrations/000_master_schema.sql

3. Start the Backend

go mod download
go run ./cmd/server
# → Server listening on http://localhost:8000

Default admin account created on first startup:

Username: admin
Password: splitteradmin   ⚠️ Change immediately in production

4. Start the Frontend

cd ../Splitter-frontend
npm install
npm run dev
# → Frontend at http://localhost:3000

5. Two-Instance Local Federation (Optional)

docker compose -f docker-compose.instances.yml up

This spins up two backend instances that federate with each other locally.

API Reference

Base URL: http://localhost:8000/api/v1
🔒 = Requires Authorization: Bearer <jwt_token>

Authentication

Method	Endpoint	Description
`POST`	`/auth/register`	Register with username/email/password
`POST`	`/auth/login`	Login → returns JWT
`POST`	`/auth/challenge`	Request a DID auth nonce
`POST`	`/auth/verify`	Verify DID signature → returns JWT
`POST`	`/auth/refresh` 🔒	Rotate JWT
`POST`	`/auth/logout` 🔒	Invalidate token

Users

Method	Endpoint	Description
`GET`	`/users/:id`	Get user by ID
`GET`	`/users/did`	Get user by DID
`GET` 🔒	`/users/me`	Get own profile
`PUT` 🔒	`/users/me`	Update profile
`DELETE` 🔒	`/users/me`	Delete account
`GET` 🔒	`/users/search`	Search users
`POST` 🔒	`/users/me/circle/:id`	Add user to circle
`DELETE` 🔒	`/users/me/circle/:id`	Remove from circle
`GET` 🔒	`/users/me/circle/:id/check`	Check circle membership

Posts

Method	Endpoint	Description
`GET`	`/posts/public`	Public feed
`GET`	`/posts/:id`	Get post
`GET`	`/posts/user/:did`	Posts by user DID
`GET` 🔒	`/posts/feed`	Personalized feed (follows + own)
`POST` 🔒	`/posts`	Create post (multipart/form-data)
`PUT` 🔒	`/posts/:id`	Update post
`DELETE` 🔒	`/posts/:id`	Delete post

Replies

Method	Endpoint	Description
`GET`	`/posts/:id/replies`	Threaded replies for a post
`POST` 🔒	`/posts/:id/replies`	Reply to a post

Social

Method	Endpoint	Description
`POST` 🔒	`/users/:id/follow`	Follow user
`DELETE` 🔒	`/users/:id/follow`	Unfollow
`GET`	`/users/:id/followers`	Followers list
`GET`	`/users/:id/following`	Following list
`POST` 🔒	`/posts/:id/like`	Like post
`DELETE` 🔒	`/posts/:id/like`	Unlike post
`POST` 🔒	`/posts/:id/repost`	Boost/repost
`POST` 🔒	`/posts/:id/bookmark`	Bookmark post

Direct Messages

Method	Endpoint	Description
`GET` 🔒	`/messages/threads`	All message threads
`GET` 🔒	`/messages/conversation/:userId`	Messages with a user
`POST` 🔒	`/messages/send`	Send encrypted message

Federation

Method	Endpoint	Description
`GET`	`/federation/timeline`	Cross-instance federated timeline
`GET`	`/federation/users`	Search users across instances
`POST`	`/ap/users/:username/inbox`	ActivityPub inbox
`GET`	`/ap/users/:username`	ActivityPub Actor JSON-LD
`GET`	`/.well-known/webfinger`	WebFinger discovery

Admin `🔒 Admin role required`

Method	Endpoint	Description
`GET`	`/admin/users`	List all users
`PUT`	`/admin/users/:id/role`	Change role
`POST`	`/admin/users/:id/suspend`	Suspend account
`POST`	`/admin/users/:id/unsuspend`	Unsuspend account
`GET`	`/admin/moderation-requests`	Content reports queue
`POST`	`/admin/moderation-requests/:id/approve`	Approve moderator

Full annotated reference with request/response examples: API_ENDPOINTS.md

Authentication

Password Login

Standard username + password flow returning a JWT:

curl -X POST http://localhost:8000/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"alice","password":"secret"}'
# → {"token":"eyJ..."}

Use the token as Authorization: Bearer <token> on subsequent requests.

DID (Decentralized Identity)

Challenge-response using Ed25519 keypairs — the server never receives the private key:

1. POST /auth/challenge   { did: "did:web:..." }   → { challenge: "nonce" }
2. Client signs nonce with private key
3. POST /auth/verify      { did, challenge, signature } → { token: "JWT" }

Private keys are stored locally (encrypted) in the browser. Recovery requires the encrypted backup file downloaded at registration.

Federation

Splitter implements a subset of ActivityPub:

Supported Activities

Create · Follow · Accept · Like · Announce · Undo · Delete

Security

All inbound federation POSTs require:

Signature header — HTTP Signatures (RSA-SHA256)
Digest header — SHA-256 body digest
Date header — within ±30 seconds (keep clocks synced via NTP)

Environmental Requirements

FEDERATION_ENABLED=true
FEDERATION_DOMAIN=your-instance-id
FEDERATION_URL=https://your-public-url

For full well-known endpoints and ActivityPub routes, see API_ENDPOINTS.md.

Configuration

All configuration is via environment variables. See .env.example for the full list.

Variable	Required	Description
`DB_HOST`	✅	PostgreSQL host (Neon endpoint)
`DB_PORT`	✅	PostgreSQL port (default: 5432)
`DB_USER`	✅	Database username
`DB_PASSWORD`	✅	Database password
`DB_NAME`	✅	Database name
`PORT`	✅	HTTP server port
`ENV`	✅	`development` or `production`
`JWT_SECRET`	✅	Secret for JWT signing
`BASE_URL`	✅	Public base URL of this instance
`SPLIT_BOT_API_KEY`	Optional	OpenAI / Gemini key for `@split` bot
`FEDERATION_ENABLED`	Optional	Enable ActivityPub federation
`FEDERATION_DOMAIN`	Optional	Canonical domain/ID for this instance
`FEDERATION_URL`	Optional	Public HTTPS URL for federation

Testing

# Run all tests
make test

# Run with coverage report
make test-cover

# Test a specific package
go test ./tests/unit/auth -v

# Integration tests (requires live DB in .env)
go test ./tests/integration/... -v

# Load tests
go test ./tests/load -v

Test documentation is in tests/docs/:

Doc	Coverage
`01_UNIT_TESTING.md`	Unit test strategy & examples
`02_INTEGRATION_TESTING.md`	Integration flows
`03_E2E_TESTING.md`	End-to-end scenarios
`04_DATABASE_TESTING.md`	Schema & migration tests
`05_LOAD_TESTING.md`	k6 / Go load benchmarks
`06_TEST_SEEDING.md`	Data seeder usage
`07_TEST_REPORTS.md`	Report format & CI integration
`08_REGRESSION_TESTING.md`	Regression suite

Documentation Index

Document	Description
`DEPLOYMENT.md`	Live services, Render + Neon setup, CI/CD, deploy checklist
`API_ENDPOINTS.md`	Full annotated API reference with cURL examples
`DATABASE_SCHEMA.md`	Schema tables, indexes, relationships
`CONTRIBUTING.md`	Dev workflow, code standards, extension recipes
`SECURITY.md`	Security model, DID auth, E2EE, threat model
`TROUBLESHOOTING.md`	Common issues — DB connection, federation, DID
`CODING_STANDARDS.md`	Go style guide & naming conventions
`OPS.md`	Operational runbooks
`DESIGN.md`	Design decisions & ADRs
`ROADMAP.md`	Planned features & milestones
`BOTS.md`	Bot system architecture
`GLOSSARY.md`	Domain terminology
`diagrams/`	Architecture, ER, sequence, state diagrams (Mermaid)
`migrations/README.md`	Migration file inventory
`tests/docs/`	Full testing documentation suite

Contributing

See CONTRIBUTING.md for:

Development setup
Branch & commit conventions
Code standards (Go formatting, error handling, naming)
How to add new endpoints, models, and handlers
Developer recipes (ActivityPub extensions, theming, bots)
PR checklist

License

MIT — see LICENSE.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
cmd		cmd
diagrams		diagrams
internal		internal
migrations		migrations
scripts		scripts
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
API_ENDPOINTS.md		API_ENDPOINTS.md
BOTS.md		BOTS.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CODING_STANDARDS.md		CODING_STANDARDS.md
CONTRIBUTING.md		CONTRIBUTING.md
DATABASE_SCHEMA.md		DATABASE_SCHEMA.md
DEPLOYMENT.md		DEPLOYMENT.md
DESIGN.md		DESIGN.md
Dockerfile		Dockerfile
ERROR_LOG.md		ERROR_LOG.md
GLOSSARY.md		GLOSSARY.md
LICENSE		LICENSE
Makefile		Makefile
NEON_CLOUD_DB_SETUP.md		NEON_CLOUD_DB_SETUP.md
OPS.md		OPS.md
PRIVACY.md		PRIVACY.md
README.md		README.md
ROADMAP.md		ROADMAP.md
SECURITY.md		SECURITY.md
SPLITTER_API.json		SPLITTER_API.json
SPRINT_2_STATUS.md		SPRINT_2_STATUS.md
TROUBLESHOOTING.md		TROUBLESHOOTING.md
diff.txt		diff.txt
docker-compose.db.yml		docker-compose.db.yml
docker-compose.instances.yml		docker-compose.instances.yml
go.mod		go.mod
go.sum		go.sum
openapi.yaml		openapi.yaml
out.txt		out.txt
out_summary.txt		out_summary.txt
out_utf8.txt		out_utf8.txt
pgadmin-servers.json		pgadmin-servers.json
populate_backup.py		populate_backup.py
render.backend.yaml		render.backend.yaml
reply_err.txt		reply_err.txt
temp.txt		temp.txt
test_replies.py		test_replies.py
test_results.txt		test_results.txt
test_results_3.txt		test_results_3.txt
test_results_cmd.txt		test_results_cmd.txt
verify.txt		verify.txt

Latest commit

History

Folders and files

Repository files navigation

Splitter

Table of Contents

Overview

Architecture

Project Structure

Quick Start

Prerequisites

1. Clone & Configure

2. Apply Database Migrations

3. Start the Backend

4. Start the Frontend

5. Two-Instance Local Federation (Optional)

API Reference

Authentication

Users

Posts

Replies

Social

Direct Messages

Federation

Admin 🔒 Admin role required

Authentication

Password Login

DID (Decentralized Identity)

Federation

Supported Activities

Security

Environmental Requirements

Configuration

Testing

Documentation Index

Contributing

License

About

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Admin `🔒 Admin role required`