diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f0493ec
--- /dev/null
+++ b/README.md
@@ -0,0 +1,134 @@
+# AfgCars - Modern Automotive Marketplace
+
+AfgCars is a robust, visually stunning automotive marketplace platform designed for the Afghan car market. It features a modern "glassmorphism" design, a powerful admin panel, and seamless car listing management for both individual sellers and administrators.
+
+## 🚀 Key Features
+- **Modern UI/UX**: Clean, youthful, and inviting design with glassmorphism effects.
+- **Admin Dashboard**: Full control over users, car listings, and customer messages.
+- **User Dashboard**: Personal area for users to manage their own car listings.
+- **Car Marketplace**: Advanced search and filtering for cars across various cities in Afghanistan.
+- **Responsive Design**: Fully functional on mobile, tablet, and desktop devices.
+- **Secure Authentication**: Robust registration and login system with role-based access control.
+
+## 🛠️ Technology Stack
+- **Backend**: PHP 8.x
+- **Database**: MariaDB/MySQL
+- **Frontend**: HTML5, CSS3 (Custom Glassmorphism Styles), JavaScript (Vanilla)
+- **Email**: Integrated PHPMailer service
+
+## 🗄️ Database Configuration
+The database connection details are stored in `db/config.php`.
+
+| Parameter | Value |
+|-----------|-------|
+| **Host** | `127.0.0.1` |
+| **Database Name** | `app_38703` |
+| **Username** | `app_38703` |
+| **Password** | `9e003665-baa5-4dba-baf3-b850a58e49d7` |
+
+To initialize the database, run:
+```bash
+php db/setup.php
+php db/seed_cars.php
+```
+
+## 👤 Default Accounts
+Use these credentials to access the platform during testing:
+
+### Administrator
+- **Email**: `admin@gmail.com`
+- **Password**: `12345678`
+- **Role**: `admin`
+
+### Regular User
+- **Email**: `user@example.com` (Example - use registration to create)
+- **Password**: `12345678`
+- **Role**: `user`
+
+## 📊 Entity Relationship Diagram (ERD)
+
+```mermaid
+erDiagram
+    USERS ||--o{ CARS : "posts"
+    USERS ||--o{ REVIEWS : "writes"
+    USERS ||--o{ PURCHASES : "makes"
+    CARS ||--o{ CAR_IMAGES : "has"
+    CARS ||--o{ REVIEWS : "receives"
+    CARS ||--o{ PURCHASES : "is_part_of"
+
+    USERS {
+        int id PK
+        string name
+        string email UK
+        string password
+        enum role "guest, user, admin"
+        enum status "active, inactive"
+        timestamp created_at
+    }
+
+    CARS {
+        int id PK
+        int user_id FK
+        string brand
+        string model
+        int year
+        decimal price
+        string city
+        text description
+        enum status "pending, approved, rejected, sold"
+        boolean is_hot_deal
+        timestamp created_at
+    }
+
+    CAR_IMAGES {
+        int id PK
+        int car_id FK
+        string image_path
+        boolean is_main
+    }
+
+    REVIEWS {
+        int id PK
+        int car_id FK
+        int user_id FK
+        int rating
+        text comment
+        enum status "pending, approved"
+        timestamp created_at
+    }
+
+    PURCHASES {
+        int id PK
+        int car_id FK
+        int user_id FK
+        string buyer_name
+        string buyer_email
+        string buyer_phone
+        enum status "pending, completed, cancelled"
+        timestamp created_at
+    }
+
+    CONTACT_MESSAGES {
+        int id PK
+        string name
+        string email
+        string subject
+        text message
+        enum status "unread, read, answered"
+        timestamp created_at
+    }
+```
+
+## 📁 Project Structure
+- `index.php`: Landing page and marketplace hero.
+- `cars.php`: Searchable list of all approved vehicles.
+- `car_detail.php`: Detailed view of a single car with photo gallery.
+- `admin_dashboard.php`: Entry point for administrative management.
+- `dashboard.php`: User-specific panel for listing management.
+- `db/`: Database configuration and setup scripts.
+- `assets/`: CSS, JS, and image assets.
+- `includes/`: Reusable header and footer components.
+- `mail/`: Built-in email service components.
+
+## 📝 License
+This project is built for educational and demonstration purposes.