A Token-Based Social Media Platform Where Engagement Has Real Value
Kudos reimagines social media by replacing traditional "likes" with a scarce token economy. Every user receives a limited supply of tokens, making engagement meaningful and thoughtful. Instead of infinite, reflexive likes, users must spend their hard-earned tokens to signal appreciation—creating economic incentives for quality content and meaningful curation.
"By reducing how easy it is to like content, the bar for what goes viral goes a notch higher."
Traditional social media incentivizes engagement at any cost. Kudos flips this model:
- Likes become investments — Spend 1-10 tokens to express how much you value content
- Quality rises naturally — When engagement costs something, users think before they click
- Creators are rewarded — Great content creators accumulate tokens and influence
- Fair redistribution — Progressive taxation and stipends ensure everyone can participate
- 💰 100 starting tokens for every new user
- 📊 60/20/20 split — 60% to creator, 20% to government pool, 20% burned
- 📈 Progressive taxation — Wealthy accounts pay more to fund stipends
- 🔄 Weekly stipends — Active users receive tokens from the community pool
- ⏰ Time decay — Inactive content gradually loses token value
- 📝 Posts with token metrics — See both engagement count AND total tokens spent
- 💬 Comments cost tokens — First 2 daily comments free, then 0.5 tokens each
- 🔥 MLFQ Feed Algorithm — Content moves through Hot → Warm → Cold → Archive queues
- ↩️ 24-hour unlike window — Changed your mind? Get a full refund within 24 hours
- 📱 Phone number authentication — One account per phone number
- 👤 Public pages — Multiple personas, unified token pool
- 🔍 Multiple feed types — Hot Today, Following, Hidden Gems, Trending
- 📊 Wealth transparency — Public leaderboards and wealth metrics
Kudos uses a microservices architecture with services split by technology and responsibility:
┌─────────────────┐
│ Frontend │
│ (Next.js) │
│ Port 3000 │
└────────┬────────┘
│
▼
┌─────────────────┐
│ API Gateway │
│ (Node.js) │
│ Port 8080 │
└────────┬────────┘
│
┌─────────────────────────────────┼─────────────────────────────────┐
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ HTTP Services │ │ gRPC Services │ │ Background │
│ (Node.js) │ │ (Go) │ │ Jobs (Go) │
└───────────────┘ └───────────────┘ └───────────────┘
│ │ │
┌───────┴───────┐ ┌────────┴───────┐ │
│ │ │ │ │
▼ ▼ ▼ ▼ │
┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │
│ Auth │ │Content│ │Token │ │ Feed │ │
│:4000 │ │:4001 │ │:50051│ │:50052│ │
└──────┘ └──────┘ └──────┘ └──────┘ │
│ │ │ │ │
▼ ▼ ▼ ▼ │
┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┴───────┐
│ User │ │ │ │ │ │ │ │ Jobs Service│
│:4002 │ │ │ │ │ │ │ │ :4004 │
└──────┘ │ │ │ │ │ │ └──────────────┘
│ │ │ │ │ │ │
└──────┴─────────┴──────┴────────┴──────┘ │
│ │
▼ │
┌─────────────────┐ │
│ PostgreSQL │◄───────────────────────────┘
│ :5432 │
└─────────────────┘
| Service | Technology | Port | Responsibility |
|---|---|---|---|
| Frontend | Next.js 16 | 3000 | Web UI, user experience |
| API Gateway | Node.js | 8080 | Request routing, rate limiting, auth, proxy |
| Auth Service | Node.js | 4000 | Phone verification, JWT authentication |
| Content Service | Node.js | 4001 | Posts, comments, content management |
| User Service | Node.js | 4002 | Profiles, avatars, user search |
| Token Service | Go (gRPC) | 50051 | Token spending, balance, transactions |
| Feed Service | Go (gRPC) | 50052 | MLFQ feed generation, trending |
| Jobs Service | Go | 4004 | Decay, taxation, stipends, queue updates |
| PostgreSQL | - | 5432 | Primary database |
- Docker and Docker Compose
- Node.js 18+ and npm
- Go 1.21+
- PostgreSQL 15+ (or use Docker)
# Clone the repository
git clone https://github.com/yourusername/kudos.git
cd kudos
# Copy environment file
cp .env.example .env
# Edit .env with your settings
# - Set DB_PASSWORD
# - Set JWT_SECRET
# - Set Twilio credentials for SMS (optional for dev)# Start all services
docker-compose up -d
# Check service health
make health
# View logs
docker-compose logs -f- Frontend: http://localhost:3000
- API Gateway: http://localhost:8080
- Health Check: http://localhost:8080/health
# Install dependencies
make setup
# Start database
make db-up
# Run all services in development mode
make dev
# Or run individual services
make dev-auth # Auth service
make dev-content # Content service
make dev-user # User service
make dev-gateway # API gateway
make dev-token # Token service (Go)
make dev-feed # Feed service (Go)
make dev-jobs # Jobs service (Go)kudos/
├── backend/
│ ├── node/
│ │ ├── api-gateway/ # Central API routing & proxying
│ │ ├── auth-service/ # Phone auth & JWT management
│ │ ├── content-service/ # Posts & comments
│ │ └── user-service/ # Profiles & avatars
│ ├── go/
│ │ └── go-core/ # Token, Feed, & Jobs services
│ └── shared/ # Shared types & utilities
├── frontend/ # Next.js web application
├── docker-compose.yml # Docker orchestration
├── schema.sql # Database schema
├── Makefile # Development commands
├── DESIGN.md # Token economics spec
└── README.md # This file
# Setup & Installation
make setup # Install all dependencies
# Database
make db-up # Start PostgreSQL
make db-down # Stop PostgreSQL
make db-reset # Reset database (WARNING: deletes data)
# Services
make services-up # Start all services (Docker)
make services-down # Stop all services
make services-restart # Restart all services
# Development
make dev # Run all services in dev mode
make dev-auth # Run auth service only
make dev-content # Run content service only
make dev-user # Run user service only
make dev-gateway # Run API gateway only
make dev-token # Run token service only
make dev-feed # Run feed service only
make dev-jobs # Run jobs service only
# Logs
make logs # View all service logs
make logs-auth # View auth service logs
make logs-gateway # View gateway logs
# Testing
make test # Run all tests
make health # Check all service health
# Cleanup
make clean # Remove dependencies & generated files
make stop # Stop all running services- DESIGN.md — Complete token economics design & specification
- backend/node/auth-service/README.md — Auth service docs
- backend/node/content-service/README.md — Content service docs
- backend/node/user-service/README.md — User service docs
- backend/node/api-gateway/README.md — API gateway docs
- backend/go/go-core/README.md — Token service docs
- backend/go/go-core/FEED_README.md — Feed service docs
- backend/go/go-core/JOBS_README.md — Jobs service docs
- frontend/README.md — Frontend docs
When a user spends 10 tokens on a post:
- 6 tokens (60%) → Creator
- 2 tokens (20%) → Government pool (funds stipends)
- 2 tokens (20%) → Burned (deflationary)
| Balance | Tax Rate |
|---|---|
| 0-200 | 0% (exempt) |
| 201-500 | 5% |
| 501-1,000 | 10% |
| 1,001-2,000 | 15% |
| 2,000+ | 20% |
- Base stipend: ~10 tokens/week for active users
- Engagement bonus: +10 tokens if you earned tokens last week
- New user bonus: 2x stipend for first 4 weeks
See DESIGN.md for the complete specification.
# Send OTP
curl -X POST http://localhost:8080/api/v1/auth/send-otp \
-H "Content-Type: application/json" \
-d '{"phone": "+1234567890"}'
# Verify OTP
curl -X POST http://localhost:8080/api/v1/auth/verify-otp \
-H "Content-Type: application/json" \
-d '{"verification_id": "...", "code": "123456"}'# Create post
curl -X POST http://localhost:8080/api/v1/posts \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"content": "Hello Kudos!"}'
# Spend tokens on a post
curl -X POST http://localhost:8080/api/v1/tokens/spend \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"target_type": "post", "target_id": "...", "amount": 5}'# Get global feed
curl http://localhost:8080/api/v1/feed/global?limit=20
# Get trending posts
curl http://localhost:8080/api/v1/feed/trending?time_window=day