docs/ARCHITECTURE.md

# NETRA - System Architecture

## 🏗️ Application Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                         FRONTEND                             │
│  ┌───────────┐  ┌──────────────┐  ┌────────────────────┐   │
│  │  Login/   │  │  Dashboard   │  │  Live Camera /     │   │
│  │  Register │  │              │  │  Video Analysis    │   │
│  └─────┬─────┘  └──────┬───────┘  └─────────┬──────────┘   │
│        │               │                     │               │
│        └───────────────┴─────────────────────┘               │
│                        │                                     │
│                   [HTTP/AJAX]                                │
│                        │                                     │
└────────────────────────┼─────────────────────────────────────┘
                         │
┌────────────────────────┼─────────────────────────────────────┐
│                   FLASK BACKEND                              │
│                        │                                     │
│  ┌─────────────────────┴─────────────────────────┐          │
│  │            Flask Application (app.py)          │          │
│  │  ┌──────────────────────────────────────────┐ │          │
│  │  │         Route Handlers                   │ │          │
│  │  │  • /register  • /login   • /dashboard   │ │          │
│  │  │  • /live-camera  • /video-analysis      │ │          │
│  │  │  • /camera_feed  • /upload_video        │ │          │
│  │  └──────────────────────────────────────────┘ │          │
│  └───────────────┬──────────────────┬────────────┘          │
│                  │                  │                        │
│     ┌────────────┴────────┐    ┌───┴──────────────┐        │
│     │  Authentication     │    │  Video Processor │        │
│     │  • User Login       │    │  • Frame Process │        │
│     │  • Session Mgmt     │    │  • Model Apply   │        │
│     │  • Password Hash    │    │  • Alert Gen     │        │
│     └─────────────────────┘    └─────────┬────────┘        │
│                                           │                  │
│     ┌────────────────────────────────────┴────────┐        │
│     │            Model Manager                    │        │
│     │  ┌──────────────┐  ┌─────────────────────┐ │        │
│     │  │ YOLO Object  │  │ Violence Detection  │ │        │
│     │  │ Detection    │  │ CNN Model           │ │        │
│     │  └──────────────┘  └─────────────────────┘ │        │
│     │                                             │        │
│     │  ┌──────────────────────────────────────┐  │        │
│     │  │   Extensible Model Interface        │  │        │
│     │  │   (Add More Models Here)            │  │        │
│     │  └──────────────────────────────────────┘  │        │
│     └─────────────────────────────────────────────┘        │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────┼─────────────────────────────────────┐
│                   DATA LAYER                                 │
│                        │                                     │
│  ┌────────────────────┴──────────────────────┐              │
│  │         SQLite Database (netra.db)        │              │
│  │  ┌──────────────┐  ┌────────────────────┐│              │
│  │  │    Users     │  │ Analysis History   ││              │
│  │  │  • id        │  │  • id              ││              │
│  │  │  • username  │  │  • user_id         ││              │
│  │  │  • email     │  │  • type            ││              │
│  │  │  • password  │  │  • detections      ││              │
│  │  │  • created   │  │  • alert_count     ││              │
│  │  └──────────────┘  └────────────────────┘│              │
│  └─────────────────────────────────────────┘               │
│                                                              │
│  ┌──────────────────────────────────────────┐              │
│  │         File Storage (uploads/)          │              │
│  │  • Uploaded video files                  │              │
│  │  • Temporary processing files            │              │
│  └──────────────────────────────────────────┘              │
└──────────────────────────────────────────────────────────────┘


## 🔄 Data Flow

### User Registration/Login Flow
```

User Input → Flask Route → Validate Data → Hash Password
→ Store in DB → Create Session → Redirect to Dashboard

```

### Live Camera Flow
```

Camera → OpenCV Capture → Frame Extract → Model Manager
→ YOLO Detection → Violence Detection → Annotate Frame
→ Generate Alerts → Stream to Frontend → Display Results

```

### Video Analysis Flow
```

Upload Video → Save to Uploads/ → Extract Frames
→ Process Each Frame → Collect Detections → Generate Report
→ Save to History → Return Results → Display to User

```

## 🔌 Component Interactions

### Frontend ↔ Backend
- **Authentication**: POST JSON → Flask validates → Return success/error
- **Video Stream**: GET request → Flask streams MJPEG → Browser displays
- **File Upload**: FormData POST → Flask saves → Processes → Returns JSON
- **Model List**: GET request → Flask queries ModelManager → Returns JSON

### Backend ↔ Models
- **Model Loading**: App start → ModelManager loads all models
- **Frame Processing**: Frame → YOLO.detect() → Violence.predict()
- **Result Aggregation**: Combine all model outputs → Format alerts

### Backend ↔ Database
- **User Operations**: Create, Read, Authenticate
- **History Logging**: Store analysis results for each session
- **Session Management**: Track logged-in users

## 📊 Technology Stack

```

┌─────────────────────────────────────────┐
│ Presentation Layer │
│ • HTML5 • CSS3 • JavaScript (Vanilla) │
└──────────────────┬──────────────────────┘
│
┌──────────────────┴──────────────────────┐
│ Application Layer │
│ • Flask 3.0 • Python 3.8+ │
│ • Flask-SQLAlchemy • Werkzeug │
└──────────────────┬──────────────────────┘
│
┌──────────────────┴──────────────────────┐
│ AI Layer │
│ • YOLOv8 (Ultralytics) │
│ • TensorFlow/Keras │
│ • OpenCV │
└──────────────────┬──────────────────────┘
│
┌──────────────────┴──────────────────────┐
│ Data Layer │
│ • SQLite • File System │
└─────────────────────────────────────────┘

```

## 🎯 Design Patterns Used

1. **MVC Pattern**: Models (DB), Views (Templates), Controllers (Routes)
2. **Manager Pattern**: ModelManager handles all AI models
3. **Singleton**: Database connection
4. **Factory**: Model creation and loading
5. **Strategy**: Different detection strategies per model

## 🔐 Security Architecture

```

Request → Session Check → Authentication → Authorization
→ Input Validation → Process → Sanitize Output

```

- Password hashing (Werkzeug)
- Session management (Flask)
- File upload validation
- Path sanitization

## 🚀 Deployment Architecture

```

Development:
Flask Dev Server → SQLite → Local Files

Production (Future):
Nginx → Gunicorn → Flask App → PostgreSQL
→ S3/Cloud Storage
→ Redis (Caching)

```

## 📈 Scalability Considerations

Current: Single-threaded with threading support
Future paths:
- Multi-process workers (Gunicorn)
- Background job queue (Celery)
- Message broker (RabbitMQ/Redis)
- Load balancer
- Microservices architecture

---

**This architecture supports:**
✅ Easy model integration
✅ Horizontal scaling potential
✅ Maintainable code structure
✅ Security best practices
✅ Future enhancements
```