85 KiB
85 KiB
│ │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:
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:
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
# 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
# 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:
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:
@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:
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:
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:
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:
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:
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:
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 │ │ │ │
│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘