Carbon Track

Carbon Track is a real-time emissions monitoring system designed for KTDA tea factories. The architecture comprises three primary components:

• IoT Measurement System:
  • Hardware: ESP32 microcontroller interfaced with NDIR CO₂ sensors (0-5000ppm range), K-type thermocouples (-50°C to 1350°C), and anemometers (0-20m/s range)
  • Data Acquisition: Continuous sampling at 5-second intervals with ±2% accuracy for CO₂ and ±1.5°C for temperature
  • Communication: MQTT protocol (QoS 1) with TLS 1.3 encryption for secure data transmission
  • Deployment: Sensors installed 1-2 meters above chimney base with weatherproof enclosures (IP67 rating)
• Backend Processing System:
  • Framework: Django 4.2+ with Django REST Framework 3.14.0
  • Database: PostgreSQL 15.0 with TimescaleDB extension for time-series data
  • Data Processing:
    • Emissions calculation: CO₂ (kg/s) = (C × V × A × M) / (R × T) where C=concentration, V=velocity, A=area, M=molar mass, R=gas constant, T=temperature
    • Data validation: Range checks and outlier detection using IQR method
    • Aggregation: 1-minute, 1-hour, and 24-hour rollups with configurable retention policies
  • API Layer: RESTful endpoints with JWT authentication (OAuth 2.0), rate limiting (100 req/min), and OpenAPI 3.0 documentation
  • WebSocket Support: Real-time bidirectional communication for emission data transmission from frontend
  • Message Broker: HiveMQ Community Edition 2023.4 with MQTT over WebSockets support
• Web Portal Applications:
  • Factory Portal:
    • Authentication: Role-based access control (RBAC) with factory-specific permissions
    • Data Input: Forms for energy source entry (firewood, diesel, electricity) with unit conversion utilities
    • Visualization: Real-time dashboards with Chart.js 4.3.0 showing emission trends, energy usage, and compliance metrics
    • WebSocket Integration: Real-time emission data transmission to backend via WebSocket connections
    • Reporting: Automated PDF reports with factory-specific KPIs and regulatory compliance status
  • KTDA Portal:
    • Network Analytics: Comparative views of all factories with filtering by region, size, and production capacity
    • Performance Benchmarking: Leaderboards ranked by emission intensity (kg CO₂/kg tea produced)
    • Compliance Tracking: Regulatory status dashboard with EU CBAM compliance indicators
    • Data Export: CSV, JSON, and PDF formats with customizable date ranges and metrics

Refer to subsequent sections for detailed technical specifications, API references, and deployment procedures.

• Real-Time Emissions Monitoring: Continuous measurement of CO₂ concentration (ppm) converted to mass flow (kg/s) using sensor data and chimney dimensions
• WebSocket Data Transmission: Bidirectional real-time communication between frontend and backend for emission data updates
• Energy Usage Logging: Web-based interface for recording energy consumption with automated unit conversions and validation
• Performance Benchmarking: Factory ranking system based on emission intensity metrics and compliance scores
• Historical Data Analysis: Interactive time-series charts with zoomable periods and comparative overlays
• Regulatory Compliance: Automated report generation for EU Carbon Border Adjustment Mechanism (CBAM) and local environmental regulations

• KTDA Manager:
  • Responsibilities: Network-wide emissions oversight, regulatory compliance, strategic decision-making
  • Access Level: Full system access with KTDA Portal privileges
• Factory Manager:
  • Responsibilities: Local emissions monitoring, energy data entry, equipment maintenance
  • Access Level: Factory-specific access with data entry and view permissions

• IoT Hardware:
  • Microcontroller: ESP32-WROOM-32 (dual-core 240MHz, Wi-Fi & Bluetooth)
  • Sensors: MH-Z19B CO₂ sensor, MAX6675 thermocouple amplifier, Adafruit anemometer
  • Power: 12V DC with battery backup (UPS)
• Backend:
  • Framework: Django 4.2.7 with DRF 3.14.0
  • Database: PostgreSQL 15.2 with TimescaleDB 2.12.0
  • Message Broker: HiveMQ 2023.4 Community Edition
  • WebSocket Implementation: Django Channels 4.0.0 for real-time bidirectional communication
  • Authentication: Simple JWT 5.3.0 with OAuth 2.0
• Frontend:
  • Framework: Next.js 13.5.4 with React 18.2.0
  • Rendering: Server-Side Rendering (SSR) and Static Site Generation (SSG) for optimal performance
  • WebSocket Client: Socket.IO 4.7.2 for real-time data transmission
  • Visualization: Chart.js 4.3.0 with react-chartjs-2
  • Styling: Tailwind CSS 3.3.3 with custom components
  • Routing: Next.js App Router for file-based routing and layout system
• Documentation:
  • API Docs: drf-yasg 1.21.7 for OpenAPI 3.0
  • Testing: Postman 10.18.9 collection

The system implements a three-tier architecture with the following components:

• Data Acquisition Layer:
  • Sensors deployed in factory chimneys collect environmental data
  • ESP32 microcontrollers process raw sensor data and format as JSON messages
  • Data transmission via MQTT to HiveMQ broker (TLS encrypted)
• Processing Layer:
  • Django backend consumes MQTT messages via paho-mqtt client
  • Data validation and transformation using Django serializers
  • Emissions calculations performed before storage in PostgreSQL
  • RESTful API endpoints exposed for frontend consumption
  • WebSocket endpoints for real-time bidirectional communication
• Presentation Layer:
  • Next.js-based web portals with role-based access control
  • Server-Side Rendering (SSR) for improved SEO and initial page load performance
  • WebSocket connections for real-time data transmission to backend
  • Interactive dashboards with Chart.js visualizations
• Data Flow:
  • Sensors → ESP32 → MQTT Broker → Django API → PostgreSQL → Next.js Portals
  • Energy input → Factory Portal → Django API → PostgreSQL
  • Real-time emission data → Factory Portal (WebSocket) → Django API → PostgreSQL
• Deployment:
  • Backend: Heroku dynos with PostgreSQL add-on
  • Frontend: Vercel for Next.js deployment with automatic SSR/SSG
  • MQTT Broker: AWS EC2 t3.medium instance
  • WebSocket Server: Django Channels with Daphne ASGI server
  • CDN: Cloudflare for static assets
• Security:
  • Transport: TLS 1.3 encryption for all communications
  • Authentication: JWT tokens with 15-minute expiration
  • Authorization: Django permissions framework with custom roles
  • WebSocket Security: Token-based authentication and origin validation

System Architecture Diagram:

IoT Device (Carbon Track IoT)

• Hardware Specifications:
  • Microcontroller: ESP32-WROOM-32 (240MHz dual-core, 4MB flash)
  • CO₂ Sensor: MH-Z19B (0-5000ppm, ±50ppm + 3% reading)
  • Temperature Sensor: K-type thermocouple with MAX6675 amplifier (0°C to 1024°C)
  • Anemometer: Adafruit 1733 (0-32.4m/s, ±3% accuracy)
  • Power: 12V DC input with 18650 battery backup (2000mAh)
• Firmware Implementation:
  • Development Platform: Arduino IDE 2.2.1 with ESP32 board manager 2.0.11
  • Libraries: PubSubClient 2.8.0, ArduinoJson 6.21.3, MAX6675 1.0.0
  • Sampling Rate: 5-second intervals with configurable sleep modes
  • Data Format: JSON payload with timestamp, sensor readings, and device ID
  • Error Handling: Watchdog timer, sensor failure detection, automatic reconnection
• Deployment Requirements:
  • Installation Height: 1-2 meters above chimney base
  • Environmental Protection: IP67-rated enclosure with desiccant
  • Calibration: Biannual calibration using certified gas mixtures

Backend System

• Technical Stack:
  • Framework: Django 4.2.7 with Python 3.11.5
  • API: Django REST Framework 3.14.0 with drf-yasg 1.21.7
  • Database: PostgreSQL 15.2 with TimescaleDB 2.12.0 extension
  • WebSocket: Django Channels 4.0.0 with Daphne ASGI server
  • Authentication: Simple JWT 5.3.0 with OAuth 2.0
  • MQTT: paho-mqtt 1.6.1 with HiveMQ broker
• Core Functionality:
  • Data Ingestion: MQTT consumer with message queue processing
  • WebSocket Handling: Real-time emission data reception from frontend
  • Validation: Range checks, data type validation, outlier detection
  • Calculations: Emissions mass flow, energy conversion factors
  • Storage: Time-series data with hypertable partitioning
  • API Endpoints: RESTful services with OpenAPI documentation
  • Scheduled Tasks: Report generation, data aggregation, notifications
• Repository:
  • URL: github.com/akirachix/carbontrack-backend.git
  • Branching Strategy: GitFlow with main, develop, and feature branches
  • CI/CD: GitHub Actions with automated testing and deployment

Database Schema

• Core Models:
  • User: Django's built-in User model with custom profile
  • Factory: Factory details with location and capacity data
  • MCUDevice: IoT device information with calibration records
  • Emission: Time-series emission data with calculated mass flow
  • EnergyEntry: Energy consumption records with source types
  • ComplianceReport: Generated reports with regulatory metrics
• Schema Implementation:
  • Migrations: Django migrations with TimescaleDB hypertables
  • Indexes: Time-based partitioning and composite indexes
  • Constraints: Foreign keys, unique constraints, check constraints

Web Portal Applications

• Factory Portal:
  • Framework: Next.js 13.5.4 with App Router architecture
  • Authentication: Factory-specific login with session management
  • Dashboard: Real-time emissions chart, energy input form, compliance status
  • Data Input: Energy source forms with unit conversion and validation
  • WebSocket Integration: Real-time emission data transmission to backend
  • Reports: PDF generation with factory-specific metrics
  • Responsive Design: Mobile-first approach with Tailwind CSS
  • Performance: Server-Side Rendering for improved SEO and initial load times
• KTDA Portal:
  • Framework: Next.js 13.5.4 with App Router architecture
  • Authentication: Role-based access with administrative privileges
  • Network View: Map-based factory overview with emission indicators
  • Analytics: Comparative charts, trend analysis, forecasting
  • Leaderboard: Factory ranking with emission intensity metrics
  • Compliance: Regulatory status dashboard with CBAM indicators
  • Data Export: Multi-format export with customizable parameters
  • Performance: Server-Side Rendering for improved SEO and initial load times
• Technical Implementation:
  • Framework: Next.js 13.5.4 with React 18.2.0
  • State Management: React Context API with useReducer
  • Data Fetching: Axios 1.5.0 with request interceptors and Next.js data fetching methods
  • WebSocket Client: Socket.IO 4.7.2 for real-time data transmission
  • Visualization: Chart.js 4.3.0 with react-chartjs-2
  • Styling: Tailwind CSS 3.3.3 with custom components
  • Routing: Next.js App Router for file-based routing and layout system
  • Rendering: Hybrid approach with SSR for dashboard pages and SSG for static content

• Authentication:
  • POST /api/register/: User registration with factory association
  • POST /api/login/: JWT token generation with device fingerprinting
  • POST /api/token/refresh/: JWT token refresh
• Energy Management:
  • GET /api/energy-entries/: List energy entries with filtering
  • POST /api/energy-entries/: Create new energy entry
  • PUT /api/energy-entries/{id}/: Update energy entry
  • DELETE /api/energy-entries/{id}/: Delete energy entry
• Emissions Data:
  • GET /api/emissions/: List emission data with time filtering
  • POST /api/emissions/: Create emission record (IoT only)
  • GET /api/emissions/aggregate/: Aggregated emission data
  • WebSocket /ws/emissions/: Real-time emission data submission
• Factory Management:
  • GET /api/factories/: List factories with emission metrics
  • GET /api/factories/{id}/: Factory details with current status
  • GET /api/factories/leaderboard/: Factory performance ranking
• Compliance:
  • GET /api/compliance/reports/: List compliance reports
  • POST /api/compliance/reports/: Generate new report
  • GET /api/compliance/status/: Current compliance status
• Device Management:
  • GET /api/mcu-devices/: List IoT devices
  • POST /api/mcu-devices/: Register new device
  • PUT /api/mcu-devices/{id}/: Update device configuration

Prerequisites

• Python 3.11.5 or later
• pip 23.2.1 or uv 0.1.11 package manager
• PostgreSQL 15.2 with TimescaleDB extension
• Git 2.42.0 or later
• Node.js 18.18.0 or later (for frontend)

Backend Installation

1. Clone repository: git clone https://github.com/akirachix/carbontrack-backend.git
2. Navigate to project directory: cd carbontrack-backend
3. Create virtual environment: python -m venv venv
4. Activate virtual environment:
   • Linux/macOS: source venv/bin/activate
   • Windows: venv\Scripts\activate
5. Install dependencies: pip install -r requirements.txt
6. Configure environment variables:
   DEBUG=False
   SECRET_KEY=your-secret-key
   DATABASE_URL=postgresql://user:password@localhost/dbname
   MQTT_HOST=your-mqtt-broker
   MQTT_PORT=1883
   MQTT_USERNAME=your-mqtt-user
   MQTT_PASSWORD=your-mqtt-password
7. Apply database migrations: python manage.py migrate
8. Create superuser: python manage.py createsuperuser
9. Collect static files: python manage.py collectstatic
10. Run development server: python manage.py runserver
11. Run WebSocket server: daphne -p 8001 carbontrack.asgi:application

Frontend Installation

1. Navigate to frontend directory: cd frontend
2. Install dependencies: npm install
3. Configure environment variables in .env.local:
   NEXT_PUBLIC_API_URL=http://localhost:8000/api
   NEXT_PUBLIC_WS_URL=ws://localhost:8001/ws/emissions/
4. Run development server: npm run dev

Production Deployment

• Backend:
  • Deploy to Heroku with PostgreSQL add-on
  • Configure environment variables via Heroku Config Vars
  • Enable automatic builds from GitHub repository
  • Set up worker dyno for MQTT message processing
  • Configure WebSocket server with Daphne ASGI server
• Frontend:
  • Build optimized bundle: npm run build
  • Deploy to Vercel with environment variables
  • Configure custom domain and SSL certificates
  • Enable Server-Side Rendering and Static Site Generation in Vercel dashboard
• MQTT Broker:
  • Deploy HiveMQ to AWS EC2 t3.medium instance
  • Configure TLS certificates for secure connections
  • Set up authentication and authorization policies

• Hardware Assembly:
  • Connect sensors to ESP32 according to pin configuration:
    CO₂ Sensor: VIN → 5V, GND → GND, TX → D2, RX → D3
    Thermocouple: VCC → 3.3V, GND → GND, SCK → D5, CS → D6, SO → D7
    Anemometer: Red → 5V, Black → GND, Yellow → D1
  • Install components in IP67 enclosure with proper cable glands
  • Connect 12V DC power supply with battery backup
• Firmware Configuration:
  • Install ESP32 board manager in Arduino IDE
  • Flash firmware with sensor libraries:
    #include <WiFi.h>
    #include <PubSubClient.h>
    #include <ArduinoJson.h>
    #include <MHZ19.h>
    #include <MAX6675.h>
  • Configure WiFi and MQTT credentials:
    const char* ssid = "your-ssid";
    const char* password = "your-password";
    const char* mqtt_server = "your-mqtt-broker";
    const int mqtt_port = 1883;
    const char* mqtt_user = "your-mqtt-user";
    const char* mqtt_password = "your-mqtt-password";
  • Set sampling interval and calibration parameters
• Deployment Procedure:
  • Mount enclosure 1-2 meters above chimney base
  • Ensure sensors are positioned away from direct flame
  • Connect power supply and verify LED indicators
  • Test data transmission to MQTT broker
  • Perform initial calibration with certified gas mixture

• Transport Layer Security:
  • MQTT: TLS 1.3 encryption with mutual authentication
  • API: HTTPS with HSTS header and TLS 1.3 cipher suites
  • WebSocket: WSS (WebSocket Secure) with TLS 1.3 encryption
  • Database: SSL/TLS encrypted connections
• Authentication & Authorization:
  • JWT tokens with 15-minute expiration and refresh tokens
  • Role-based access control (RBAC) with factory-specific permissions
  • OAuth 2.0 integration for enterprise identity providers
  • WebSocket Authentication: Token-based authentication with origin validation
• Data Protection:
  • Input validation and sanitization for all user inputs
  • Parameterized queries to prevent SQL injection
  • Content Security Policy (CSP) headers for XSS prevention
  • Sensitive data encryption at rest using AES-256
  • WebSocket Message Validation: Schema validation for all WebSocket messages
• Network Security:
  • Firewall rules restricting access to essential ports
  • VPN access for administrative interfaces
  • DDoS protection with rate limiting and request validation
  • WebSocket Rate Limiting: Message frequency limits to prevent abuse
• Monitoring & Auditing:
  • Comprehensive logging of all system activities
  • Real-time security event monitoring with alerts
  • Regular vulnerability scanning and penetration testing
  • WebSocket Connection Monitoring: Tracking of all active connections

• Testing Strategy:
  • Unit Tests: Django TestCase with 95% code coverage
  • Integration Tests: MQTT message flow validation
  • WebSocket Tests: Socket.IO client-server communication validation
  • API Tests: Postman collections with automated validation
  • Frontend Tests: React Testing Library with Jest and Next.js specific testing
  • End-to-End Tests: Cypress for critical user journeys
• Quality Assurance:
  • Code Review: Pull request reviews with automated checks
  • Static Analysis: ESLint, Pylint, and Bandit integration
  • Performance Testing: Locust simulation for 1000 concurrent users
  • WebSocket Performance Testing: Load testing with multiple concurrent connections
  • Security Testing: OWASP ZAP and Burp Suite scans
• Monitoring:
  • Application Performance: New Relic APM with custom dashboards
  • Infrastructure: AWS CloudWatch for resource utilization
  • WebSocket Monitoring: Connection metrics, message throughput, and error rates
  • Error Tracking: Sentry with real-time alerts
  • Uptime Monitoring: Pingdom with 1-minute checks
• Success Metrics:
  • System Uptime: 99.9% availability target
  • Data Accuracy: 5% deviation from reference measurements
  • API Performance: 200ms response time for 95% of requests
  • WebSocket Performance: 100ms message latency for 95% of transmissions
  • Security Incidents: Zero critical vulnerabilities in production

• Version Control:
  • Git repository with semantic versioning
  • Branching strategy: GitFlow with main, develop, and feature branches
  • Automated tagging for releases
• Scaling Strategy:
  • Horizontal Scaling: Load balancer with multiple dynos
  • Database: Read replicas for reporting workloads
  • Caching: Redis for session storage and API responses
  • WebSocket Scaling: Horizontal scaling with Redis-based message broker
  • Message Queue: RabbitMQ for background processing
  • Next.js Scaling: Serverless functions for API routes and edge caching for static assets
• Disaster Recovery:
  • Automated daily backups with 30-day retention
  • Multi-region deployment for critical components
  • Failover procedures with documented runbooks
• Connectivity Mitigation:
  • Local buffering for IoT devices during outages
  • Automatic reconnection with exponential backoff
  • Data synchronization on connection restoration
  • WebSocket Reconnection: Automatic reconnection with backoff strategy

• Software Requirements:
  • Python 3.11.5 or later
  • pip 23.2.1 or uv 0.1.11 package manager
  • PostgreSQL 15.2 with TimescaleDB extension
  • Git 2.42.0 or later
  • Node.js 18.18.0 or later
  • Next.js 13.5.4
  • Arduino IDE 2.2.1 with ESP32 board manager
• Hardware Requirements:
  • IoT Devices: ESP32-WROOM-32 microcontrollers
  • Sensors: MH-Z19B CO₂ sensors, K-type thermocouples, anemometers
  • Server: Minimum 2 vCPUs, 4GB RAM for production backend
  • Database: Minimum 4 vCPUs, 16GB RAM, 100GB SSD storage
• Network Requirements:
  • Stable internet connection with minimum 10 Mbps upload
  • Public IP address for MQTT broker
  • Firewall rules allowing ports 443 (HTTPS), 1883 (MQTT), 8080 (MQTT WebSocket), 8001 (WebSocket)
• Operational Requirements:
  • Technical staff with Python/Django expertise
  • Electrical engineering support for IoT deployment
  • Database administration capabilities
  • DevOps resources for deployment and maintenance
  • Next.js development experience for frontend implementation
  • WebSocket development experience for real-time features

Complete backend installation sequence:

Complete frontend installation sequence: