docs/PROJECT_STRUCTURE.md

# Project Structure Guide

## Overview

NETRA is now organized into clear, logical sections for easy maintainability and scalability.

```
NETRA/
├── src/                     Source code
│   ├── detectors/          AI detection modules
│   ├── pipeline/           Video processing pipeline
│   └── utils/              Utility functions
├── models/                 Trained AI model weights
├── config/                 Configuration files
├── webapp/                 Flask web application
├── docs/                   Documentation
├── tests/                  Unit tests
└── README.md              Main documentation
```

## Directory Details

### `/src` - Source Code

Contains all core application code organized by functionality.

#### `/src/detectors`
All AI detection models wrapped in consistent interfaces:

- **`yolo_detector.py`** - Object detection (people, cars, animals)
  - Uses YOLOv8 from Ultralytics
  - Model: `models/object_detection/yolov8n.pt`

- **`violence_detector.py`** - Violence/fight detection
  - Uses Keras CNN trained on violence data
  - Model: `models/violence_detection/violence_model.h5`

- **`weapon_detector.py`** - Gun/knife detection
  - Uses custom trained YOLO model
  - Models: `models/weapon_detection/best.pt`, `models/object_detection/yolov8n.pt`

- **`pose_detector.py`** - Human pose detection
  - Uses YOLOv11 Pose
  - Model: `models/pose_detection/yolo11n-pose.pt`

- **`anomaly_detector.py`** - Anomalous behavior detection
  - Uses PyTorch anomaly model
  - Model: `models/anomaly_detection/best.bin`

#### `/src/pipeline`
Video input and processing modules:

- **`video_capture.py`** - Camera/RTSP stream capture
  - Motion detection using MOG2
  - ROI extraction for efficient processing

#### `/src/utils`
Helper utilities and common functions (for future expansion)

### `/models` - Trained Model Weights

Organized by detection type:

```
models/
├── object_detection/      YOLO object models
├── violence_detection/    Violence detection models
├── weapon_detection/      Weapon detection models
├── pose_detection/        Pose detection models
└── anomaly_detection/     Anomaly detection models
```

Each folder contains the trained weights ready for inference.

### `/config` - Configuration Files

Centralized configuration management:

- **`settings.py`** - Application-wide settings
  - Flask configuration
  - Database settings
  - File upload parameters
  - Session management

- **`model_config.py`** - Model-specific configuration
  - All model paths (easy updates)
  - Detection thresholds
  - Processing parameters

### `/webapp` - Flask Web Application

The complete web interface:

```
webapp/
├── app.py                 Main Flask application
├── templates/             HTML templates
├── static/               CSS, JavaScript, images
├── uploads/              User uploaded videos
├── processed/            Processed video outputs
└── instance/             SQLite database
```

### `/docs` - Documentation

- **`ARCHITECTURE.md`** - System architecture overview
- **`ANOMALY_DETECTION_GUIDE.md`** - Anomaly detection setup
- **`SETUP.md`** - Installation and setup instructions
- **`API.md`** - API reference

### `/tests` - Unit Tests

Test files for core modules (optional for future):

- `test_detectors.py` - Tests for detector modules
- `test_pipeline.py` - Tests for video pipeline

## Import Examples

### Old Structure (Before)
```python
from NETRA.violence_detector import ViolenceDetector
from NETRA.yolo_detector import YOLODetector
from pose_detection import PoseDetection
```

### New Structure (After)
```python
from src.detectors import ViolenceDetector, YOLODetector, PoseDetection
from src.pipeline import VideoCapture
from config import MODEL_PATHS, DETECTION_THRESHOLDS
```

## File Organization Benefits

✅ **Clear Separation** - Code organized by functionality
✅ **Easy Navigation** - Developers know where to find things
✅ **Scalability** - Easy to add new detectors or features
✅ **Maintainability** - Configuration centralized
✅ **Model Management** - All models in one organized place
✅ **Documentation** - All docs in dedicated folder

## Configuration Usage

### Accessing Model Paths

```python
from config import MODEL_PATHS, get_model_path

# Get specific model path
violence_model = get_model_path('violence')

# Get all available models
from config import get_all_available_models
models = get_all_available_models()
# Output: {'violence': True, 'yolo': True, 'weapon': True, ...}
```

### Accessing Thresholds

```python
from config import DETECTION_THRESHOLDS

yolo_threshold = DETECTION_THRESHOLDS['yolo']  # 0.25
violence_threshold = DETECTION_THRESHOLDS['violence']  # 0.6
```

### Accessing Settings

```python
from config import SECRET_KEY, MAX_CONTENT_LENGTH, UPLOAD_FOLDER

print(f"Max upload: {MAX_CONTENT_LENGTH}")
print(f"Upload location: {UPLOAD_FOLDER}")
```

## Next Steps

1. ✅ New folder structure created
2. ✅ Files reorganized
3. ✅ Configuration centralized
4. 🔄 Update imports in `webapp/app.py`
5. 🔄 Test all functionality

## Troubleshooting

**"Module not found" errors:**
- Ensure sys.path includes project root
- Check that `__init__.py` files exist in all packages

**Model not loading:**
- Check `config/model_config.py` paths
- Verify model files exist in `models/` directory
- Check file permissions

**Import issues:**
- Run from project root directory
- Ensure Python path includes `src/`