E-Bike Rental System

A comprehensive electric bike rental platform built with Ballerina microservices architecture and a modern React frontend. The system provides bike sharing capabilities with real-time tracking, payment processing, review management, and notification services.

Development Organization

This project was developed by Team OrByte under the Team-OrByte GitHub Organization. All development activities, including individual service repositories, CI/CD workflows, and deployment pipelines, are maintained within this organization. Each microservice has its own repository with comprehensive documentation, automated builds..

System Architecture

View on Eraser

The application follows a microservices architecture with the following components:

Backend Services (Ballerina)

• Auth Service: JWT-based authentication and authorization
• User Service: User profile and account management
• Bike Service: Bike fleet management and reservation system
• Ride Service: Ride lifecycle management with real-time tracking
• Payment Service: Stripe integration for payment processing
• Review Service: User review and rating system
• Reward Service: Loyalty program and rewards management
• Notification Service: Real-time notifications and messaging

How We Used Ballerina

We utilized Ballerina extensively for microservices orchestration, API integration, cloud-native development, and event-driven architecture to create a seamless, scalable, and maintainable bike rental ecosystem. Ballerina's built-in cloud connectors, type-safe data binding, and native support for distributed systems simplified the complexity of managing inter-service communication, data persistence, and real-time event processing across our entire platform.

Ballerina Packages and Libraries Used

Our E-Bike Rental System leverages numerous Ballerina packages to implement comprehensive functionality:

Core Ballerina Libraries

• ballerina/http: RESTful API development and HTTP client/server implementation
• ballerina/websocket: Real-time communication for live tracking and notifications
• ballerina/jwt: JWT token issuance, validation, and authentication
• ballerina/crypto: Password hashing and cryptographic operations
• ballerina/log: Structured logging and observability
• ballerina/time: Time and date operations for scheduling and timestamps
• ballerina/uuid: Unique identifier generation for entities
• ballerina/sql: SQL query building and database operations
• ballerina/persist: ORM-like data persistence layer
• ballerina/io: Input/output operations and data streaming

External Connectors (ballerinax)

• ballerinax/kafka: Apache Kafka integration for event-driven architecture
• ballerinax/postgresql: PostgreSQL database connectivity and operations
• ballerinax/mongodb: MongoDB integration for document storage
• ballerinax/stripe: Stripe payment processing integration
• ballerinax/persist.sql: SQL persistence layer implementation

Frontend Application (React + TypeScript)

• Modern web interface built with Vite and TailwindCSS
• Real-time ride tracking with maps integration
• Admin dashboard for fleet management
• User portal for bike rentals and account management

Infrastructure

• API Gateway: Nginx reverse proxy for service routing
• Message Queue: Apache Kafka for event-driven communication
• Databases: PostgreSQL for transactional data, MongoDB for document storage
• Container Orchestration: Docker Compose for local deployment

Prerequisites

Before running the application, ensure you have the following installed:

• Docker Engine (v20.0+)
• Docker Compose (v2.0+)
• Node.js (v20.0+)
• Yarn package manager

Quick Start

1. Clone the Repository

git clone https://github.com/TheTharz/iwb25-262-orbyte
cd iwb25-262-orbyte

2. Configure Environment Variables

Cloudinary Setup (Required for image uploads)

1. Create an account at Cloudinary

2. Navigate to your dashboard to get the Cloud Name

3. Create an upload preset:

   • Go to Settings → Upload → Upload Presets
   • Create a new preset (e.g., ebike-image-store)
   • Set it as an unsigned preset for direct frontend uploads

4. Create environment file for the frontend:

cd e-bike-rental-client
cp env.example .env

5. Update the .env file with your Cloudinary credentials:

VITE_CLOUDINARY_CLOUD_NAME=your-cloud-name
VITE_CLOUDINARY_UPLOAD_PRESET=your-upload-preset

Stripe Configuration (Required for payments)

1. Create a Stripe account and obtain your Secret Key from the dashboard
2. Configure the payment service:

cd deployment/payment-service

3. Update Config.toml with your Stripe secret key:

stripeSecretKey = "sk_test_your_stripe_secret_key_here"

3. Start Backend Services

cd deployment
docker compose pull
docker compose up -d

Wait approximately 2-3 minutes for all services to initialize and establish database connections.

4. Start Frontend Application

cd e-bike-rental-client
yarn install
yarn dev

5. Access the Application

• Frontend: http://localhost:5173
• API Gateway: http://localhost:8080
• Backend Services: Available through API Gateway routes

API Documentation

The system exposes the following API endpoints through the Nginx gateway:

Service	Route	Internal Port	Description
Auth Service	/auth-api/*	8080	Authentication endpoints
User Service	/user-api/*	5000	User management
Bike Service	/bike-api/*	8090	Bike fleet operations
Ride Service	/ride-api/*	8082	Ride management
Payment Service	/payment-api/*	9090	Payment processing
Review Service	/review-api/*	8090	Review management
Reward Service	/reward-api/*	9092	Rewards system
Notification Service	/notification-api/*	8084	Notifications

Development Setup

Local Development Configuration

For local development, update the database host configurations in each service's Config.toml:

[service_name.repository]
host = "localhost"
port = 5432

Stripe Webhook Configuration

Development Environment

Use Stripe CLI to forward webhook events:

stripe listen --forward-to localhost:8080/payment-api/webhook

Production Environment

1. Deploy services to a publicly accessible server
2. Configure webhook endpoint in Stripe Dashboard:
   • Go to Developers → Webhooks → Add Endpoint
   • URL: https://yourdomain.com/payment-api/webhook
   • Events: checkout.session.completed, payment_intent.payment_failed

Service Dependencies

The deployment includes the following infrastructure components:

Databases

• PostgreSQL: Used by Auth, User, Bike, Ride, and Review services
• MongoDB: Used by Payment, Reward, and Notification services

Message Broker

• Apache Kafka: Handles event-driven communication between services

Load Balancer

• Nginx: API Gateway for request routing and CORS handling

Troubleshooting

Common Issues

1. Port Conflicts: Ensure port 8080 is available for the API Gateway
2. Database Connection Issues: Wait for database initialization to complete
3. Kafka Connection: Verify Kafka is running and accessible to dependent services
4. Environment Variables: Ensure all required configuration files are properly set

Service Health Checks

Monitor service health through Docker logs:

docker compose logs -f [service_name]

Data Persistence

The system uses Docker volumes for data persistence. To reset the system:

docker compose down -v
docker compose up -d

Security Considerations

• JWT tokens are used for service-to-service authentication
• All services validate JWT tokens using shared public/private key pairs
• Database credentials are environment-specific and should be secured in production
• API Gateway implements CORS policies for frontend access

Deployment Notes

Identified Deployment Flows

1. Missing Service Dependencies: Some services may start before their dependencies are ready
2. Configuration Management: Environment-specific configurations need proper templating
3. Health Check Implementation: Services lack proper health check endpoints for orchestration
4. Secret Management: Sensitive credentials are stored in plain text configuration files
5. Network Security: Default passwords and open database ports in development configuration

Production Recommendations

1. Implement Kubernetes for better orchestration and scaling
2. Use secret management solutions (e.g., HashiCorp Vault, Kubernetes Secrets)
3. Add health check endpoints to all services
4. Implement service mesh for better traffic management
5. Use environment-specific configuration management tools
6. Set up monitoring and logging aggregation
7. Implement backup and disaster recovery procedures