UniCarpool 🚗

A comprehensive carpooling application designed specifically for university students, providing secure and efficient ride-sharing services within the campus community.

📋 Table of Contents

• Overview
• Features
• Technology Stack
• Project Structure
• Quick Start
• API Documentation
• Development
• Deployment
• Testing
• Contributing
• License

🎯 Overview

UniCarpool is a full-stack mobile application that facilitates carpooling among university students. The platform connects drivers and riders, enabling cost-effective and environmentally friendly transportation solutions for the campus community.

Key Benefits

• Cost Reduction: Share transportation costs among students
• Environmental Impact: Reduce carbon footprint through shared rides
• Safety: Built-in emergency protocols and user verification
• Convenience: Easy-to-use mobile interface with real-time notifications
• Community: Connect with fellow students and build campus relationships

✨ Features

🔐 Authentication & Security

• JWT-based secure authentication
• Email verification system
• Password recovery and reset functionality
• Role-based access control (Driver/Rider)

🚗 Ride Management

• For Drivers:

  • Create and manage rides
  • Set departure times, locations, and conditions
  • Accept/reject ride requests
  • Update ride status (Active, Completed, Cancelled)
  • Manage driver availability for cab bookings

• For Riders:

  • Browse and search available rides
  • Request to join rides
  • Track booking status
  • View ride history

📱 User Experience

• Intuitive mobile interface built with React Native
• Real-time ride updates and notifications
• Profile management and customization
• Rating and review system for completed rides

🆘 Emergency Features

• SOS alert system
• Emergency contact management
• Automatic notifications to emergency contacts and drivers
• Safety protocols for ride sharing

🚕 Additional Services

• Cab booking system for immediate transportation needs
• Alternative transportation options
• Driver availability management

📧 Communication

• Automated email notifications
• Ride status updates
• Emergency alert notifications
• Password recovery emails

🛠 Technology Stack

Backend (Spring Boot)

• Framework: Spring Boot 3.5.6
• Language: Java 23
• Build Tool: Gradle 8.14.3
• Database: MySQL 8.0.30
• Security: Spring Security + JWT
• Email: Spring Boot Mail + Thymeleaf
• Testing: JUnit 5, Mockito (140 total tests)

Frontend (React Native)

• Framework: React Native 0.81.5
• Platform: Expo ~54.0.20
• Navigation: Expo Router ~6.0.13
• Language: TypeScript ~5.9.2
• HTTP Client: Axios ^1.13.1
• UI Components: Custom components + Expo Vector Icons

DevOps & Deployment

• Containerization: Docker + Docker Compose
• CI/CD: GitLab CI/CD
• Web Server: Nginx (production)
• SSL: Let's Encrypt certificates
• Process Management: systemd

📁 Project Structure

unicarpool/
├── unicarpool-backend/           # Spring Boot REST API
│   ├── src/main/java/           # Java source code
│   │   └── com/asdc/unicarpool/
│   │       ├── config/          # Configuration classes
│   │       ├── controller/      # REST controllers
│   │       ├── dto/             # Data Transfer Objects
│   │       ├── model/           # JPA entities
│   │       ├── repository/      # Data repositories
│   │       ├── service/         # Business logic
│   │       └── util/            # Utility classes
│   ├── src/test/                # Test classes
│   ├── docs/                    # Documentation
│   ├── docker-compose/          # Docker configurations
│   ├── db-migration/            # Database scripts
│   └── ci-cd/                   # CI/CD configurations
│
├── unicarpool-frontend/         # React Native mobile app
│   ├── app/                     # Screen components (Expo Router)
│   │   ├── (tabs)/             # Tab navigation screens
│   │   ├── login.tsx           # Authentication screens
│   │   └── _layout.tsx         # Layout configuration
│   ├── src/
│   │   ├── components/         # Reusable UI components
│   │   ├── services/           # API services
│   │   ├── contexts/           # React contexts
│   │   ├── hooks/              # Custom hooks
│   │   ├── types/              # TypeScript definitions
│   │   └── styles/             # Styling
│   ├── assets/                 # Static assets
│   └── android/                # Android-specific files
│
└── README.md                   # This file

🚀 Quick Start

Prerequisites

Backend Requirements:

• Java Development Kit (JDK) 23+
• Gradle 8.14.3+
• MySQL 8.0+
• Docker (optional)

Frontend Requirements:

• Node.js 18.0.0+
• npm 9.0.0+ or yarn
• Android Studio (for Android development)
• Xcode (for iOS development, macOS only)

Installation

1. Clone the repository

   git clone <repository-url>
   cd unicarpool

2. Backend Setup

   cd unicarpool-backend
   
   # Set up MySQL database
   mysql -u root -p
   CREATE DATABASE unicarpool;
   CREATE USER 'unicarpool_user'@'localhost' IDENTIFIED BY 'your_password';
   GRANT ALL PRIVILEGES ON unicarpool.* TO 'unicarpool_user'@'localhost';
   
   # Run database migration
   mysql -u unicarpool_user -p unicarpool < db-migration/db_migration.sql
   
   # Configure application properties
   # Edit src/main/resources/application.properties
   
   # Build and run
   ./gradlew bootRun

3. Frontend Setup

   cd unicarpool-frontend
   
   # Install dependencies
   npm install
   
   # Start development server
   npm start
   
   # Run on specific platform
   npm run android  # For Android
   npm run ios      # For iOS
   npm run web      # For web

Docker Deployment (Alternative)

# Backend with Docker Compose
cd unicarpool-backend/docker-compose
docker-compose -f main.yml up -d

# The application will be available at http://localhost:8080

📚 API Documentation

Base URLs

• Development: http://localhost:8080

Key Endpoints

Authentication

• POST /api/v1/auth/login - User login
• POST /api/v1/auth/verification-code - Send email verification
• POST /api/v1/auth/verify-code - Verify email
• POST /api/v1/auth/recover-password - Password recovery

User Management

• POST /api/v1/user/register - Register new user
• GET /api/v1/user - Get user profile
• POST /api/v1/user/update - Update profile
• POST /api/v1/user/add-type - Add user role

Driver Operations

• POST /api/v1/driver/create-ride - Create new ride
• GET /api/v1/driver/ride - Get driver's rides
• PUT /api/v1/driver/{requestId}/accept - Accept ride request
• PUT /api/v1/driver/{requestId}/reject - Reject ride request

Rider Operations

• GET /api/v1/rider/ride/active - Browse available rides
• POST /api/v1/rider/book-ride - Request to join ride
• GET /api/v1/rider/my-request - View ride requests
• POST /api/v1/rider/rating - Submit ride rating

Emergency Features

• POST /api/v1/emergency/add-contact - Add emergency contact
• GET /api/v1/emergency/sos-alert - Send SOS alert

Complete API Documentation: API_DOCUMENTATION.md

Postman Collection: UniCarpool API Collection

💻 Development

Backend Development

cd unicarpool-backend

# Run tests
./gradlew test

# Build application
./gradlew build

# Run with development profile
./gradlew bootRun --args='--spring.profiles.active=dev'

Frontend Development

cd unicarpool-frontend

# Start development server
npm start

# Run linting
npm run lint

# Build for production
eas build --platform all --profile production

Code Quality

• Backend: 140 comprehensive tests (123 unit + 17 integration)
• Code Coverage: Comprehensive test coverage across all layers
• Code Quality Reports: Available in unicarpool-backend/reports/quality/
• Design Principles: SOLID principles implementation documented

🚀 Deployment

Production Deployment Options

1. VM Deployment (Recommended)

   • Complete guide: VM_DEPLOYMENT.md
   • Includes Nginx, SSL, and systemd configuration

2. Docker Deployment

   • Guide: DOCKER_DEPLOYMENT.md
   • Container orchestration with Docker Compose

3. GitLab CI/CD

   • Automated deployment pipeline
   • Guide: GITLAB_CICD.md

Environment Configuration

• Development: application-dev.properties
• Production: application.properties
• Docker: Environment variables in .env files

🧪 Testing

Backend Testing

cd unicarpool-backend

# Run all tests
./gradlew test

# Run specific test class
./gradlew test --tests "AuthServiceTest"

# Generate test report
./gradlew test jacocoTestReport

Test Coverage:

• Unit Tests: 123 tests covering service layer, utilities, and components
• Integration Tests: 17 tests covering end-to-end workflows
• Test Categories: Authentication, User Management, Ride Operations, Emergency Protocols

Frontend Testing

cd unicarpool-frontend

# Run linting
npm run lint

# Type checking
npx tsc --noEmit

📖 Documentation

Comprehensive Guides

• Getting Started - Complete setup instructions
• Configuration - Environment and application configuration
• Testing Guide - Testing strategies and best practices
• Design Principles - Architecture and design patterns
• Use Case Scenarios - Real-world usage examples
• TDD Documentation - Test-driven development practices

API & Technical Documentation

• API Documentation - Complete REST API reference
• Backend README - Backend-specific documentation
• Frontend README - Frontend-specific documentation

🤝 Contributing

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Implement changes with tests
4. Run tests and ensure they pass
5. Commit changes (git commit -m 'Add amazing feature')
6. Push to branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Code Standards

• Backend: Follow Java naming conventions, use Lombok, write meaningful tests
• Frontend: Follow TypeScript best practices, use consistent component structure
• Documentation: Update relevant documentation for new features
• Testing: Maintain test coverage for new functionality

Quality Assurance

• All code must pass existing tests
• New features require corresponding tests
• Code review required for all pull requests
• Follow established design patterns and principles

📄 License

Intellectual Property: Sanif Ali Momin

---

Version: 1.0.0
Last Updated: January 2025
Status: Active Development