Twitter/X Clone

A full-stack social media and community platform built with a microservices architecture.

Tech Stack

Frontend

• Svelte 5 + TypeScript
• Vite 6
• Axios, jwt-decode, svelte-routing, Sass

Backend

• Go 1.24 (microservices + API gateway)
• gRPC (inter-service communication)
• Gin (HTTP framework)
• GORM (ORM)

Infrastructure

• PostgreSQL (one database per service)
• Redis (caching)
• RabbitMQ (async messaging)
• Supabase (file storage)
• Docker Compose

---

Architecture

Browser (Svelte SPA)
       │
       ▼
  API Gateway (Gin/HTTP :8080)
       │
       ├── gRPC ──► auth-service      (:50050)
       ├── gRPC ──► user-service      (:50051)
       ├── gRPC ──► content-service   (:50052)
       ├── gRPC ──► chat-service      (:50053)  ◄── WebSocket
       └── gRPC ──► community-service (:50054)
                         │
                         └── RabbitMQ ──► message-service (email)

Each service owns its own PostgreSQL database.

---

Features

Authentication

• Email/password registration and login
• Google OAuth
• JWT access + refresh token rotation
• Email OTP verification
• Security questions for account recovery
• reCAPTCHA on login

Social

• Follow / unfollow users
• Block / unblock users
• User profile with avatar, banner, bio
• User suggestions
• Notifications (likes, reposts, follows, mentions, community events)

Content

• Create threads with images/videos
• Hashtag support
• Polls with voting
• Comments and replies
• Like, repost, bookmark
• Pinned threads/replies

Communities

• Create communities with categories and rules
• Join request workflow
• Community banner and logo
• Member management

Real-Time

• WebSocket-based direct messaging
• Live notifications

Admin

• Premium account request approval/rejection
• User ban management

---

Project Structure

TPA-Web/
├── frontend/               # Svelte SPA
│   └── src/
│       ├── routes/         # Pages
│       ├── lib/
│       │   ├── api/        # HTTP clients and DTOs
│       │   ├── components/ # Reusable UI components
│       │   ├── stores/     # Svelte stores (chat, notifications, websocket)
│       │   ├── models/     # TypeScript types
│       │   └── utils/      # JWT utilities, date formatting
│       └── assets/
├── api-gateway/            # HTTP gateway (Go/Gin)
│   └── internal/
│       ├── handlers/       # HTTP request handlers
│       ├── client/         # gRPC clients
│       └── router/         # Route definitions
├── services/
│   ├── user-service/
│   ├── auth-service/
│   ├── content-service/
│   ├── chat-service/
│   ├── community-service/
│   ├── message-service/    # Email via SMTP + RabbitMQ
│   └── ai-service/         # Python-based AI features
├── proto/                  # Protocol Buffer definitions
├── docker-compose.yml
└── .env.example

---

Getting Started

Prerequisites

• Docker and Docker Compose
• (For local dev) Node.js 20+, Go 1.24+

1. Clone and configure environment

git clone <repo-url>
cd TPA-Web
cp .env.example .env
# Edit .env with your credentials

2. Run with Docker Compose

docker-compose up -d

This starts all services, databases, Redis, and RabbitMQ with health-check dependencies.

Service	URL
Frontend	http://localhost:4173
API Gateway	http://localhost:8080
Swagger Docs	http://localhost:8080/swagger/index.html

3. Frontend development (without Docker)

cd frontend
npm install
npm run dev

---

Environment Variables

Copy .env.example to .env and fill in the values.

Databases (PostgreSQL)

Variable	Description
USER_POSTGRES_HOST/PORT/DB/USER/PASSWORD	User service DB
CONTENT_POSTGRES_*	Content service DB
CHAT_POSTGRES_*	Chat service DB
COMMUNITY_POSTGRES_*	Community service DB

Service Ports

Variable	Default	Description
GATEWAY_HTTP_PORT	8080	API Gateway
AUTH_SERVICE_GRPC_PORT	50050	Auth gRPC
USER_SERVICE_GRPC_PORT	50051	User gRPC
CONTENT_SERVICE_GRPC_PORT	50052	Content gRPC
CHAT_SERVICE_GRPC_PORT	50053	Chat gRPC
COMMUNITY_SERVICE_GRPC_PORT	50054	Community gRPC
FRONTEND_PORT	4173	Frontend

External Services

Variable	Description
SUPABASE_URL	Supabase project URL
SUPABASE_KEY	Supabase service key
SUPABASE_BUCKET	Storage bucket name
SMTP_HOST/PORT/USERNAME/PASSWORD	Email delivery
RECAPTCHA_SECRET_KEY	Google reCAPTCHA
GOOGLE_CLIENT_ID/SECRET/REDIRECT_URL	Google OAuth
RABBITMQ_USERNAME/PASSWORD/HOST/PORT	Message queue
REDIS_HOST/PORT	Cache

Auth

Variable	Description
JWT_SECRET_KEY	JWT signing secret
VITE_BACKEND_URL	Frontend → API Gateway URL

---

Pages / Routes

Route	Description
/	Landing page
/auth/login	Login
/auth/register	Registration
/auth/forgot	Password reset
/auth/callback	Google OAuth callback
/home	Main feed
/chat	Direct messaging
/thread/:id	Thread detail view
/user/profile	Own profile
/user/:id	Other user profile
/explore	Explore content
/community	Community list
/community/create	Create community
/community/:id	Community detail
/notifications	Notifications
/bookmarks	Saved content
/premium	Premium request
/settings	Account settings
/admin	Admin dashboard

---

Frontend Scripts

npm run dev      # Start dev server (hot reload)
npm run build    # Production build
npm run preview  # Preview production build
npm run check    # Type check + lint

---

API Documentation

Swagger UI is available at http://localhost:8080/swagger/index.html when the API gateway is running.

---

Authentication Flow

1. User submits credentials → API Gateway → Auth Service
2. Auth Service returns JWT access token + refresh token
3. Frontend stores tokens in localStorage
4. All subsequent requests include Authorization: Bearer <token>
5. API Gateway validates each request with Auth Service
6. On token expiry, frontend automatically calls the refresh endpoint

---

Data Flow (Content Creation Example)

Frontend
  │ POST /api/thread (multipart form)
  ▼
API Gateway
  │ Upload media → Supabase
  │ gRPC CreateThread → Content Service
  ▼
Content Service
  │ INSERT thread (PostgreSQL)
  │ Publish event → RabbitMQ
  ▼
Message Service
  └── Send email notification (SMTP)