A full-featured Instagram clone built with modern microservices architecture, featuring real-time messaging, stories, posts, video calls, and AI-powered caption generation.
-
User Management
- Registration with email verification (OTP)
- Login with JWT authentication (access + refresh tokens)
- Two-Factor Authentication (2FA)
- Google OAuth integration
- Password reset functionality
- User profile with verification badges
- Profile privacy settings (private/public accounts)
-
Posts
- Create posts with images/videos
- Multiple media uploads per post
- Video transcoding for optimized playback
- Like and save posts
- Comments with nested replies
- Post summarization using AI
- Hashtag support with trending topics
- Explore feed with personalized recommendations
-
Stories
- 24-hour ephemeral stories
- Image and video stories
- Story filters and stickers
- Text overlays with customization
- Close friends feature
- Story archive
- View analytics
-
Messaging
- Real-time chat via WebSocket
- Direct messages and group conversations
- Media sharing (images, videos)
- Video and audio calls (VideoSDK integration)
- Message status (sent, delivered, seen)
- Online status indicators
-
Social Interactions
- Follow/unfollow users
- Block/unblock users
- Hide stories from specific users
- Close friends management
- User search with Jaro-Winkler similarity algorithm
- Friend recommendations
-
Content Moderation
- Post reporting system
- Admin dashboard for report management
- User banning capabilities
- Content visibility controls
The application follows a microservices architecture pattern with the following services:
βββββββββββββββββββ
β Traefik β β Reverse Proxy & Load Balancer
β (Port 80/443) β
ββββββββββ¬βββββββββ
β
βββββββββββββββ
β β
ββββββΌβββββ βββββΌβββββββ
βFrontend β β API β
β Vue.js β β Gateway β
βββββββββββ ββββββ¬ββββββ
β
βββββββββββββββΌββββββββββββββ¬ββββββββββββββ¬βββββββββββββββ
β β β β β
ββββββΌβββββ βββββΌβββββββ βββββΌβββββββ βββββΌβββββββ βββββΌβββββββ
β User β β Post β β Story β β Message β β Media β
β Service β β Service β β Service β β Service β β Service β
ββββββ¬βββββ ββββββ¬ββββββ ββββββ¬ββββββ ββββββ¬ββββββ ββββββ¬ββββββ
β β β β β
ββββββΌβββββ βββββΌβββββββ βββββΌβββββββ βββββΌβββββββ βββββΌβββββββ
βUser DB β β Post DB β βStory DB β βMessage DBβ β MinIO β
βPostgres β β Postgres β β Postgres β β Postgres β β(Storage) β
βββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ
Additional services:
- Hashtag Service: Manages hashtags and trending topics
- Report Service: Handles content reporting and moderation
- Notification Service: Manages user notifications
- Email Service: Sends transactional emails
- Worker Service: Background job processing (video transcoding, story expiration)
- AI Service: Caption summarization using T5 transformer model
- gRPC: Inter-service communication for high performance
- REST API: Client-facing API through API Gateway
- WebSocket: Real-time messaging and notifications
- RabbitMQ: Asynchronous message queue for background tasks
- Redis: Caching and distributed rate limiting
- Language: Go 1.25
- Framework: Gin (HTTP), gRPC
- Database: PostgreSQL 15 (per-service databases)
- Cache: Redis 7
- Message Queue: RabbitMQ 3.12
- Object Storage: MinIO
- Authentication: JWT with bcrypt
- API Documentation: Swagger/OpenAPI
- Framework: Vue.js 3.5
- Build Tool: Vite (Rolldown variant)
- State Management: Pinia
- Routing: Vue Router
- Styling: SCSS with CSS variables for theming
- HTTP Client: Axios
- Testing: Vitest
- Language: Python 3.11
- Framework: FastAPI
- ML Library: PyTorch 2.1, Transformers 4.35
- Model: T5 (Text-to-Text Transfer Transformer) for caption summarization
- Model Source: Hugging Face (
alexcsl10/baption)
- Containerization: Docker & Docker Compose
- Reverse Proxy: Traefik 2.10
- Video Processing: FFmpeg (for transcoding)
- Video Calls: VideoSDK integration
- Docker Desktop (or Docker Engine + Docker Compose)
- Git
- (Optional) Go 1.25+ for local backend development
- (Optional) Node.js 20+ for local frontend development
- (Optional) Python 3.11+ for AI service development
git clone https://github.com/yourusername/hoshibmatchi.git
cd hoshibmatchiIMPORTANT: The .env file in the repository contains default development values. For production or public deployment, you MUST update these values:
# Copy and edit the environment file
cp .env .env.production
# Update these critical values:
# - JWT_SECRET (generate a secure random string)
# - Database passwords
# - GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET (obtain from Google Cloud Console)
# - VIDEOSDK_API_KEY and VIDEOSDK_API_SECRET (obtain from VideoSDK)
# - SMTP credentials for email service
# - MinIO credentialsSecurity Warning: The current .env file contains example credentials and should NOT be used in production!
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up --builddocker-compose up --build -d- Frontend: http://localhost:5173 (dev) or http://localhost:80 (prod)
- API Gateway: http://localhost:8000
- API Documentation: http://localhost:8000/swagger/index.html
- Traefik Dashboard: http://localhost:8080
- MinIO Console: http://localhost:9001
- RabbitMQ Management: http://localhost:15672 (dev only)
On first run, you may need to:
- Create MinIO buckets (posts, stories, messages, profile-pictures)
- Run database migrations (automatically handled by services on startup)
- Register a test account
hoshibmatchi/
βββ backend/
β βββ api-gateway/ # REST API entry point
β βββ user-service/ # User management, auth, profiles
β βββ post-service/ # Post CRUD, likes, comments
β βββ story-service/ # Story management (24h expiry)
β βββ message-service/ # Chat and video calls
β βββ media-service/ # Media upload to MinIO
β βββ hashtag-service/ # Hashtag tracking
β βββ report-service/ # Content moderation
β βββ notification-service/ # Push notifications
β βββ email-service/ # Email sending
β βββ worker-service/ # Background jobs
β βββ ai-service/ # AI caption summarization
β
βββ frontend/
β βββ hoshi-vue/ # Vue.js SPA
β
βββ protos/ # gRPC protocol definitions
βββ traefik/ # Traefik configuration
βββ docker-compose.yml # Production compose file
βββ docker-compose.dev.yml # Development overrides
βββ .env # Environment variables
Each microservice is independently buildable:
cd backend/user-service
go mod download
go run main.goGenerate gRPC code:
cd protos
protoc --go_out=. --go-grpc_out=. user.protocd frontend/hoshi-vue
npm install
npm run devBuild for production:
npm run buildcd backend/ai-service
pip install -r requirements.txt
python main.pycd backend/user-service
go test ./...cd frontend/hoshi-vue
npm run test
npm run test:coverageEach service has its own PostgreSQL database following the database-per-service pattern:
- user_service_db: Users, followers, blocks, close friends
- post_service_db: Posts, comments, likes, saves, collections
- story_service_db: Stories, story views, story likes
- message_service_db: Conversations, messages, message status
- notification_service_db: Notifications
- report_service_db: Reports
- hashtag_service_db: Hashtags, trending data
- JWT-based authentication with short-lived access tokens
- Refresh token rotation
- Password hashing with bcrypt
- Rate limiting (Redis-backed distributed limiter)
- CORS configuration
- SQL injection prevention (parameterized queries)
- Input validation and sanitization
- Cloudflare Turnstile CAPTCHA integration
- Content Security Policy headers
- Private account support
- Blocked user filtering
POST /auth/register- Register new userPOST /auth/login- Login with credentialsPOST /auth/login/2fa- Verify 2FA codePOST /auth/refresh- Refresh access tokenGET /auth/google- OAuth with GooglePOST /auth/password-reset- Request password resetPOST /auth/password-reset/verify- Verify reset token
GET /feed/home- Home feedGET /feed/explore- Explore feedGET /feed/reels- Reels feedPOST /posts- Create postDELETE /posts/:id- Delete postPOST /posts/:id/like- Like postPOST /posts/:id/save- Save postPOST /posts/:id/summarize- AI summarize caption
GET /stories/feed- Get story feedPOST /stories- Create storyPOST /stories/:id/view- Mark story as viewedGET /stories/archive- Get archived stories
GET /messages/conversations- List conversationsPOST /messages- Send messageGET /messages/token- Get video call token
See API Documentation for full details.
The project is containerized and can be deployed to any Docker-compatible platform:
- Docker Swarm
- Kubernetes (K8s manifests needed)
- AWS ECS
- Google Cloud Run
- Azure Container Instances
For production deployment:
- Update all secrets in
.env - Configure SSL certificates in Traefik
- Set up proper DNS records
- Configure backup strategies for PostgreSQL databases
- Set up monitoring and logging (Prometheus, Grafana)
- Configure MinIO for production (persistent volumes)
This is a personal portfolio project. If you'd like to contribute or provide feedback:
- Fork the repository
- Create a feature branch
- Make your changes
- Submit a pull request
This project is for educational and portfolio purposes. All rights reserved.
- Vue.js and Go communities
- Hugging Face for pre-trained models
- VideoSDK for video calling infrastructure
- MinIO for object storage
- Traefik for reverse proxy
For questions or collaboration opportunities, please reach out via:
- GitHub: @alexcsl
- Email: hoshibmatchi@gmail.com
Note: This is a demonstration project showcasing microservices architecture, full-stack development, and modern DevOps practices. It is not intended for production use without proper security hardening and infrastructure setup. This project is still buggy and is in development. It's a messy project hehe...