diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..d940160
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,46 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environments
+venv/
+env/
+.venv/
+.python-version
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Logs and local settings
+*.log
+*.env
+.envrc
+
+# Jupyter Notebook checkpoints
+.ipynb_checkpoints/
+
+# MyPy cache
+.mypy_cache/
+
+# PyTest cache
+.pytest_cache/
+
+# Coverage reports
+htmlcov/
+.coverage
+.coverage.*
+.cache
+
+# IDE and editor files
+.vscode/
+.idea/
+*.sublime-project
+*.sublime-workspace
+
+# macOS and Linux files
+.DS_Store
+*.swp
diff --git a/.idea/workspace.xml b/.idea/workspace.xml
index 02e8f39..8cd56a6 100644
--- a/.idea/workspace.xml
+++ b/.idea/workspace.xml
@@ -4,13 +4,10 @@
-
-
-
-
-
-
-
+
+
+
+
@@ -63,13 +60,34 @@
1741367638904
-
+
+
+
+ 1741369090367
+
+
+
+ 1741369090367
+
+
+
+ 1741369108114
+
+
+
+ 1741369108114
+
+
+
+
+
+
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4af99d4
--- /dev/null
+++ b/README.md
@@ -0,0 +1,140 @@
+# 🚀 Helmet Violation Detector
+
+A **real-time helmet violation detection system** that identifies motorcycles, detects whether riders are wearing helmets, and reads license plates using **YOLO, PaddleOCR, and OpenCV**.
+
+---
+
+## 📌 Features
+
+- 🏍️ **Motorcycle Detection** (YOLO-based)
+- 🎩 **Helmet Detection** (Custom YOLO model)
+- 🚶 **Person-Motorcycle Association** (using IoU & aspect ratio similarity)
+- 🔍 **License Plate Recognition** (PaddleOCR)
+- 🚗 **License Plate Detection** (YOLO-based)
+- 🎥 **Real-time Camera Processing** (OpenCV)
+- 📊 **Report Generation in Excel** (OpenPyXL)
+- 🖥️ **GUI Interface** (PyQt6)
+
+---
+
+## 🛠️ Installation
+
+### 1️⃣ Clone the Repository
+
+```bash
+git clone https://github.com/yourusername/helmet-violation-detector.git
+cd helmet-violation-detector
+```
+
+### 2️⃣ Set Up Virtual Environment (Recommended)
+
+```bash
+python -m venv venv
+source venv/bin/activate # On macOS/Linux
+.\venv\Scripts\activate.bat # On Windows CMD
+.\venv\Scripts\activate.ps1 # On Powershell
+```
+
+### 3️⃣ Install Dependencies
+
+Ensure you have **Python 3.8+** installed. Then, run:
+
+```bash
+pip install -r requirements.txt
+```
+
+**🔹 Note:**
+1. If you face **PaddleOCR-related dependency issues**, make sure to install **paddlepaddle**:
+
+```bash
+pip install paddlepaddle
+```
+
+2. If you face **Protobuf related issues**, make sure to install correct version of protobuf (4.25.*):
+
+```bash
+pip install protobuf==4.25.*
+```
+
+---
+
+
+## 🚀 Usage
+
+### 🔹 GUI Mode
+
+To launch the **Helmet Violation Detector GUI**, run:
+
+```bash
+python main.py
+```
+
+### 🔹 Real-time Camera Detection
+
+Click **"Start Real-Time Analysis"** in the GUI to process frames from your webcam.
+
+### 🔹 Processing Images/Videos
+
+1. Click **"Upload Media"** and select an image or video.
+2. Click **"Analyze Media"** to process.
+3. Click **"Create Report"** to generate an **Excel report**.
+4. Click **"Start Real-Time Mode"** to start/stop **analysis on connected webcam/camera feed**.
+
+---
+
+## 📝 Limitations
+
+- Cannot do excel writes in real time mode , however console outs detected number plates at all times
+- Model Accuracy depends on presented input source quality and fidelity.
+- Currently motorcycle to person association is done however,associations for person to helmet is also required.
+
+---
+
+## ⚙️ Dependencies
+
+This project requires:
+
+- **Python 3.8+**
+- **YOLO (Ultralytics)**
+- **PaddleOCR**
+- **OpenCV**
+- **Mediapipe**
+- **PyQt6**
+- **OpenPyXL (Excel support)**
+
+You can install them using:
+
+```bash
+pip install -r requirements.txt
+```
+
+---
+
+## 📌 Troubleshooting
+
+### ❓ Facing PaddleOCR Issues?
+
+If you get errors related to `protobuf` or `paddleocr`, try:
+
+```bash
+pip install paddlepaddle
+```
+
+or
+
+```bash
+pip install protobuf==3.20.*
+```
+
+---
+
+## 📜 License
+
+This project is licensed under the **Apache 2.0 License**.
+
+---
+
+## 👨💻 Author
+
+Developed by **Bitmutex Technologies** 🚀
+