This project is an example implementation of a payment gateway system built with Rust, featuring a modular monolith architecture. It simulates a complete digital financial transaction process, including user management, digital wallets, and various transaction types (top-up, transfer, withdrawal).
The primary goal is to provide a comprehensive, real-world reference for building robust, scalable, and observable systems using Rust's modern ecosystem.
- ✅ JWT Authentication with refresh tokens
- ✅ Role-Based Access Control (RBAC)
- ✅ Digital Wallet Management
- ✅ Complete Transaction Lifecycle (Top-up, Transfer, Withdraw, Payment)
- ✅ Payment Card Management
- ✅ Merchant API Key Management
- ✅ Comprehensive Observability with metrics, logging, and distributed tracing
- ✅ Containerized Deployment with Docker and Kubernetes
- ✅ API Documentation with Swagger UI
The system uses a modular monolith architecture where an API Gateway serves as the single entry point. Each business domain is separated into an independent Rust crate (module), and all inter-module communication is handled via gRPC for high performance and type safety.
graph TD
subgraph "Clients (Web/Mobile/CLI)"
A[End User or API Client]
end
subgraph "Payment Gateway System"
B(API Gateway <br> HTTP/REST)
subgraph "Internal gRPC Services (Modules)"
C[Auth Service]
D[User Service]
E[Card Service]
F[Saldo Service]
G[Merchant Service]
H[Role Service]
I[Topup Service]
J[Transaction Service]
K[Transfer Service]
L[Withdraw Service]
end
M[(Database <br> PostgreSQL)]
N[(Cache <br> Redis)]
end
A --> B
B -- gRPC --> C
B -- gRPC --> D
B -- gRPC --> E
B -- gRPC --> F
B -- gRPC --> G
B -- gRPC --> H
B -- gRPC --> I
B -- gRPC --> J
B -- gRPC --> K
B -- gRPC --> L
C --> M & N
D --> M
E --> M
F --> M
G --> M
H --> M
I --> M
J --> M
K --> M
L --> M
| Category | Technology |
|---|---|
| Language | Rust (Stable) |
| Async Runtime | tokio |
| Web Framework | axum (for API Gateway) |
| Inter-service | tonic (gRPC), prost (Protobuf) |
| Database | PostgreSQL |
| ORM / DB Driver | sqlx |
| Cache | Redis |
| Containerization | Docker, Docker Compose |
| Orchestration | Kubernetes (Minikube for local setup) |
| Observability | OpenTelemetry, Prometheus (metrics), Grafana (dashboards), Jaeger (tracing), Loki (logs) |
- Docker and Docker Compose
sqlx-clifor database migrations.- (Optional, for K8s) Minikube and kubectl.
This is the fastest way to get the entire system running on your local machine.
-
Clone the Repository
git clone https://github.com/MamangRust/example-payment-gateway-sqlx.git cd example-payment-gateway-sqlx/backend -
Configure Environment
Review the
.envfile and ensure the settings (especiallyDATABASE_URL) match the configuration indocker-compose.yml. The defaults should work out of the box. -
Run the Database Migration
Before starting the services, you need to set up the database schema.
First, start the database container:
docker-compose up -d db
Wait a few seconds for it to initialize, then run the migrations:
# Ensure your .env file is present in the current directory sqlx migrate run -
Start All Services
Now, bring up the entire stack, including all application services and the observability suite.
docker-compose up -d
The application services use pre-built images from
ghcr.io. If you want to use your local code changes, you must first build the images using the./build-docker-images.shscript. -
Access the System
- API Gateway / Swagger UI:
http://localhost:5000/swagger-ui/ - See the Observability section below for more URLs.
- API Gateway / Swagger UI:
This method simulates a production-like deployment on a local Kubernetes cluster.
-
Clone the Repository
git clone https://github.com/MamangRust/example-payment-gateway-sqlx.git cd example-payment-gateway-sqlx/backend -
Build Local Docker Images
The Kubernetes manifests are configured to use local images. Run the build script to create them.
./build-docker-images.sh
-
Run the Minikube Setup Script
This script will:
- Start Minikube (if not already running).
- Load the necessary Docker images into Minikube's context.
- Apply all Kubernetes manifests for databases, observability, and application services.
./k8s/scripts/setup-minikube.sh
-
Access the System
The script will output all the access URLs. The application will be available via a NodePort on your Minikube IP. Example:
- Main Application:
http://<MINIKUBE_IP>:30080 - Grafana:
http:// 97D8 <MINIKUBE_IP>:30030 - Jaeger:
http://<MINIKUBE_IP>:31686
- Main Application:
The docker-compose and minikube setups include a full observability stack. Here’s how to access the different tools when running with Docker Compose:
| Service | URL | Description |
|---|---|---|
| Grafana | http://localhost:3000 |
Dashboards for metrics and logs. (Login: admin/admin) |
| Prometheus | http://localhost:9090 |
Time-series database for metrics. |
| Jaeger | http://localhost:16686 |
Distributed tracing UI. |
| Loki | http://localhost:3100 |
Log aggregation system. |
| Alertmanager | http://localhost:9093 |
Manages alerts sent by Prometheus. |
The API Gateway provides OpenAPI documentation via Swagger UI. Once the system is running, you can access it at:
http://localhost:5000/swagger-ui/
crates/: Contains all the independent Rust modules (services).apigateway: The public-facing REST API gateway.auth,user,card, etc.: Internal services, each representing a business domain.genproto: Crate for compiling.protofiles into Rust code for gRPC.
proto/: Protobuf definition files.migrations/: SQLx database migrations.docker-compose.yml: Defines the local development environment.k8s/: Contains all Kubernetes manifests for deployment.observability/: Configuration files for Prometheus, Grafana, Loki, etc.
Manual Installation (Without Containers)
- Rust & Cargo
sqlx-cliprotoc- A running PostgreSQL instance.
-
Clone Repository
git clone https://github.com/MamangRust/example-payment-gateway-sqlx.git cd example-payment-gateway-sqlx/backend -
Setup Environment Create and edit an
.envfile with your database configuration. -
Database Migration
sqlx migrate run
-
Build Protobuf
cargo build -p genproto
-
Build All Services
cargo build --workspace
You need to run each service in a separate terminal.
# Terminal 1: API Gateway
cargo run -p apigateway
# Terminal 2: Auth Service
cargo run -p auth
# ... and so on for every other service in the `crates` directory.Jaeger UI
Node Exporter
Monitoring Memory
Monitoring Card Service
Monitoring Merchant Service
Monitoring User Service
Monitoring Role Service
Monitoring Saldo Service
Monitoring Topup Service
Monitoring Transaction Service
Monitoring Transfer Service
Monitoring Withdraw Service