Superapp E-Commerce & Mobility Platform

A modern cloud-native microservices architecture inspired by Snapp, built with Go, Java, Kubernetes, Helm, GitOps (Argo CD), and GitHub Actions.

🏗️ Architecture Overview

This platform implements a complete multi-service superapp backend with:

• Microservices (Go + Java)
• API Gateway (Kong)
• Event-driven communication (Kafka)
• CI/CD (GitHub Actions)
• GitOps deployment (Argo CD)
• Kubernetes manifests + Helm charts
• Observability (Prometheus, Grafana, Jaeger)

📐 Architecture Diagram

graph TB
    subgraph "Client Layer"
        Mobile[Mobile App]
        Web[Web App]
    end
    
    subgraph "API Gateway"
        Kong[Kong Gateway]
    end
    
    subgraph "Microservices - Java"
        Auth[Auth Service<br/>Spring Boot]
        Payment[Payment Service<br/>Spring Boot]
    end
    
    subgraph "Microservices - Go"
        Passenger[Passenger Service<br/>Go]
        Driver[Driver Service<br/>Go]
        Food[Food Service<br/>Go]
        Market[Market Service<br/>Go]
        Notification[Notification Service<br/>Go]
    end
    
    subgraph "Event Bus"
        Kafka[Apache Kafka]
    end
    
    subgraph "Data Layer"
        PgAuth[(PostgreSQL<br/>Auth)]
        PgPayment[(PostgreSQL<br/>Payment)]
        PgPassenger[(PostgreSQL<br/>Passenger)]
        PgDriver[(PostgreSQL<br/>Driver)]
        PgFood[(PostgreSQL<br/>Food)]
        PgMarket[(PostgreSQL<br/>Market)]
    end
    
    subgraph "Observability"
        Prometheus[Prometheus]
        Grafana[Grafana]
        Jaeger[Jaeger]
    end
    
    Mobile --> Kong
    Web --> Kong
    Kong --> Auth
    Kong --> Payment
    Kong --> Passenger
    Kong --> Driver
    Kong --> Food
    Kong --> Market
    
    Auth --> PgAuth
    Payment --> PgPayment
    Passenger --> PgPassenger
    Driver --> PgDriver
    Food --> PgFood
    Market --> PgMarket
    
    Passenger --> Kafka
    Driver --> Kafka
    Payment --> Kafka
    Food --> Kafka
    Market --> Kafka
    
    Kafka --> Notification
    
    Auth -.metrics.-> Prometheus
    Payment -.metrics.-> Prometheus
    Passenger -.metrics.-> Prometheus
    Driver -.metrics.-> Prometheus
    Food -.metrics.-> Prometheus
    Market -.metrics.-> Prometheus
    Notification -.metrics.-> Prometheus
    
    Prometheus --> Grafana
    Auth -.traces.-> Jaeger
    Payment -.traces.-> Jaeger
    Passenger -.traces.-> Jaeger

Loading

🧩 Services

Java Services

Auth Service

• Technology: Spring Boot 3.2, Java 17
• Endpoints:
  • POST /auth/register - User registration
  • POST /auth/login - User login
  • POST /auth/refresh - Refresh JWT token
• Features:
  • JWT authentication
  • User profiles
  • Roles & permissions (USER, DRIVER, ADMIN, MERCHANT)
  • PostgreSQL database
  • Prometheus metrics

Payment Service

• Technology: Spring Boot 3.2, Java 17
• Endpoints:
  • POST /payment/process - Process payment
  • POST /payment/refund - Refund payment
  • GET /payment/wallet/{userId} - Get wallet balance
  • POST /payment/wallet/{userId}/topup - Top up wallet
• Features:
  • Wallet management
  • Installments support
  • Refunds
  • Payment events → Kafka topic payment_events
  • Prometheus metrics

Go Services

Passenger Service

• Technology: Go 1.21, Gin, PostgreSQL
• Endpoints:
  • POST /passenger/rides - Request ride
  • GET /passenger/rides/{id} - Get ride details
  • GET /passenger/rides/user/{userId} - Get user rides
• Features:
  • Ride request management
  • Track ride status
  • Publish events → Kafka topic ride_events
  • Prometheus metrics
  • OpenTelemetry tracing

Driver Service

• Technology: Go 1.21, Gin, PostgreSQL
• Endpoints:
  • POST /driver/availability - Update driver availability
  • GET /driver/{userId} - Get driver info
  • POST /driver/accept-ride - Accept ride
  • GET /driver/available - Get available drivers
• Features:
  • Driver availability management
  • Accept rides
  • Update trip status
  • Publish events → Kafka topic driver_events
  • Prometheus metrics
  • OpenTelemetry tracing

Food Service

• Technology: Go 1.21, Gin, PostgreSQL
• Endpoints:
  • GET /food/restaurants - List restaurants
  • GET /food/restaurants/{id}/menu - Get restaurant menu
  • POST /food/orders - Create order
  • GET /food/orders/{id} - Get order details
• Features:
  • Restaurant management
  • Menu management
  • Order processing
  • Publish events → Kafka topic order_events
  • Prometheus metrics

Market Service

• Technology: Go 1.21, Gin, PostgreSQL
• Endpoints:
  • GET /market/products - List products
  • GET /market/products/{id} - Get product details
  • POST /market/orders - Create order
  • GET /market/orders/{id} - Get order details
• Features:
  • Product catalog
  • Inventory management
  • Order processing
  • Publish events → Kafka topic order_events
  • Prometheus metrics

Notification Service

• Technology: Go 1.21, Kafka Consumer
• Features:
  • Consumes Kafka events from multiple topics
  • Sends SMS/Email/Push notifications
  • Async worker pattern
  • Prometheus metrics

🚪 API Gateway

Kong Gateway provides:

• Routes:

  • /auth/* → auth-service
  • /passenger/* → passenger-service
  • /driver/* → driver-service
  • /food/* → food-service
  • /market/* → market-service
  • /payment/* → payment-service

• Features:

  • Rate limiting
  • CORS support
  • JWT validation (if configured)
  • Tracing headers
  • Load balancing

🔄 Event Bus

Apache Kafka topics:

• ride_events - Ride-related events
• driver_events - Driver-related events
• payment_events - Payment-related events
• order_events - Order-related events (food & market)

🚀 CI/CD Pipeline

GitHub Actions Workflow

graph LR
    A[Code Push] --> B[Detect Changes]
    B --> C{Service Type?}
    C -->|Java| D[Run Java Tests]
    C -->|Go| E[Run Go Tests]
    D --> F[Build Docker Image]
    E --> F
    F --> G[Push to GHCR]
    G --> H[Update Helm Values]
    H --> I[Commit Changes]
    I --> J[Argo CD Auto-Sync]
    J --> K[Deploy to K8s]

Loading

Pipeline Steps:

1. Detect Changed Services: Identifies which services have been modified
2. Run Tests:
   • Java services: Maven tests
   • Go services: go test
3. Build Docker Images: Multi-stage builds for all services
4. Push to GitHub Container Registry: Tagged with commit SHA
5. Update Helm Values: Automatically updates values.yaml with new image tags
6. Commit Changes: Commits updated Helm values back to repo
7. Argo CD Auto-Sync: Automatically deploys to Kubernetes

🎯 GitOps with Argo CD

Application Structure

Each service has three Argo CD applications (one per environment):

• {service}-dev.yaml - Development environment
• {service}-staging.yaml - Staging environment
• {service}-prod.yaml - Production environment

Features

• Auto-sync enabled: Automatic deployment on changes
• Prune: Removes resources not in Git
• Self-heal: Automatically corrects drift
• Namespace creation: Creates namespaces if they don't exist

Deploying with Argo CD

1. Install Argo CD (if not already installed):

   kubectl create namespace argocd
   kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

2. Apply Argo CD Applications:

   kubectl apply -f deploy/argocd-apps/

3. Access Argo CD UI:

   kubectl port-forward svc/argocd-server -n argocd 8080:443

   Open https://localhost:8080 (default credentials: admin / password from secret)

📊 Observability

Prometheus Metrics

All services expose Prometheus metrics at /metrics:

• Java Services: Micrometer metrics
• Go Services: Prometheus client library metrics

Metrics Examples

• auth_login_total - Total login attempts
• payment_total - Total payments processed
• ride_requests_total - Total ride requests
• driver_actions_total - Total driver actions
• food_orders_total - Total food orders
• notifications_sent_total - Total notifications sent

Tracing

OpenTelemetry integration for distributed tracing:

• Java Services: OpenTelemetry Spring Boot Starter
• Go Services: OpenTelemetry Go SDK
• Backend: Jaeger for trace collection and visualization

Logging

• Structured logging in all services
• Log aggregation with Loki or ELK stack
• Centralized log management

🧪 Local Development

Prerequisites

• Docker & Docker Compose
• Go 1.21+
• Java 17+
• Maven 3.9+
• Make

Start Infrastructure

# Start PostgreSQL and Kafka
make local-up

# Or manually:
docker-compose up -d

Build Services

# Build all services
make build

# Build Java services only
make build-java

# Build Go services only
make build-go

Run Tests

# Run all tests
make test

# Run Java tests only
make test-java

# Run Go tests only
make test-go

Run Services Locally

Auth Service

cd services/auth-service-java
mvn spring-boot:run

Payment Service

cd services/payment-service-java
mvn spring-boot:run

Passenger Service

cd services/passenger-service-go
go run main.go

Driver Service

cd services/driver-service-go
go run main.go

Food Service

cd services/food-service-go
go run main.go

Market Service

cd services/market-service-go
go run main.go

Notification Service

cd services/notification-service-go
go run main.go

Environment Variables

Set these environment variables for local development:

# Database
export DB_HOST=localhost
export DB_PORT=5432
export DB_USER=postgres
export DB_PASSWORD=postgres

# Kafka
export KAFKA_BOOTSTRAP_SERVERS=localhost:9092

# JWT (for auth service)
export JWT_SECRET=your-secret-key-here

📦 Deployment

Using Helm

# Install a service
helm install auth-service deploy/helm/auth-service

# Upgrade a service
helm upgrade auth-service deploy/helm/auth-service

# Uninstall a service
helm uninstall auth-service

Using Argo CD

1. Ensure Argo CD is installed and configured
2. Apply application manifests:

   kubectl apply -f deploy/argocd-apps/

3. Argo CD will automatically sync and deploy

Kubernetes Namespaces

Create namespaces:

kubectl apply -f deploy/k8s-base/namespaces.yaml

This creates:

• dev - Development environment
• staging - Staging environment
• prod - Production environment
• argocd - Argo CD namespace

📁 Repository Structure

superapp-ecommerce/
├── services/
│   ├── auth-service-java/          # Java + Spring Boot
│   ├── payment-service-java/        # Java + Spring Boot
│   ├── passenger-service-go/        # Go service
│   ├── driver-service-go/           # Go service
│   ├── food-service-go/             # Go service
│   ├── market-service-go/           # Go service
│   └── notification-service-go/      # Go service
├── deploy/
│   ├── helm/                        # Helm charts
│   │   ├── auth-service/
│   │   ├── payment-service/
│   │   ├── passenger-service/
│   │   ├── driver-service/
│   │   ├── food-service/
│   │   ├── market-service/
│   │   ├── notification-service/
│   │   └── api-gateway/
│   ├── argocd-apps/                 # Argo CD applications
│   └── k8s-base/                    # Base Kubernetes manifests
│       ├── namespaces.yaml
│       ├── ingress-base.yaml
│       └── monitoring/
├── scripts/
│   ├── detect_changed_services.sh
│   └── update_helm_values.sh
├── .github/workflows/
│   └── ci.yml                       # CI/CD pipeline
├── docker-compose.yml               # Local development
├── Makefile                         # Build automation
└── README.md

🔧 Configuration

Helm Values

Each service has a values.yaml file in deploy/helm/{service}/ with:

• Image repository and tag
• Replica count
• Resource limits/requests
• Environment variables
• Autoscaling configuration

Environment-Specific Configuration

Argo CD applications override values per environment:

• Dev: Lower replica count, latest dev images
• Staging: Medium replica count, staging images
• Prod: Higher replica count, production images

🛠️ Scripts

detect_changed_services.sh

Detects which services have changed between commits:

./scripts/detect_changed_services.sh HEAD~1 HEAD

update_helm_values.sh

Updates Helm values with new image tag:

./scripts/update_helm_values.sh auth-service v1.0.0

📈 Monitoring & Alerting

Prometheus

• Scrapes metrics from all services
• Service discovery via Kubernetes
• Configurable scrape intervals

Grafana

• Pre-built dashboards for:
  • Service health
  • Request rates
  • Error rates
  • Response times
  • Resource utilization

Jaeger

• Distributed tracing
• Service dependency mapping
• Performance analysis

🔒 Security

• JWT Authentication: Secure token-based auth
• RBAC: Role-based access control
• Secrets Management: Kubernetes secrets (consider using external secret management)
• Network Policies: Isolate services (recommended)
• TLS: Encrypted communication

🚧 Roadmap

• Add service mesh (Istio/Linkerd)
• Implement circuit breakers
• Add API versioning
• Implement caching layer (Redis)
• Add comprehensive integration tests
• Implement blue-green deployments
• Add chaos engineering tests

📝 License

This project is licensed under the MIT License.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📧 Contact

For questions or support, please open an issue in the repository.

---

Built with ❤️ for cloud-native microservices