Telepesa is a modular, microservices-based digital banking platform. It provides secure, scalable services for user management, accounts, transactions, loans, notifications, transfers, and bill payments, routed through a centralized API Gateway and discovered via Eureka.
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ TELEPESA ARCHITECTURE │
└─────────────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────┐
│ Web Frontend │
│ (React/TypeScript)│
│ localhost:5174 │
└──────────┬──────────┘
│ HTTPS/CORS
│
┌──────────▼──────────┐
│ API Gateway │
│ (Spring Gateway) │
│ localhost:8080 │
└──────────┬──────────┘
│
┌────────────────────┼────────────────────┐
│ │ │
┌──────────▼─────────┐ ┌────────▼────────┐ ┌────────▼────────┐
│ Eureka Server │ │ Infrastructure │ │ Monitoring │
│ (Service Discovery)│ │ │ │ │
│ localhost:8761 │ │ PostgreSQL:5432 │ │ Zipkin:9411 │
└────────────────────┘ │ Redis:6379 │ │ Kafka:9092 │
│ MongoDB:27017 │ └─────────────────┘
│ ZooKeeper:2181 │
└──────────────────┘
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ MICROSERVICES LAYER │
├─────────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ User Service │ │ Account Service │ │Transaction Svc │ │ Loan Service │ │
│ │ Port: 8081 │ │ Port: 8082 │ │ Port: 8083 │ │ Port: 8084 │ │
│ │ │ │ │ │ │ │ │ │
│ │ • Authentication│ │ • Account CRUD │ │ • Txn Processing│ │ • Loan Apps │ │
│ │ • JWT Tokens │ │ • Balance Mgmt │ │ • History │ │ • Credit Checks │ │
│ │ • User Profiles │ │ • Account Types │ │ • Audit Logs │ │ • Repayment │ │
│ │ • Security │ │ • Statements │ │ • Reconciliation│ │ • Collateral │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │Notification Svc │ │ Transfer Service│ │Bill Payment Svc │ │
│ │ Port: 8085 │ │ Port: 8086 │ │ Port: 8087 │ │
│ │ │ │ │ │ │ │
│ │ • Email/SMS │ │ • Fund Transfers│ │ • Utility Bills │ │
│ │ • Push Notify │ │ • Inter-bank │ │ • Telecom │ │
│ │ • Templates │ │ • Fee Calc │ │ • Entertainment │ │
│ │ • Audit Trail │ │ • Limits │ │ • Biller Mgmt │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────┐
│ DATA LAYER │
├─────────────────────────────┤
│ │
│ • PostgreSQL (Primary) │
│ - User data │
│ - Account data │
│ - Transaction records │
│ - Loan information │
│ │
│ • Redis (Cache & Sessions) │
│ - JWT tokens │
│ - Rate limiting │
│ - Temporary data │
│ │
│ • MongoDB (Notifications) │
│ - Email templates │
│ - Notification history │
│ - Message queues │
│ │
│ • Kafka (Event Streaming) │
│ - Transaction events │
│ - Audit trails │
│ - Inter-service comms │
│ │
└─────────────────────────────┘
- Language/Framework: Java 17, Spring Boot 3.4
- Service Discovery: Netflix Eureka
- API Gateway: Spring Cloud Gateway
- Datastores: PostgreSQL (primary), Redis (cache), MongoDB (notifications)
- Messaging/Tracing: Kafka, Zipkin
- Auth: Spring Security + JWT
- Docs: OpenAPI/Swagger
- Containers: Docker
- Frontend: React + TypeScript + Vite
- API Gateway: 8080
- Eureka Server: 8761
- User Service: 8081
- Account Service: 8082
- Transaction Service: 8083
- Loan Service: 8084
- Notification Service: 8085
- Transfer Service: 8086
- Bill Payment Service: 8087
Prerequisites: Docker Desktop or Docker Engine.
- Build shared libraries (first time only)
cd Backend/shared-libraries
mvn -q -DskipTests clean install- Start core infrastructure and services
cd Backend/docker-compose
# Starts infra + gateway + Eureka + transfer-service + bill-payment-service
docker compose -f docker-compose.yml up -d \
zookeeper kafka postgres redis zipkin eureka-server api-gateway \
transfer-service bill-payment-service- Verify health
# Eureka UI
open http://localhost:8761
# API Gateway health
curl -fsS http://localhost:8080/actuator/health | jq
# Transfer Service health (via service)
curl -fsS http://localhost:8086/actuator/health | jq
# Bill Payment Service health (via service)
curl -fsS http://localhost:8087/actuator/health | jqNotes
- All services register with Eureka and are routed via the API Gateway under /api/v1/**.
- Per-service PostgreSQL databases are created by docker-compose init scripts.
- Users: /api/v1/users/**
- Accounts: /api/v1/accounts/**
- Transactions: /api/v1/transactions/**
- Loans: /api/v1/loans/**
- Notifications: /api/v1/notifications/**
- Transfers: /api/v1/transfers/**
- Bills: /api/v1/bills/**
- Each service can be run with:
mvn spring-boot:run -Dspring-boot.run.profiles=dev - Recommended to run Eureka and API Gateway first, then dependent services.
cd Backend
mvn -q clean test
# Or run realistic E2E infra/gateway tests
bash Backend/scripts/realistic-e2e-test.shPostman collection: Backend/Telepesa_API_Collection_Complete.postman_collection.json
Docker Hub (Recommended):
# Repository Secrets Required:
DOCKER_USERNAME=<your-dockerhub-username>
DOCKER_PASSWORD=<your-dockerhub-token>GitHub Container Registry (Alternative):
# Repository Secret Required:
GHCR_PAT=<github-personal-access-token>
# Token needs: write:packages, read:packagesCoverage Reports (Optional but Recommended):
# Repository Secret Required:
CODECOV_TOKEN=<your-codecov-upload-token>
# Get token from: https://codecov.io/gh/YOUR_USERNAME/YOUR_REPOSetup Steps:
- Visit codecov.io and sign up with GitHub
- Add your repository to Codecov
- Copy the upload token from repository settings
- Add
CODECOV_TOKENto your GitHub repository secrets - Coverage reports will be automatically uploaded on each CI run
- Code Coverage: >80% target across all services
- Security Scanning: Automated vulnerability detection
- Bundle Size: Frontend <5MB JavaScript bundle limit
- Build Time: Average <10 minutes per pipeline
- Deployment: Zero-downtime with health checks
The Telepesa web application provides a modern, responsive interface for all banking operations. Here are screenshots showcasing the key features:
Login Page |
Register Account |
Dashboard Home |
Accounts Interface |
Transfer Form |
Bill Payments |
Bill Payments |
Loan Details |
Loan Details |
My Loan Status |
Loan Calculator |
Profile Settings |
Profile Settings |
Security Settings |
Security Settings |
Help & Support |
- Secure Authentication: JWT-based login with session management
- Real-time Dashboard: Account balances, recent transactions, and quick actions
- Money Transfers: Internal and external transfers with real-time processing
- Bill Payments: Utility bills, telecom, and entertainment payments
- Responsive Design: Optimized for desktop, tablet, and mobile devices
- Transaction Search: Advanced filtering and search capabilities
- Notifications: Real-time alerts and notification management
- Account Management: Profile settings, security preferences, and preferences
- Backend/docs contains detailed guides for architecture, security, and testing.
- Each service exposes Swagger UI at
http://localhost:<port>/swagger-ui.html. - Frontend web app: http://localhost:5174/ (React + TypeScript)
MIT License. See LICENSE for details.