Smart Sentinel Eye - Industrial CCTV Management System

Enterprise-grade camera management system for 24/7 industrial monitoring

---

🎯 Overview

Smart Sentinel Eye is a robust, scalable CCTV management system designed for industrial production facilities that require 24/7 monitoring. The system supports up to 250 cameras with low-latency streaming, dynamic overlays, automated workflows, and comprehensive event processing.

Key Features

• 📹 Multi-Camera Management: Support for 250+ cameras with RTSP, ONVIF, and proprietary protocols
• 🎥 Low-Latency Streaming: < 2s glass-to-glass latency with HLS/WebRTC
• 🖥️ Flexible Layouts: Configurable display layouts with 1-20+ monitor walls
• 🎨 Dynamic Overlays: Real-time text, shapes, and data visualization on streams
• ⚙️ Automation: Time-based and event-driven camera switching and actions
• 📊 Event Processing: External event ingestion with timestamp synchronization
• 🔐 Security: JWT authentication, RBAC, and encrypted credentials
• 📈 Observability: Prometheus metrics, Grafana dashboards, structured logging

🏗️ Architecture

Smart Sentinel Eye follows Domain-Driven Design (DDD) principles with clear bounded contexts:

┌─────────────────────────────────────────────────────────────────┐
│                      FRONTEND (React)                           │
│  Operator Client  │  Display Client  │  Admin Console          │
└───────────┬───────────────────┬───────────────────┬─────────────┘
            │                   │                   │
         ┌──┴───────────────────┴───────────────────┴──┐
         │         API Gateway / Load Balancer         │
         └──┬───────────────────┬───────────────────┬──┘
            │                   │                   │
┌───────────┴──────┬────────────┴────┬──────────────┴───────────┐
│  Camera Mgmt     │  Streaming      │  Layout  │  Overlay      │
│  Service         │  Gateway        │  Service │  Service      │
├──────────────────┼─────────────────┼──────────┼───────────────┤
│  Automation      │  Event          │  Identity                │
│  Service         │  Processing     │  Service                 │
└──────────────────┴─────────────────┴──────────────────────────┘
            │                   │
┌───────────┴──────┬────────────┴────┬────────────┐
│  PostgreSQL      │  Redis          │  RabbitMQ  │
│  (TimescaleDB)   │  (Cache/PubSub) │  (Events)  │
└──────────────────┴─────────────────┴────────────┘
            │
┌───────────┴─────────────────────────────────────────┐
│  Stream Keeper Pool (20-50 cameras each)           │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐            │
│  │ Keeper 1│  │ Keeper 2│  │ Keeper N│            │
│  └────┬────┘  └────┬────┘  └────┬────┘            │
└───────┼────────────┼────────────┼──────────────────┘
        │            │            │
    📷 Cameras (RTSP/ONVIF) 1-250

Bounded Contexts

1. Camera Management: Device registration, configuration, PTZ control, health monitoring
2. Streaming: Stream keeper services, format conversion (RTSP → HLS), distribution
3. Layout Management: Display configuration, monitor walls, cell management
4. Overlay: Dynamic content rendering, system variables, templates
5. Automation: Scheduled actions, camera sequences, event-triggered workflows
6. Event Processing: External event ingestion, validation, history (Event Sourcing)
7. Identity & Access: Authentication, authorization, user management

For detailed architecture documentation, see docs/ARCHITECTURE.md.

🎨 Frontend Features

The Operator Client is a feature-rich React application providing comprehensive camera management and monitoring capabilities:

📊 Dashboard

• Real-time system statistics (total cameras, online/offline status, PTZ cameras)
• Active streams count with live updates
• System health overview with visual indicators
• Responsive stat cards with dynamic colors

📹 Camera Management

• Complete CRUD operations for camera devices
• RTSP connection configuration and testing
• PTZ (Pan-Tilt-Zoom) control for supported cameras
• Camera status monitoring (online/offline, enabled/disabled)
• ONVIF protocol support with capability detection
• Bulk operations and filtering

🎥 Live Streaming

• Customizable grid layouts (1x1 to 5x5 and beyond)
• Layout templates with persistent camera assignments
• Quick layout switching with keyboard shortcuts (Alt+1-5)
• Individual camera view enlargement with fullscreen mode
• Camera switching within grid cells
• Recent layouts tracking

🏗️ Layout Templates

• Pre-configured multi-camera layouts
• 1-20+ monitor wall support
• Cell-based camera assignment
• Layout sharing across operators
• Dynamic grid columns (1-10 columns)

🎨 Video Overlays

• Text overlays with custom fonts, colors, and positioning
• Shape overlays (rectangles, circles) with styling
• Line overlays with dash patterns
• Image overlays with opacity control
• Real-time visibility toggling
• Position and content updates

🔧 System Variables

• Typed variables (Text, Number, Boolean, DateTime, JSON)
• Variable substitution in overlay text using {{variableName}} syntax
• Live preview of text templates
• Variable history tracking with timestamps
• Default values and descriptions

📡 Event Monitoring

• Real-time event stream with auto-refresh
• Event filtering by source, severity, and time range
• External event ingestion display
• Timestamp-based synchronization with video streams
• Acknowledged/unacknowledged status tracking

⚡ Real-Time Updates

• SignalR WebSocket integration for live data
• Automatic UI updates on backend changes
• Optimistic UI updates with rollback on errors
• Efficient cache invalidation with React Query

🎯 User Experience

• Material-UI v7 - Modern, responsive design
• Dark/Light themes - Automatic system preference detection
• Keyboard shortcuts - Fast navigation and actions
• Loading states - Clear feedback during operations
• Error handling - User-friendly error messages
• Form validation - Client-side validation before submission

📚 Documentation

• Architecture Overview - System design, technology stack, scalability
• Domain Model - Value objects, entities, aggregates
• User Stories - 40+ detailed requirements and acceptance criteria
• Deployment Guide - Production deployment instructions, Docker Compose, Kubernetes
• Service Ports - Service port mapping and Docker build instructions
• Docker Optimization - Alpine and Chiseled image optimization
• API Documentation - Complete REST API reference for all 7 microservices

Testing Documentation

New to testing? Start here: GET_STARTED.md ⭐

Essential Reading:

• Get Started Guide - Your first 5 minutes ⭐ START HERE
• Testing Best Practices - Must-read guidelines ⭐
• Quick Reference Card - Commands & patterns cheat sheet

Detailed Guides:

• Complete Test Summary - Full inventory (225+ tests, 46 examples)
• Testing Guide - Comprehensive documentation
• Test Setup Checklist - Step-by-step verification

Reference:

• Changelog - v1.0.0 release notes
• Final Status - Implementation details
• Automation Tests - Service-specific details

🚀 Quick Start

Prerequisites

• Docker & Docker Compose (24.0+)
• .NET 9 SDK (for local development)
• Node.js 18+ (for frontend development)

One-Command Setup

# Clone the repository
git clone https://github.com/smartsolutionslab/smart-sentinel-eye.git
cd smart-sentinel-eye

# Start everything (all 7 microservices + infrastructure)
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Services available at:

• Camera Management: http://localhost:5001
• Streaming: http://localhost:5002
• Layout: http://localhost:5003
• Overlay: http://localhost:5004
• Automation: http://localhost:5005
• Event Processing: http://localhost:5006
• Identity: http://localhost:5007

Infrastructure services:

• PostgreSQL: localhost:5432
• RabbitMQ Management: http://localhost:15672 (smartsentinel/dev_password_123)
• Keycloak: http://localhost:8080 (admin/admin)
• Seq Logs: http://localhost:5341

Local Development (without Docker)

1. Start infrastructure only:

docker-compose up -d postgres rabbitmq keycloak seq

2. Run a service locally:

cd src/backend/Services/Automation/Api
dotnet run

3. Access Swagger UI:

# Each service has Swagger documentation
http://localhost:5005/swagger  # Automation
http://localhost:5001/swagger  # Camera Management
# ... etc

Production Deployment

# Build optimized images (60% smaller)
./scripts/build-all-chiseled.sh

# Deploy with production configuration
cp .env.example .env
# Edit .env with production credentials
docker-compose -f docker-compose.prod.yml up -d

See DEPLOYMENT.md for complete deployment guide.

🛠️ Technology Stack

Docker Image Variants

All services are available in 3 optimized variants:

Variant	Size per Service	Total (7 Services)	Security	Use Case
Standard	~220MB	~1.54GB	✅ Good	Development
Alpine	~110MB	~770MB	✅✅ Better	Staging
Chiseled	~90MB	~630MB	✅✅✅ Best	Production

Chiseled Images (recommended for production):

• No shell, no package manager
• Minimal attack surface
• 60% size reduction
• Ubuntu-based distroless

See DOCKER_OPTIMIZATION.md for details.

CI/CD Pipeline

Automated GitHub Actions workflows:

Build & Test (on every push):

• ✅ Build .NET solution
• ✅ Run 31 unit tests (85%+ coverage)
• ✅ Code quality checks
• ✅ Build Docker images (Alpine & Chiseled)
• ✅ Integration tests

Deploy (on release):

• ✅ Build production images
• ✅ Push to Docker Hub
• ✅ Deploy to Kubernetes
• ✅ Smoke tests
• ✅ Auto-rollback on failure

Backend (.NET 9)

• ASP.NET Core 9.0 - Web API framework
• Entity Framework Core 9.0 - ORM with PostgreSQL
• MediatR - CQRS pattern implementation
• FluentValidation - Request validation
• MassTransit - Message bus abstraction (RabbitMQ)
• SignalR - Real-time WebSocket communication
• FFmpeg - Stream processing and conversion
• OpenTelemetry - Distributed tracing and metrics

Frontend (React 19)

• React 19 with TypeScript 5.x
• Vite 6 - Next-generation build tool
• TanStack Query v5 - Data fetching, caching, and real-time invalidation
• React Router v7 - Type-safe navigation
• Material-UI v7 - Modern component library with emotion styling
• SignalR Client - Real-time WebSocket updates
• HLS.js - Adaptive HLS video playback
• Axios - HTTP client with interceptors

Infrastructure

• PostgreSQL 16 with TimescaleDB - Primary database + time-series
• Redis 7 - Caching and pub/sub
• RabbitMQ 3 - Message broker
• Prometheus - Metrics collection
• Grafana - Visualization dashboards
• Seq / ELK - Structured logging
• Docker & Kubernetes - Containerization and orchestration
• NGINX / Traefik - Reverse proxy and load balancing

📊 System Capabilities

Capability	Specification
Maximum Cameras	250 (horizontally scalable)
Concurrent Streams	250+ (with multiple Stream Keepers)
Stream Latency	< 2 seconds (target < 1s with WebRTC)
Supported Protocols	RTSP, ONVIF, HTTP, Proprietary SDKs
Video Formats	H.264, H.265, MJPEG
Output Formats	HLS, WebRTC (optional)
Max Resolution	Up to 4K (3840x2160)
Availability	24/7 operation, 99.5%+ uptime target
Event Throughput	1000+ events/second

🏭 Production Deployment

Docker Compose (Recommended for Single Server)

# Build Chiseled images (60% smaller, maximum security)
./scripts/build-all-chiseled.sh

# Configure environment
cp .env.example .env
nano .env  # Set POSTGRES_PASSWORD, RABBITMQ_PASSWORD, KEYCLOAK_AUTHORITY

# Deploy
docker-compose -f docker-compose.prod.yml up -d

# Verify
curl http://localhost:5001/health

Kubernetes Deployment

# Create namespace and secrets
kubectl create namespace smartsentinel-prod
kubectl create secret generic smartsentinel-secrets \
  --from-literal=postgres-password=<password> \
  --from-literal=rabbitmq-password=<password> \
  -n smartsentinel-prod

# Deploy services
kubectl apply -f k8s/ -n smartsentinel-prod

# Scale services
kubectl scale deployment camera-management --replicas=3 -n smartsentinel-prod
kubectl scale deployment automation --replicas=2 -n smartsentinel-prod

Health Checks

All services expose /health endpoints:

# Check all services
for port in 5001 5002 5003 5004 5005 5006 5007; do
  echo "Port $port: $(curl -s -o /dev/null -w "%{http_code}" http://localhost:$port/health)"
done

# Individual service
curl http://localhost:5005/health  # Automation

For detailed deployment instructions, see DEPLOYMENT.md.

🧪 Testing

Unit Tests

# Run all tests
cd src/backend
dotnet test SmartSentinelEye.sln

# Run specific service tests
cd Services/Automation
dotnet test

Test Coverage:

• 31 comprehensive unit tests for Automation service
• 85%+ coverage on critical paths
• xUnit + Moq + Shouldly framework
• See TEST_SUMMARY.md for details

Test Categories:

• CameraSequenceExecutor (12 tests)
• EventBasedRuleExecutor (11 tests)
• CameraRegisteredEventConsumer (5 tests)
• CameraDeletedEventConsumer (3 tests)

Integration Tests

# Run with Docker Compose
docker-compose up -d
dotnet test --filter Category=Integration

Manual Testing

See AUTOMATION_TESTING.md for comprehensive manual testing guide with curl examples.

🔒 Security

• Authentication: JWT tokens with refresh token rotation
• Authorization: Role-based (Admin, Operator, Display) + policy-based
• Encryption: TLS for all external communication, encrypted credentials at rest
• API Keys: For external system integration
• Rate Limiting: Prevents API abuse
• Audit Logging: All actions tracked with user context

📈 Monitoring & Observability

Metrics (Prometheus)

• Stream latency and frame rate per camera
• Service health and resource usage (CPU, memory, network)
• Message queue depth
• Database connection pool status
• Custom business metrics (camera switches, automation executions)

Dashboards (Grafana)

Pre-configured dashboards for:

• System overview
• Camera health status
• Streaming performance
• Event processing throughput
• Service-specific metrics

Structured Logging (Seq)

• Centralized log aggregation
• Correlation IDs for distributed tracing
• Log levels: Debug, Information, Warning, Error, Fatal
• Search and filtering by service, timestamp, context

🤝 Contributing

Contributions are welcome! Please read our CONTRIBUTING.md for guidelines.

Development Workflow

1. Create a feature branch: git checkout -b feature/your-feature
2. Make changes and commit: git commit -m "Add your feature"
3. Push to branch: git push origin feature/your-feature
4. Open a Pull Request

Code Standards

• Backend: Follow C# coding conventions, use nullable reference types
• Frontend: Use TypeScript strict mode, follow React best practices
• Testing: Maintain 80%+ code coverage for business logic
• Documentation: Update docs with significant changes

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👥 Authors

• Smart Solutions Lab - Initial architecture and development

🙏 Acknowledgments

• FFmpeg for stream processing
• TimescaleDB for time-series data
• .NET Community for excellent tooling
• React Community for frontend libraries

---

📞 Support

For issues, questions, or feature requests:

• GitHub Issues: https://github.com/smartsolutionslab/smart-sentinel-eye/issues
• Email: [email protected]
• Documentation: docs/

---

Built with ❤️ for industrial monitoring