38703-vm/MONOGRAPH.md

# Comprehensive Project Monograph: Advanced Vehicle Marketplace System

## 1. Introduction
This document serves as a complete technical monograph for the Vehicle Marketplace System, a full-stack web application designed for the educational sector and general vehicle trading. This system provides a robust platform for users to list vehicles, manage sales, and for buyers to submit purchase requests through a secure, modern interface.

## 2. System Architecture
The application follows a modular LAMP (Linux, Apache, MySQL/MariaDB, PHP) architecture. It is designed to be scalable, secure, and user-centric.

### 2.1 Backend Layer
- **Language:** PHP 8.x (Vanilla PHP for maximum performance and compatibility).
- **Database Interaction:** PDO (PHP Data Objects) with prepared statements to prevent SQL injection.
- **Session Management:** Secure PHP sessions for user authentication and role-based access control.

### 2.2 Frontend Layer
- **HTML5 & CSS3:** Modern semantic markup and advanced styling.
- **Design Paradigm:** Sophisticated Dark Theme with Glassmorphism effects.
- **Typography:** Inter font family for high legibility and professional aesthetics.
- **Responsive Design:** Mobile-first approach using CSS Grid and Flexbox.

### 2.3 Database Layer
- **Engine:** MariaDB/MySQL.
- **Schema Design:** Normalized relational structure with foreign key constraints.

## 3. Technology Stack Detail

### 3.1 PHP (Hypertext Preprocessor)
Used for all server-side logic, including:
- User registration and authentication.
- CRUD operations for vehicle listings.
- Purchase request processing.
- Admin panel logic.
- Email notifications via `MailService.php`.

### 3.2 MariaDB
The database stores all critical information:
- **users table:** Stores user credentials, contact info (phone, address), and roles.
- **cars table:** Stores vehicle details (brand, model, price, description, status).
- **car_images table:** Manages multiple images per vehicle with a primary image flag.
- **purchases table:** Tracks buying requests, bank transaction IDs, and status (pending/approved/rejected).
- **messages table:** Stores contact form submissions.

### 3.3 CSS (Cascading Style Sheets)
The styling is centralized in `assets/css/style.css`, featuring:
- **Custom Variables:** `--primary-color` (Gold), `--bg-color` (Deep Slate), etc.
- **Glassmorphism:** Using `backdrop-filter: blur()` and semi-transparent backgrounds for a premium feel.
- **Animations:** Smooth transitions (`cubic-bezier`) for interactive elements.

## 4. Database Schema Specification

### 4.1 Table: users
| Column | Type | Description |
|---|---|---|
| id | INT | Primary Key, Auto-increment |
| username | VARCHAR(50) | Unique username |
| password | VARCHAR(255) | Hashed password |
| email | VARCHAR(100) | Unique email |
| phone | VARCHAR(20) | User contact number |
| address | TEXT | User physical address |
| role | ENUM | 'user' or 'admin' |
| created_at | TIMESTAMP | Account creation date |

### 4.2 Table: cars
| Column | Type | Description |
|---|---|---|
| id | INT | Primary Key |
| user_id | INT | Foreign Key to users |
| brand | VARCHAR(50) | Vehicle brand |
| model | VARCHAR(50) | Vehicle model |
| year | INT | Manufacturing year |
| price | DECIMAL | Listing price |
| city | VARCHAR(50) | Location |
| description | TEXT | Detailed info |
| status | ENUM | 'pending', 'approved', 'rejected', 'sold' |

### 4.3 Table: purchases
| Column | Type | Description |
|---|---|---|
| id | INT | Primary Key |
| car_id | INT | Foreign Key to cars |
| user_id | INT | Foreign Key to users |
| bank_id | VARCHAR(100) | Transaction reference |
| personal_info| TEXT | Buyer's additional info |
| status | ENUM | 'pending', 'approved', 'rejected' |

## 5. Functional Walkthrough

### 5.1 User Experience (UX)
The user journey starts at the landing page (`index.php`), featuring a high-impact hero section. Users can browse vehicles in `cars.php` with advanced filtering.

### 5.2 Seller Workflow
1. **Login/Register:** Secure entry point.
2. **Dashboard:** Overview of listings.
3. **Add Car:** Upload vehicle details and images.
4. **Management:** Edit or mark listings as sold.

### 5.3 Buyer Workflow
1. **Discovery:** Find a vehicle.
2. **Purchase Request:** Submit a formal request with payment reference (Bank ID).
3. **Tracking:** View request status in the dashboard.
4. **Receipt:** Generate a digital receipt upon approval.

### 5.4 Admin Capabilities
- **Dashboard:** High-level stats (Total sales, users, cars).
- **Approval System:** Approve or reject car listings and purchase requests.
- **User Management:** Oversee the community.
- **Communications:** Manage messages from the contact form.

## 6. UI/UX Design Principles

### 6.1 Sophisticated Dark Theme
The "Darker and User-Friendly" theme uses a color palette that reduces eye strain and emphasizes high-value content.
- **Background:** `#0f172a` (Deep Space)
- **Accents:** `#d4af37` (Luxury Gold)
- **Contrast:** High legibility white and slate-gray text.

### 6.2 Modern Components
- **Cards:** Elevated cards with hover scaling.
- **Glassmorphism:** Professional blur effects for navigation and overlays.
- **Buttons:** Large, accessible touch targets with subtle shadows.

## 7. Security and Integrity
- **Password Hashing:** `password_hash()` and `password_verify()` for industry-standard security.
- **SQL Protection:** 100% usage of PDO prepared statements.
- **Input Sanitization:** `htmlspecialchars()` for XSS prevention.
- **State Management:** Secure session handling and CSRF awareness.

## 8. Conclusion
This system represents a state-of-the-art vehicle marketplace, combining technical excellence with a premium user experience. It is designed to be both a functional tool and a beautiful interface, adhering to the highest standards of modern web development.

---
*Monograph created on February 23, 2026.*
*Version 1.0.0*