Skip to content

README.md

Latest commit

 

History

History
207 lines (153 loc) · 6.25 KB

README.md

File metadata and controls

207 lines (153 loc) · 6.25 KB

MetaRGB Microservices

Microservices implementation for the MetaRGB platform migration from Laravel monolith to Golang/gRPC.

Architecture

Services

Service Port Description
auth-service 50051 Authentication, User Management, KYC
commercial-service 50052 Wallet, Transactions, Payments
features-service 50053 Features (Lands), Marketplace
levels-service 50054 User Progression, Activities
dynasty-service 50055 Dynasty, Family Members
support-service 50056 Tickets, Reports
training-service 50057 Video Tutorials, Comments
notifications-service 50058 Multi-channel Notifications
calendar-service 50059 Events Management
storage-service 50060 (gRPC), 8059 (HTTP) File Upload & Management
financial-service 50062 Payment Processing
grpc-gateway 8080 REST to gRPC Translation
websocket-gateway 3002 Real-time Communication
Kong API Gateway 8000 HTTP/REST → gRPC
MySQL 3306 Shared Database
Redis 6379 Caching, Pub/Sub

Shared Components

  • shared/proto: Protocol Buffer definitions
  • shared/pkg: Shared Go packages (db, auth, logger, metrics, helpers)

Prerequisites

  • Go 1.21+ (go version)
  • Protocol Buffers (protoc --version)
  • Docker & Docker Compose (docker --version)
  • Node.js 18+ (for WebSocket gateway)
  • Make (make --version)

External APIs needed: OAuth server, Kavenegar (SMS), Parsian (payments), FTP (storage).

Quick Start

1. Generate Protocol Buffer Files

make proto

2. Configure Services

Each service uses its own config.env. Copy from the sample and edit:

# Example: Auth service
cp services/auth-service/config.env.sample services/auth-service/config.env
# Edit services/auth-service/config.env with your credentials

# Repeat for each service you need:
# services/commercial-service/config.env
# services/notifications-service/config.env
# services/financial-service/config.env
# services/storage-service/config.env
# services/grpc-gateway/config.env
# websocket-gateway/config.env
# etc.

3. Start Infrastructure

docker-compose up -d mysql redis
sleep 10  # Wait for MySQL to be ready

4. Import Database Schema

make import-schema

5. Start All Services

make dev

6. Verify

make ps
curl http://localhost:8000
curl http://localhost:3002/health

Configuration

Each service loads from config.env in its directory. Copy config.env.sample → config.env and set:

  • Database: DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_DATABASE
  • OAuth (auth-service): OAUTH_SERVER_URL, OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET
  • SMS (auth, notifications): KAVENEGAR_API_KEY
  • Parsian (commercial, financial): PARSIAN_MERCHANT_ID, PARSIAN_PIN, etc.
  • FTP (storage): FTP_HOST, FTP_USER, FTP_PASSWORD, FTP_BASE_URL

Docker Compose injects config.env via env_file; the environment section overrides DB_HOST/DB_PORT for container networking.

Common Commands

make dev              # Start full dev environment
make ps               # Check service status
make logs             # View all logs
make logs-service SERVICE=auth-service   # Service-specific logs
make down             # Stop all services

make build-all        # Build all images
make restart-service SERVICE=auth-service
make clean            # Stop and remove volumes

make kong-validate    # Validate Kong config
make kong-reload      # Reload Kong

Local Development (Without Docker)

  1. Database & Redis: Start MySQL 8 and Redis locally
  2. Schema: mysql -u root -p metargb_db < scripts/schema.sql
  3. Config: Copy config.env.sample → config.env per service
  4. Run services in separate terminals:
cd services/auth-service && go run cmd/server/main.go
cd services/commercial-service && go run cmd/server/main.go
cd websocket-gateway && npm install && npm start
# etc.

Project Structure

metargb-microservices/
├── services/
│   ├── auth-service/
│   │   ├── cmd/server/main.go
│   │   ├── internal/handler/    # gRPC handlers
│   │   ├── internal/service/    # Business logic
│   │   ├── internal/repository/ # Data access
│   │   └── config.env.sample
│   └── ...
├── shared/proto/     # .proto files
├── shared/pb/        # Generated Go code
├── kong/             # Kong gateway config
├── scripts/          # Schema, migrations
└── Makefile

Testing

make test-unit        # Unit tests
make test-integration # Integration tests
make test-golden      # Golden JSON (Laravel compatibility)
make test-database    # Database tests
make test-all         # Full suite

Use grpcurl or Postman gRPC for API testing (Kong returns 415 for plain REST on gRPC routes).

Database Schema

Shared schema in scripts/schema.sql. Notes: transactions.id is VARCHAR; feature_properties.id has prefix/postfix; soft deletes use deleted_at; polymorphic relations use {model}_type and {model}_id.

API Compatibility

CRITICAL: All services MUST maintain 100% API compatibility with the Laravel monolith (JSON fields, status codes, validation format, Jalali dates, URLs). Golden tests enforce this.

Troubleshooting

Issue Command
Services not starting docker-compose logs auth-service
Database connection docker exec metargb-mysql mysql -uroot -proot_password -e "SELECT 1"
Port in use lsof -i :50051 (macOS) or netstat -tulpn | grep 50051 (Linux)
Proto errors make clean-proto && make proto
Reset everything make clean && make dev

Deployment

docker build -t metargb/auth-service:latest -f services/auth-service/Dockerfile .
kubectl apply -f k8s/auth-service/

See docs/DEPLOYMENT.md and docs/TROUBLESHOOTING.md for production details.

Development Rules

  • .cursor/rules/ – Rules for LLM assistants
  • docs/ – Architecture, deployment, troubleshooting

Key principles: 100% Laravel API compatibility, layered architecture (handler/service/repository), dependency injection, proper error handling.

License

Proprietary - MetaRGB Platform