│ │Access │ │Infrastructure│ │Physical │ │ │ │Control │ │Security │ │Access Control │ │ │ │ │ │ │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Authentication Flow Diagram ``` ┌─────────────────┐ │ Client │ │ Request │ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ User-Agent │ │ Detection │ └────────┬────────┘ │ ┌────▼────┐ │Particle?│ └────┬────┘ │ ┌────▼────┐ ┌─────────────────┐ │ YES │──────────────▶│Bearer Token │ └─────────┘ │Validation │ │ └────────┬────────┘ │ │ │ ▼ │ ┌─────────────────┐ │ │Token Match? │ │ └────────┬────────┘ │ │ │ ┌────▼────┐ │ │ YES │ │ └────┬────┘ │ │ ┌────▼────┐ ┌────────▼────────┐ │ NO │──────────────▶│HMAC Signature │ └─────────┘ │Verification │ └────────┬────────┘ │ ▼ ┌─────────────────┐ │Signature Valid? │ └────────┬────────┘ │ ┌────▼────┐ │ YES │ └────┬────┘ │ ▼ ┌─────────────────┐ │Request │ │Processing │ └─────────────────┘ ``` ## 📦 Component Architecture ### Application Layer Components ``` ┌─────────────────────────────────────────────────────────────────┐ │ FLASK APPLICATION │ ├─────────────────────────────────────────────────────────────────┤ │ REQUEST HANDLERS │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │/health │ │/webhook │ │/metrics (future) │ │ │ │GET │ │POST │ │GET │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ ├─────────────────────────────────────────────────────────────────┤ │ MIDDLEWARE │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │Request │ │Error │ │Security │ │ │ │Logging │ │Handling │ │Headers │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ ├─────────────────────────────────────────────────────────────────┤ │ CORE SERVICES │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │Authentication│ │Input │ │Notification │ │ │ │Service │ │Validation │ │Service │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ ├─────────────────────────────────────────────────────────────────┤ │ UTILITY MODULES │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │HMAC │ │Email/SMS │ │Configuration │ │ │ │Verification │ │Formatting │ │Management │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Detailed Component Breakdown **Authentication Service:** ```python class AuthenticationService: def __init__(self): self.particle_secret = os.environ.get('PARTICLE_WEBHOOK_SECRET') self.webhook_secret = os.environ.get('WEBHOOK_SECRET') def verify_particle_auth(self, auth_header): """Verify Bearer token for Particle webhooks""" # Implementation details def verify_hmac_signature(self, payload, signature): """Verify HMAC-SHA256 signature for generic webhooks""" # Implementation details def is_particle_webhook(self, user_agent): """Detect Particle webhook requests""" # Implementation details ``` **Input Validation Service:** ```python class ValidationService: def __init__(self): self.required_fields = ['event', 'data', 'published_at'] self.particle_fields = ['coreid', 'device_name', 'fw_version'] def validate_json_structure(self, data): """Validate JSON payload structure""" # Implementation details def validate_field_types(self, data): """Validate data types for all fields""" # Implementation details def sanitize_input(self, data): """Sanitize input data for security""" # Implementation details ``` **Notification Service:** ```python class NotificationService: def __init__(self): self.smtp_config = self._load_smtp_config() self.templates = self._load_templates() def send_email_notification(self, message, webhook_data): """Send email/SMS notification""" # Implementation details def format_message(self, webhook_data): """Format notification message from webhook data""" # Implementation details def _load_smtp_config(self): """Load SMTP configuration from environment""" # Implementation details ``` ## 🔄 Container Architecture ### Docker Container Structure ``` ┌─────────────────────────────────────────────────────────────────┐ │ CONTAINER IMAGE │ ├─────────────────────────────────────────────────────────────────┤ │ BASE IMAGE LAYER │ │ python:3.11-slim (Debian-based minimal Python runtime) │ ├─────────────────────────────────────────────────────────────────┤ │ SYSTEM DEPENDENCIES │ │ curl (for health checks), ca-certificates (SSL) │ ├─────────────────────────────────────────────────────────────────┤ │ PYTHON DEPENDENCIES │ │ Flask, Gunicorn, Werkzeug (from requirements.txt) │ ├─────────────────────────────────────────────────────────────────┤ │ APPLICATION LAYER │ │ webhook_app.py, configuration files │ ├─────────────────────────────────────────────────────────────────┤ │ USER & PERMISSIONS │ │ Non-root user 'appuser', minimal file permissions │ ├─────────────────────────────────────────────────────────────────┤ │ RUNTIME CONFIGURATION │ │ WORKDIR /app, EXPOSE 5000, health check configuration │ └─────────────────────────────────────────────────────────────────┘ ``` ### Multi-Stage Build Process ```dockerfile # Stage 1: Build Environment FROM python:3.11-slim as builder WORKDIR /build COPY requirements.txt . RUN pip install --user --no-cache-dir -r requirements.txt # Stage 2: Runtime Environment FROM python:3.11-slim as runtime RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/* RUN groupadd -r appuser && useradd -r -g appuser appuser WORKDIR /app COPY --from=builder /root/.local /home/appuser/.local COPY --chown=appuser:appuser webhook_app.py . USER appuser ENV PATH=/home/appuser/.local/bin:$PATH EXPOSE 5000 HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \ CMD curl -f http://localhost:5000/health || exit 1 CMD ["gunicorn", "--bind", "0.0.0.0:5000", "--workers", "2", "--timeout", "30", "webhook_app:app"] ``` ### Container Resource Management ```yaml # Resource limits and reservations deploy: resources: limits: cpus: '0.5' # Maximum 0.5 CPU cores memory: 256M # Maximum 256MB RAM reservations: cpus: '0.1' # Guaranteed 0.1 CPU cores memory: 128M # Guaranteed 128MB RAM restart_policy: condition: unless-stopped delay: 5s max_attempts: 3 window: 120s ``` ## 🌐 Network Architecture ### Network Topology ``` ┌─────────────────────────────────────────────────────────────────┐ │ EXTERNAL NETWORKS │ ├─────────────────────────────────────────────────────────────────┤ │ Internet ──▶ Router ──▶ Port Forwarding ──▶ Server │ │ │ 80 → 80 (HTTP) │ │ │ 443 → 443 (HTTPS) │ │ └─────────2222 → 2222 (SSH Git) │ └─────────────────────────────────────────────────────────────────┘ │ ┌─────────────────────────────────────▼───────────────────────────┐ │ DOCKER NETWORKS │ ├─────────────────────────────────────────────────────────────────┤ │ ┌─────────────────┐ ┌─────────────────┐ │ │ │ traefik │ │ Service │ │ │ │ (external) │ │ Networks │ │ │ │ │ │ (internal) │ │ │ │ ┌─────────────┐ │ │ ┌─────────────┐ │ │ │ │ │webhook- │ │ │ │gitea- │ │ │ │ │ │service │ │ │ │internal │ │ │ │ │ └─────────────┘ │ │ └─────────────┘ │ │ │ │ ┌─────────────┐ │ │ ┌─────────────┐ │ │ │ │ │traefik │ │ │ │harbor- │ │ │ │ │ │proxy │ │ │ │harbor │ │ │ │ │ └─────────────┘ │ │ └─────────────┘ │ │ │ │ ┌─────────────┐ │ │ │ │ │ │ │gitea │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ └─────────────┘ │ │ │ │ │ │ ┌─────────────┐ │ │ │ │ │ │ │harbor │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ └─────────────┘ │ │ │ │ │ └─────────────────┘ └─────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Service Discovery and Routing ``` ┌─────────────────────────────────────────────────────────────────┐ │ TRAEFIK ROUTING │ ├─────────────────────────────────────────────────────────────────┤ │ Request Flow: │ │ │ │ webhook.domain.com ──▶ Traefik ──▶ webhook-service:5000 │ │ git.domain.com ──▶ Traefik ──▶ gitea:3000 │ │ registry.domain.com──▶ Traefik ──▶ harbor:80 │ │ traefik.domain.com ──▶ Traefik ──▶ dashboard:8080 │ │ │ │ Routing Rules: │ │ - Host header matching │ │ - Automatic service discovery via Docker labels │ │ - Health check integration │ │ - Load balancing (when multiple instances) │ └─────────────────────────────────────────────────────────────────┘ ``` ### SSL/TLS Architecture ``` ┌─────────────────────────────────────────────────────────────────┐ │ SSL/TLS TERMINATION │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Client ──[TLS 1.3]──▶ Traefik ──[HTTP]──▶ Backend Service │ │ │ │ │ ▼ │ │ ┌─────────────┐ │ │ │Let's Encrypt│ │ │ │Certificate │ │ │ │Management │ │ │ └─────────────┘ │ │ │ │ Features: │ │ - Automatic certificate generation │ │ - Automatic renewal (60 days before expiry) │ │ - HTTP to HTTPS redirection │ │ - HSTS headers │ │ - Perfect Forward Secrecy │ └─────────────────────────────────────────────────────────────────┘ ``` ## 📊 Data Architecture ### Data Flow Patterns **Synchronous Request-Response:** ``` Client Request ──▶ Authentication ──▶ Validation ──▶ Processing ──▶ Response │ │ │ │ │ │ ▼ ▼ ▼ │ │ Security Check Schema Check Business │ │ Rate Limit Field Types Logic │ │ IP Filter Sanitization Notification │ │ Dispatch │ │ │ └──────────────────── Immediate Response ◀─────────────────────┘ ``` **Asynchronous Notification Processing:** ``` Webhook Event ──▶ Queue ──▶ Background Worker ──▶ Email/SMS Gateway │ │ │ │ │ │ ▼ ▼ │ │ Notification Delivery │ │ Formatting Confirmation │ │ │ │ │ │ ▼ ▼ │ │ Template Status │ │ Engine Tracking │ │ │ │ └─────── Retry Logic ◀─────────────────┘ │ └────────── Immediate Response (webhook success) ``` ### Data Models **Webhook Event Data Model:** ```python from dataclasses import dataclass from datetime import datetime from typing import Optional @dataclass class WebhookEvent: event: str data: str published_at: str coreid: Optional[str] = None device_name: Optional[str] = None fw_version: Optional[str] = None received_at: datetime = None source_ip: str = None user_agent: str = None def is_particle_event(self) -> bool: return self.coreid is not None def get_device_info(self) -> dict: return { 'device_id': self.coreid, 'device_name': self.device_name or self.coreid, 'firmware_version': self.fw_version } ``` **Notification Data Model:** ```python @dataclass class NotificationRequest: event_type: str device_info: dict message: str priority: str # low, normal, high, critical recipients: list delivery_method: str # email, sms, both retry_count: int = 0 max_retries: int = 3 def should_retry(self) -> bool: return self.retry_count < self.max_retries ``` ### Configuration Management **Environment-based Configuration:** ```python class Config: def __init__(self): self.flask_secret = os.environ.get('FLASK_SECRET_KEY') self.webhook_secret = os.environ.get('WEBHOOK_SECRET') self.particle_secret = os.environ.get('PARTICLE_WEBHOOK_SECRET') self.smtp_config = self._load_smtp_config() self.security_config = self._load_security_config() def _load_smtp_config(self): return { 'server': 'smtp.gmail.com', 'port': 465, 'username': os.environ.get('SMTP_EMAIL'), 'password': os.environ.get('SMTP_PASSWORD'), 'use_tls': True } def _load_security_config(self): return { 'rate_limit': { 'requests_per_minute': 10, 'burst_size': 20 }, 'auth_timeout': 30, 'max_payload_size': 1024 # bytes } ``` ## 🔍 Monitoring Architecture ### Observability Stack ``` ┌─────────────────────────────────────────────────────────────────┐ │ MONITORING LAYER │ ├─────────────────────────────────────────────────────────────────┤ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │ Metrics │ │ Logs │ │ Traces │ │ │ │ │ │ │ │ │ │ │ │ Prometheus │ │ Loki │ │ Jaeger │ │ │ │ (Future) │ │ (Future) │ │ (Future) │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ ├─────────────────────────────────────────────────────────────────┤ │ CURRENT MONITORING │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │ Docker │ │ File │ │ Health │ │ │ │ Logs │ │ Logs │ │ Checks │ │ │ │ │ │ │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Health Check Architecture **Multi-Level Health Checks:** ``` ┌─────────────────────────────────────────────────────────────────┐ │ HEALTH CHECK LAYERS │ ├─────────────────────────────────────────────────────────────────┤ │ Level 1: Container Health │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │Process │ │Port │ │Basic HTTP │ │ │ │Running │ │Listening │ │Response │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ ├─────────────────────────────────────────────────────────────────┤ │ Level 2: Application Health │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │Flask App │ │Database │ │External Dependencies │ │ │ │Responding │ │Connection │ │(SMTP, etc.) │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ ├─────────────────────────────────────────────────────────────────┤ │ Level 3: Business Logic Health │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │Authentication│ │Notification │ │End-to-End │ │ │ │Service │ │Service │ │Functionality │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Logging Architecture **Structured Logging:** ```python import logging import json from datetime import datetime class StructuredLogger: def __init__(self, name): self.logger = logging.getLogger(name) self.logger.setLevel(logging.INFO) handler = logging.StreamHandler() formatter = logging.Formatter('%(message)s') handler.setFormatter(formatter) self.logger.addHandler(handler) def log_event(self, level, event_type, message, **kwargs): log_data = { 'timestamp': datetime.utcnow().isoformat(), 'level': level, 'event_type': event_type, 'message': message, 'component': 'webhook-service', **kwargs } self.logger.log(getattr(logging, level.upper()), json.dumps(log_data)) # Usage logger = StructuredLogger('webhook') logger.log_event('info', 'webhook_received', 'Particle webhook authenticated', device_id='abc123', source_ip='1.2.3.4') ``` ## 🚀 Deployment Architecture ### Deployment Pipeline ``` ┌─────────────────────────────────────────────────────────────────┐ │ DEPLOYMENT PIPELINE │ ├─────────────────────────────────────────────────────────────────┤ │ Development ──▶ Testing ──▶ Staging ──▶ Production │ │ │ │ │ │ │ │ ▼ ▼ ▼ ▼ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │Local │ │Unit │ │Integration│ │Blue/Green│ │ │ │Testing │ │Tests │ │Testing │ │Deploy │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ ├─────────────────────────────────────────────────────────────────┤ │ GITOPS WORKFLOW │ │ │ │ Git Push ──▶ CI/CD ──▶ Image Build ──▶ Deploy ──▶ Monitor │ │ │ │ │ │ │ │ │ ▼ ▼ ▼ ▼ ▼ │ │ Code Automated Docker Container Health │ │ Review Testing Registry Deployment Checks │ └─────────────────────────────────────────────────────────────────┘ ``` ### Environment Architecture **Multi-Environment Setup:** ``` ┌─────────────────────────────────────────────────────────────────┐ │ ENVIRONMENTS │ ├─────────────────────────────────────────────────────────────────┤ │ Development Environment │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │Local Docker │ │File-based │ │Mock Services │ │ │ │Compose │ │Logging │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ ├─────────────────────────────────────────────────────────────────┤ │ Staging Environment │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │Production │ │Structured │ │Real Services │ │ │ │Like Setup │ │Logging │ │(Limited) │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ ├─────────────────────────────────────────────────────────────────┤ │ Production Environment │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │High │ │Centralized │ │Full Service │ │ │ │Availability │ │Monitoring │ │Integration │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Scaling Architecture **Horizontal Scaling Strategy:** ``` ┌─────────────────────────────────────────────────────────────────┐ │ SCALING PATTERNS │ ├─────────────────────────────────────────────────────────────────┤ │ Single Instance (Current) │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ Traefik ──▶ Webhook Service Instance │ │ │ └─────────────────────────────────────────────────────────┘ │ ├─────────────────────────────────────────────────────────────────┤ │ Multiple Instances (Future) │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ Traefik ──┬──▶ Webhook Service Instance 1 │ │ │ │ ├──▶ Webhook Service Instance 2 │ │ │ │ └──▶ Webhook Service Instance N │ │ │ └─────────────────────────────────────────────────────────┘ │ ├─────────────────────────────────────────────────────────────────┤ │ Database-Backed (Advanced) │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ Multiple Instances ──▶ Shared Database │ │ │ │ ──▶ Message Queue │ │ │ │ ──▶ Shared State │ │ │ └─────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ## 🔄 Integration Architecture ### External System Integration ``` ┌─────────────────────────────────────────────────────────────────┐ │ INTEGRATION POINTS │ ├─────────────────────────────────────────────────────────────────┤ │ Inbound Integrations │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │Particle │ │GitHub │ │Custom │ │ │ │Webhooks │ │Webhooks │ │Services │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ ├─────────────────────────────────────────────────────────────────┤ │ Outbound Integrations │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │SMTP/Email │ │SMS Gateways │ │Monitoring │ │ │ │Services │ │ │ │Systems │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ ├─────────────────────────────────────────────────────────────────┤ │ Future Integrations │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │Slack/Discord│ │Database │ │Analytics │ │ │ │Webhooks │ │Logging │ │Platforms │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ### API Design Architecture **RESTful API Design:** ``` ┌─────────────────────────────────────────────────────────────────┐ │ API ENDPOINTS │ ├─────────────────────────────────────────────────────────────────┤ │ GET /health │ │ ├─ Purpose: Health check endpoint │ │ ├─ Authentication: None │ │ ├─ Response: JSON health status │ │ └─ Caching: No cache │ ├─────────────────────────────────────────────────────────────────┤ │ POST /webhook │ │ ├─ Purpose: Process incoming webhook events │ │ ├─ Authentication: Bearer token or HMAC signature │ │ ├─ Request: JSON payload with event data │ │ ├─ Response: JSON success/error status │ │ └─ Rate Limiting: 10 req/min average, 20 burst │ ├─────────────────────────────────────────────────────────────────┤ │ GET /metrics (Future) │ │ ├─ Purpose: Prometheus metrics endpoint │ │ ├─ Authentication: Internal network only │ │ ├─ Response: Prometheus format metrics │ │ └─ Caching: 30 second cache │ ├─────────────────────────────────────────────────────────────────┤ │ POST /test (Development Only) │ │ ├─ Purpose: Test notification delivery │ │ ├─ Authentication: Same as webhook │ │ ├─ Request: Test message payload │ │ └─ Response: Delivery confirmation │ └─────────────────────────────────────────────────────────────────┘ ``` ### Error Handling Architecture **Hierarchical Error Management:** ```python class WebhookError(Exception): """Base webhook exception""" def __init__(self, message, status_code=500, error_code=None): self.message = message self.status_code = status_code self.error_code = error_code super().__init__(self.message) class AuthenticationError(WebhookError): """Authentication related errors""" def __init__(self, message): super().__init__(message, 403, "AUTH_FAILED") class ValidationError(WebhookError): """Input validation errors""" def __init__(self, message): super().__init__(message, 400, "VALIDATION_FAILED") class NotificationError(WebhookError): """Notification delivery errors""" def __init__(self, message): super().__init__(message, 500, "NOTIFICATION_FAILED") # Error Handler @app.errorhandler(WebhookError) def handle_webhook_error(error): response = { "error": error.message, "error_code": error.error_code, "timestamp": datetime.utcnow().isoformat() } return jsonify(response), error.status_code ``` ## 📈 Performance Architecture ### Performance Optimization Strategies ``` ┌─────────────────────────────────────────────────────────────────┐ │ PERFORMANCE LAYERS │ ├─────────────────────────────────────────────────────────────────┤ │ Application Level │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │Async │ │Connection │ │Response │ │ │ │Processing │ │Pooling │ │Caching │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ ├─────────────────────────────────────────────────────────────────┤ │ Server Level │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │Gunicorn │ │Worker │ │Keep-Alive │ │ │ │WSGI Server │ │Processes │ │Connections │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ ├─────────────────────────────────────────────────────────────────┤ │ Infrastructure Level │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │Load │ │CDN │ │Resource │ │ │ │Balancing │ │(Future) │ │Optimization │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Caching Architecture **Multi-Level Caching Strategy:** ```python from functools import lru_cache from threading import Lock import time class CacheManager: def __init__(self): self._memory_cache = {} self._cache_lock = Lock() self._ttl_cache = {} @lru_cache(maxsize=128) def get_config_value(self, key): """Application-level configuration caching""" return os.environ.get(key) def cache_with_ttl(self, key, value, ttl_seconds=300): """TTL-based caching for dynamic data""" with self._cache_lock: expiry = time.time() + ttl_seconds self._memory_cache[key] = value self._ttl_cache[key] = expiry def get_cached(self, key): """Retrieve cached value if not expired""" with self._cache_lock: if key in self._memory_cache: if time.time() < self._ttl_cache.get(key, 0): return self._memory_cache[key] else: # Expired, clean up del self._memory_cache[key] del self._ttl_cache[key] return None ``` ### Resource Optimization **Memory Management:** ```python import gc import psutil import threading class ResourceMonitor: def __init__(self): self.max_memory_mb = 256 # Container limit self.warning_threshold = 0.8 self.monitoring_interval = 60 # seconds def start_monitoring(self): """Start background resource monitoring""" def monitor(): while True: memory_usage = psutil.virtual_memory().percent if memory_usage > self.warning_threshold * 100: logger.warning(f"High memory usage: {memory_usage}%") gc.collect() # Force garbage collection time.sleep(self.monitoring_interval) thread = threading.Thread(target=monitor, daemon=True) thread.start() ``` ## 🔒 Security Deep Dive ### Threat Model ``` ┌─────────────────────────────────────────────────────────────────┐ │ THREAT ANALYSIS │ ├─────────────────────────────────────────────────────────────────┤ │ External Threats │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │DDoS Attacks │ │Injection │ │Unauthorized │ │ │ │ │ │Attacks │ │Access │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ ├─────────────────────────────────────────────────────────────────┤ │ Internal Threats │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │Configuration│ │Container │ │Supply Chain │ │ │ │Vulnerabilities│ │Escape │ │Attacks │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ ├─────────────────────────────────────────────────────────────────┤ │ Mitigation Strategies │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │Defense in │ │Principle of │ │Security │ │ │ │Depth │ │Least │ │Monitoring │ │ │ │ │ │Privilege │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Security Controls Matrix ``` ┌─────────────────┬─────────────────┬─────────────────┬─────────────────┐ │ Control Type │ Implementation│ Threat │ Effectiveness │ ├─────────────────┼─────────────────┼─────────────────┼─────────────────┤ │ Authentication │ Bearer Token │ Unauthorized │ High │ │ │ HMAC Signature │ Access │ │ ├─────────────────┼─────────────────┼─────────────────┼─────────────────┤ │ Input Validation│ JSON Schema │ Injection │ High │ │ │ Type Checking │ Attacks │ │ ├─────────────────┼─────────────────┼─────────────────┼─────────────────┤ │ Rate Limiting │ Traefik │ DDoS │ Medium │ │ │ Middleware │ │ │ ├─────────────────┼─────────────────┼─────────────────┼─────────────────┤ │ Container │ Non-root User │ Container │ High │ │ Security │ Minimal Base │ Escape │ │ ├─────────────────┼─────────────────┼─────────────────┼─────────────────┤ │ Network │ Internal │ Network │ High │ │ Isolation │ Docker Networks │ Attacks │ │ ├─────────────────┼─────────────────┼─────────────────┼─────────────────┤ │ Encryption │ TLS 1.3 │ Data │ High │ │ │ Let's Encrypt │ Interception │ │ └─────────────────┴─────────────────┴─────────────────┴─────────────────┘ ``` ### Cryptographic Architecture **Key Management:** ```python import secrets import hashlib import hmac from cryptography.fernet import Fernet class CryptoManager: def __init__(self): self.webhook_secret = os.environ.get('WEBHOOK_SECRET') self.particle_secret = os.environ.get('PARTICLE_WEBHOOK_SECRET') def verify_hmac_signature(self, payload, signature, secret): """Verify HMAC-SHA256 signature""" expected_signature = hmac.new( secret.encode('utf-8'), payload, hashlib.sha256 ).hexdigest() # Use constant-time comparison to prevent timing attacks return hmac.compare_digest( f"sha256={expected_signature}", signature ) def generate_secure_token(self, length=32): """Generate cryptographically secure random token""" return secrets.token_hex(length) def hash_sensitive_data(self, data): """Hash sensitive data for logging""" return hashlib.sha256(data.encode()).hexdigest()[:8] ``` ## 🔮 Future Architecture Considerations ### Microservices Evolution **Current Monolithic Architecture:** ``` ┌─────────────────────────────────────────────────────────────────┐ │ MONOLITHIC SERVICE │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │Authentication│ │Validation │ │Notification │ │ │ │ │ │ │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` **Future Microservices Architecture:** ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ Auth Service │ │ Validation │ │ Notification │ │ │ │ Service │ │ Service │ │ - Bearer Token │ │ │ │ │ │ - HMAC Verify │ │ - Schema Check │ │ - Email Service │ │ - Rate Limiting │ │ - Sanitization │ │ - SMS Service │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │ │ └─────────────────────┼───────────────────────┘ │ ┌─────────────────┐ │ API Gateway │ │ │ │ - Routing │ │ - Load Balance │ │ - SSL Term │ └─────────────────┘ ``` ### Database Integration **Current State (Stateless):** ``` Request → Process → Response (No Persistence) ``` **Future Database Integration:** ``` ┌─────────────────────────────────────────────────────────────────┐ │ DATABASE LAYER │ ├─────────────────────────────────────────────────────────────────┤ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │PostgreSQL │ │Redis Cache │ │Time Series DB │ │ │ │ │ │ │ │(InfluxDB) │ │ │ │ - Events │ │ - Sessions │ │ │ │ │ │ - Devices │ │ - Rate Limit│ │ - Metrics │ │ │ │ - Users │ │ - Config │ │ - Analytics │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Event-Driven Architecture **Future Event Bus Integration:** ``` ┌─────────────────────────────────────────────────────────────────┐ │ EVENT BUS │ ├─────────────────────────────────────────────────────────────────┤ │ Webhook Event ──▶ Event Bus ──▶ Multiple Consumers │ │ │ │ │ ├──▶ Notification Service │ │ ├──▶ Analytics Service │ │ ├──▶ Alerting Service │ │ ├──▶ Audit Service │ │ └──▶ Archive Service │ │ │ │ Technologies: Apache Kafka, RabbitMQ, Redis Streams │ └─────────────────────────────────────────────────────────────────┘ ``` ### Cloud Migration Path **Phase 1: Containerized (Current)** ``` On-Premise Server → Docker Containers → Manual Management ``` **Phase 2: Orchestrated** ``` Docker Swarm or Kubernetes → Auto-scaling → Health Management ``` **Phase 3: Cloud Native** ``` AWS ECS/EKS, Azure ACI/AKS, or GCP Cloud Run → Serverless Options ``` **Phase 4: Serverless** ``` AWS Lambda, Azure Functions, GCP Cloud Functions → Event-Driven ``` --- ## 📋 Architecture Decision Records (ADRs) ### ADR-001: Flask Web Framework Choice **Status:** Accepted **Date:** 2024-01-07 **Context:** Need lightweight web framework for webhook processing. **Decision:** Use Flask with Gunicorn WSGI server. **Rationale:** - Lightweight and minimal for simple webhook processing - Excellent ecosystem and community support - Easy to containerize and scale - Gunicorn provides production-grade WSGI serving **Consequences:** - Simple to develop and maintain - Limited built-in features require additional libraries - Single-threaded request processing per worker ### ADR-002: Docker Containerization **Status:** Accepted **Date:** 2024-01-07 **Context:** Need consistent deployment across environments. **Decision:** Use Docker containers with multi-stage builds. **Rationale:** - Consistent runtime environment - Easy integration with existing Traefik infrastructure - Simplified deployment and scaling - Security isolation **Consequences:** - Additional complexity in development workflow - Resource overhead from containerization - Container security considerations ### ADR-003: Dual Authentication Strategy **Status:** Accepted **Date:** 2024-01-07 **Context:** Support both Particle.io webhooks and generic webhooks. **Decision:** Implement Bearer token auth for Particle, HMAC for generic. **Rationale:** - Particle.io supports Bearer tokens natively - HMAC signatures provide strong security for generic webhooks - User-Agent detection provides reliable differentiation **Consequences:** - Increased complexity in authentication logic - Need to maintain two secret management strategies - Clear separation of authentication methods ### ADR-004: Synchronous Processing **Status:** Accepted **Date:** 2024-01-07 **Context:** Choose between synchronous and asynchronous webhook processing. **Decision:** Use synchronous processing with immediate response. **Rationale:** - Simple implementation and debugging - Low latency requirements for security alerts - Current volume doesn't require async processing - Easier error handling and retry logic **Consequences:** - Limited scalability for high-volume scenarios - Blocking operations may impact response times - Simpler architecture and fewer components --- **📊 Architecture Summary:** This webhook service architecture provides: ✅ **Scalable Foundation** - Ready for growth from single instance to microservices ✅ **Security First** - Multiple layers of security controls and monitoring ✅ **Operational Excellence** - Comprehensive logging, monitoring, and health checks ✅ **Performance Optimized** - Caching, resource management, and efficiency focus ✅ **Integration Ready** - Clean APIs and extensible notification system ✅ **Future Proof** - Clear migration paths to cloud and serverless architectures The architecture balances simplicity for current needs with flexibility for future requirements, ensuring the system can evolve as the security device network scales.# Webhook Server Architecture Documentation Comprehensive technical architecture documentation for the secure webhook service component of the ultra-low-power security device system. ## 🏗️ System Architecture Overview ``` ┌─────────────────────────────────────────────────────────────────┐ │ INTERNET │ └──────────────────────────┬──────────────────────────────────────┘ │ ┌──────────────────────────▼──────────────────────────────────────┐ │ EDGE LAYER │ │ ┌─────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │ │ Firewall │ │ Load Balancer │ │ DDoS Protection │ │ │ │ (UFW) │ │ (Optional) │ │ (Cloudflare) │ │ │ └─────────────┘ └─────────────────┘ └─────────────────────┘ │ └──────────────────────────┬──────────────────────────────────────┘ │ ┌──────────────────────────▼──────────────────────────────────────┐ │ REVERSE PROXY LAYER │ │ ┌─────────────────────────────────────────────────────────────┐│ │ │ TRAEFIK ││ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ ││ │ │ │SSL/TLS │ │Rate Limiting│ │Security Headers │ ││ │ │ │Termination │ │& Throttling │ │& Middleware │ ││ │ │ └─────────────┘ └─────────────┘ └─────────────────────┘ ││ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ ││ │ │ │Service │ │Health Checks│ │Automatic SSL │ ││ │ │ │Discovery │ │& Monitoring │ │(Let's Encrypt) │ ││ │ │ └─────────────┘ └─────────────┘ └─────────────────────┘ ││ │ └─────────────────────────────────────────────────────────────┘│ └──────────────────────────┬──────────────────────────────────────┘ │ ┌──────────────────────────▼──────────────────────────────────────┐ │ APPLICATION LAYER │ │ ┌─────────────────────────────────────────────────────────────┐│ │ │ WEBHOOK SERVICE ││ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ ││ │ │ │Flask App │ │Gunicorn │ │Authentication │ ││ │ │ │ │ │WSGI Server │ │Handler │ ││ │ │ └─────────────┘ └─────────────┘ └─────────────────────┘ ││ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ ││ │ │ │Input │ │Business │ │Output │ ││ │ │ │Validation │ │Logic │ │Notification │ ││ │ │ └─────────────┘ └─────────────┘ └─────────────────────┘ ││ │ └─────────────────────────────────────────────────────────────┘│ └──────────────────────────┬──────────────────────────────────────┘ │ ┌──────────────────────────▼──────────────────────────────────────┐ │ CONTAINER LAYER │ │ ┌─────────────────────────────────────────────────────────────┐│ │ │ DOCKER ││ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ ││ │ │ │Container │ │Volume │ │Network │ ││ │ │ │Runtime │ │Management │ │Isolation │ ││ │ │ └─────────────┘ └─────────────┘ └─────────────────────┘ ││ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ ││ │ │ │Health │ │Log │ │Resource │ ││ │ │ │Monitoring │ │Management │ │Limits │ ││ │ │ └─────────────┘ └─────────────┘ └─────────────────────┘ ││ │ └─────────────────────────────────────────────────────────────┘│ └──────────────────────────┬──────────────────────────────────────┘ │ ┌──────────────────────────▼──────────────────────────────────────┐ │ INFRASTRUCTURE LAYER │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │ Host OS │ │ Storage │ │ Networking │ │ │ │ (Ubuntu) │ │ (SSD) │ │ (Docker Bridge) │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ## 🔄 Data Flow Architecture ### Request Processing Pipeline ``` External Request → Authentication → Validation → Processing → Response ↓ ↓ ↓ ↓ Security Input Business Output Layer Validation Logic Formatting ↓ ↓ ↓ ↓ Rate Limit Schema Check Event Success/Error Check Required Processing Response ↓ Fields ↓ ↓ IP Filter Data Types Notification Logging Check Validation Dispatch ↓ ↓ ↓ ↓ Metrics Auth Token Sanitization Email/SMS Collection Verification ↓ Service ↓ Clean Data ↓ Access ↓ Delivery Granted Validated Confirmation Request ``` ### Event Processing Flow ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Particle │ │ Particle │ │ Webhook │ │ Device │───▶│ Cloud │───▶│ Service │ │ │ │ │ │ │ │ - Sensor Event │ │ - Event Storage │ │ - Authentication│ │ - Data Payload │ │ - Webhook │ │ - Validation │ │ - Device Info │ │ Delivery │ │ - Processing │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ ▼ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Notification │ │ Email/SMS │ │ Response │ │ Formatting │◀───│ Gateway │◀───│ Generation │ │ │ │ │ │ │ │ - Message │ │ - SMTP Server │ │ - Status Code │ │ Template │ │ - SMS Gateway │ │ - JSON Response │ │ - Device Context│ │ - Delivery │ │ - Logging │ └─────────────────┘ └─────────────────┘ └─────────────────┘ ``` ## 🔐 Security Architecture ### Defense in Depth Model ``` ┌─────────────────────────────────────────────────────────────────┐ │ Layer 7: Application Security │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │Input │ │Business │ │Output │ │ │ │Validation │ │Logic │ │Sanitization │ │ │ │ │ │Security │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────┐ │ Layer 6: Authentication & Authorization │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │Bearer Token │ │HMAC │ │User-Agent │ │ │ │Validation │ │Signature │ │Detection │ │ │ │ │ │Verification │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────┐ │ Layer 5: Transport Security │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │TLS 1.3 │ │Certificate │ │HSTS Headers │ │ │ │Encryption │ │Validation │ │ │ │ │ │ │ │ │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────┐ │ Layer 4: Network Security │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │Rate │ │IP │ │DDoS │ │ │ │Limiting │ │Filtering │ │Protection │ │ │ │ │ │ │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────┐ │ Layer 3: Container Security │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │Non-root │ │Resource │ │Minimal Attack │ │ │ │User │ │Limits │ │Surface │ │ │ │ │ │ │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────┐ │ Layer 2: Host Security │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │UFW │ │fail2ban │ │OS Security │ │ │ │Firewall │ │Intrusion │ │Updates │ │ │ │ │ │Prevention │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────┐ │ Layer 1: Physical Security │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │Server │ │Network │ │Physical │ │ │ │Access │ │Infrastructure│ │Access Control │ │ │ │Control │ │Security │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘