🚗 Car Rental Management System

A full-stack car rental management system with intelligent cost calculation, modern UI, and comprehensive API, and persistence in data. Built as an OOP course project implementing design patterns, monolith architecture, and best practices.

🎯 Overview

Backend: FastAPI REST API with modular monolith and service layer pettern, Strategy/Decorator patterns for rental cost calculation, PostgreSQL-based repository pattern, ORM for data manipulation, and CLI interface.

Frontend: React + TypeScript SPA with shadcn/ui components, React Query for data fetching, Zod validation, and comprehensive testing.

Key Features:

🚙 Complete car inventory management with image uploads
👥 Client management system
📝 Rental creation and tracking
💰 Smart cost calculation (SUV premium, long-term discounts, holiday deals)
📊 Dashboard with real-time statistics
🗑️ Soft delete with recovery archives
⚡ Optimized queries with bulk fetching to prevent N+1 problems
🐳 Docker containerization for easy deployment
🖥️ CLI for system management
🧪 Full test coverage (Pytest + Vitest)
🔒 JWT-based authentication

📸 App Preview

📱 Mobile Flow	🖥️ Desktop Flow

📱 Rental Workflow (Logic)	🖥️ Car Creation (UX/Validation)

Stage-based selection: Car search → Client lookup → Confirmation	Inventory Flow: Zod validation & Drag-and-drop upload

🎬 Interactive Demo

Experience the system in action without installing anything!

🚀 Quick Start

Option 1: Docker Deployment (Recommended)

Prerequisites:

Docker 21+
Docker Compose

# Clone repository
git clone https://github.com/M4sayev/car-rental-system.git
cd car-rental-system

# Configure environment
cp .env.example .env
# Edit .env with your database credentials

# Start all services
docker-compose up --build

# View logs
docker-compose logs -f

Access the application:

🌐 Frontend: http://localhost 📚 API Docs: http://localhost:8000/docs 🔧 Direct Backend: http://localhost:8000

Option 2: Local Development

Prerequisites

Python 3.9+
Node.js 22+
PostgreSQL 18+
pip & npm

1. Clone Repository

git clone https://github.com/M4sayev/car-rental-system.git
cd car-rental-system

2. Backend Setup (navigate to api folder for a more feature specific readme)

# Install Python dependencies
pip install -r requirements.txt

# Configure database connection in .env or environment variables
(follow .env.example ensure the DB_NAME is localhost)

# Start API server
python run_api.py

API runs at: http://localhost:8000
Docs: http://localhost:8000/docs

3. Frontend Setup (navigate to frontend folder for a more feature specific readme)

cd frontend

# Install dependencies
npm install

# Start dev server
npm run dev

App runs at: http://localhost:5173

📁 Project Structure

car-rental-system/
│
├── api/                          # FastAPI application
│   ├── main.py                   # App entry with CORS & static files
│   ├── routes/                   # API endpoints (cars, clients, rentals, dashboard)
│   ├── schemas/                  # Pydantic validation models
│   ├── utils/                    # utility and helper functions (deserialize(), save_image(),...)
│   ...
│   └── collections/              # Postman test collections (4 collections)
│
├── src/                          # Core business logic
│   ├── models/                   # Domain models
│   │   ├── car.py
│   │   ├── client.py
│   │   ├── rental.py
│   │   └── strategies/           # Cost calculation (Strategy + Decorator patterns)
│   ├── repositories/             # Data access layer (Postgresql storage)
│   ├── db/                       # Seed DB, connection to DB, table creation
│   ├── types/                    # Reusable types for type aliasing
│   └── services/                 # Business logic (car, client, rental services)
│
├── frontend/                     # React + TypeScript SPA
│   ├── src/
│   │   ├── components/           # UI components (shadcn/ui + custom + test for each scoped component folder)
│   │   ├── pages/                # Pages (dashboard, cars, clients, rentals)
│   │   ├── hooks/                # React Query hooks
│   │   ...
│   │   ├── constants/            # Model templates, Zod validation schemas, and reusable constants
│   │   └── utils/                # Utilities formatStringToISO, getStatusColor,... 
│   └── test/                     # Mock values for testing (MockClient, MockCar,...)
│
├── data/                         # JSON data for seeding database
│   ├── cars.json
│   ├── clients.json
│   └── rentals.json
│
├── deleted_data/                 # Soft-deleted records archive for seeding database
│
├── media/                        # Uploaded car images
│   └── cars/
├── nginx/                        # Nginx configuration file 
│   └── nginx.conf
├── docs/                         # Documentation
│   ├── UML.png
│   ├── ER (for db).png
│   ├── technical_documentation.md
│   ...
│   └── user_guide.md
│
├── tests/                        # Backend tests (Pytest)
│
├── cli.py                        # Command-line interface
├── run_api.py                    # API launcher
├── run.py                        # CLI launcher
├── docker-compose.yml            # Docker orchestration configuration
├── .env.example                  # Environment variables template
├── .dockerignore                 # Docker ignore patterns
└── requirements.txt              # Python dependencies

💻 Usage

Web Interface

Navigate to http://localhost:5173 for the full UI:

Dashboard with statistics
Manage cars (CRUD + image upload)
Manage clients (CRUD + validation)
Manage Rentals (CRUD + search option + validation)
handle login form authentication

API

Access http://localhost:8000/docs for interactive API documentation with:

8 car endpoints (including cost calculator)
6 client endpoints
5 rental endpoints
2 dashboard endpoints
2 authentication endpoints (login and signup)

Command Line

Quick operations via CLI:

# List cars (list-available / list-deleted for available / deleted respectively)
python cli.py car list

# Add a car interactively
python cli.py car add

# Delete a car (select from list)
python cli.py car delete

# List all clients (list-deleted for deleted clients)
python cli.py client list

# Add a client
python cli.py client add

# Create a rental
python cli.py rental create C001 CL001

# Complete a rental
python cli.py rental complete R001

# List active rentals
python cli.py rental list

🎨 Design Patterns

Strategy Pattern

Different cost strategies based on car type:

StandardCarCost      # Base daily rate
SUVRentalCost        # 20% premium for SUVs

Decorator Pattern

Stackable discounts:

LongTermRentalCost   # 15% off for 7+ days
HolidayDiscount      # 10% off on Azerbaijan holidays

Example: SUV rented for 10 days on a holiday = base × 1.2 × 0.85 × 0.9

⚡ Performance Optimizations

N+1 Query Prevention

The repository layer implements bulk fetching to avoid N+1 query problems:

Rentals are hydrated using bulk get_by_ids() operations
Cars and clients are fetched in batches and mapped using hashmaps
Result: Single query per entity type instead of N queries per rental

Example: Loading 100 rentals requires only 3 queries (rentals, cars, clients) instead of 201.

🧪 Testing

Backend Tests

pytest                    # Run all tests
pytest --cov=src          # With coverage

Frontend Tests

cd frontend
npm run test              # Run all tests
npm run test:coverage     # With coverage

📚 Documentation

Detailed documentation available:

API Documentation - Endpoints, examples, Postman collections, design patterns
Frontend Documentation - Setup, components, testing, architecture
Technical Docs - System design and architecture
User Guide - End-user instructions

🛣️ Roadmap

Current Status ✅

Planned 🎯

Dashboard analytics charts
AI integration

🔧 Tech Stack

Backend:

FastAPI - High-performance async API framework
Python 3.9+ - Core language
Pydantic - Data validation
Pytest - Testing framework
Click - CLI framework
Docker 29+ - containeraziation

Frontend:

React 18 - UI library
TypeScript - Type safety
Vite - Build tool
TailwindCSS - Styling
shadcn/ui - Component library
React Query - Data fetching
React Hook Form + Zod - Form validation
Vitest - Testing framework

Data Storage:

PostgreSQL - database
psycopg2 ORM - data manipulation
Bulk select operations preventing N+1 query issues
Configurable history tracking for deleted items
Media storage for uploaded images

🤝 Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a Pull Request

Ensure all tests pass before submitting:

# Backend
pytest

# Frontend
cd frontend && npm run test && npm run lint

📄 License

This project is licensed under the MIT License.

👥 Authors

Elvin Musayev - @M4Sayev
Eltun Jalilli - @EltunLTN

🙏 Acknowledgments

Built as part of an OOP course project, demonstrating:

Object-oriented programming principles
Design patterns (Strategy, Decorator, Repository)
Microservices architecture
Modern web development practices
Test-driven development
Persisting data in the database

Name		Name	Last commit message	Last commit date
Latest commit History 171 Commits
api		api
data		data
deleted_data		deleted_data
docs		docs
frontend		frontend
media/cars		media/cars
nginx		nginx
src		src
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
cli.py		cli.py
docker-compose.yaml		docker-compose.yaml
requirements.txt		requirements.txt
run.py		run.py
run_api.py		run_api.py

M4sayev/car-rental-system

Folders and files

Latest commit

History

Repository files navigation