- Live project portal: mtlab1122.github.io/Campus_Environment_DataVisualization_System
- Local interactive application: run
python run.py, then openhttp://127.0.0.1:5000/dashboard/ - API documentation: docs/api-documentation.md and the in-app
/api/docsportal - Graduation thesis: docs/thesis.md
- University approval presentation: Campus_Environment_System_Approval_Presentation.pptx
The live portal is a browser-based project overview and demonstration. The full Flask and Plotly Dash application runs locally or through a configured Python WSGI deployment.
The Campus Environment Data Visualization System is a full-stack Python application engineered to collect, store, process, analyze, and visualize multi-zone ambient and indoor environmental telemetry across educational campus grounds.
Integrating a high-performance Flask web core and an interactive Plotly Dash analytical dashboard, the platform enables students, faculty, and campus facility administrators to monitor ambient conditions, identify acoustic and atmospheric anomalies, and review empirical trend reports across multiple campus zones.
Modern university and college campuses host thousands of students, researchers, and staff across diverse functional facilities, such as libraries, crowded dining halls, multi-floor classroom blocks, specialized research laboratories, and outdoor sports grounds. These areas present contrasting environmental challenges:
-
Indoor Air Quality (IAQ) & Cognitive Decline: Poor ventilation in crowded lecture halls and study libraries leads to rapid accumulation of Carbon Dioxide (
$CO_2 > 1000\text{ ppm}$ ) and fine particulate matter ($PM_{2.5}$ ), inducing lethargy, headaches, and impaired cognitive retention. - Acoustic Pollution: Unregulated noise in academic libraries and residential dormitories disrupts concentration and restorative sleep.
-
Outdoor & Vehicular Particulates: Heavy traffic around campus gates and parking lots generates elevated
$PM_{10}$ and$PM_{2.5}$ exhaust plumes during morning and evening rush hours. - Fragmented Monitoring: Most institutions lack a unified, automated telemetry framework, relying instead on sporadic manual spot checks that fail to provide real-time alerts or historical insights.
-
Unified Atmospheric & Acoustic Sensing: Provide a centralized telemetry hub capturing Temperature, Humidity,
$PM_{2.5}$ ,$PM_{10}$ ,$CO_2$ , Noise, and standard US EPA Air Quality Index (AQI). - Multi-Zone Spatial Surveillance: Support granular monitoring across distinct campus zones (Main Gate, Library, Classroom Block, Cafeteria, Hostel, Playground, Parking Area, Laboratory Block).
- Automated Alerting: Continuously evaluate incoming readings against configurable multi-tiered thresholds (Warning, Poor, Dangerous) with instant dashboard flags and resolution logs.
- Rich Interactive Visualizations: Render publication-quality dynamic charts (multi-trace time trends, zone comparisons, real-time gauges, quartile distributions, diurnal heatmaps, and 5-axis spider radar comparisons).
- Campus Environmental Health Index (CEHI): Compute a holistic campus safety grade (0–100 score, A+ to F) evaluating AQI, thermal comfort, acoustics, and ventilation.
- Periodic Reporting & Open Data Access: Offer automated daily, weekly, and monthly statistical summaries with direct CSV data exports.
-
Role-Based Access Control (RBAC):
- Admin: Manage campus zones, provision sensor hardware, configure alert thresholds, ingest manual telemetry, and view audit reports.
- Viewer / Public: View real-time dashboards, filter readings, analyze charts, inspect alert histories, and download CSV reports.
- Campus Environmental Health Index (CEHI): Real-time weighted multi-factor health grade (A+ to F) combining EPA AQI, ASHRAE thermal comfort, and WHO noise guidelines.
- Multi-Dimensional Radar Matrix Chart: Interactive Plotly Radar visualization comparing all 8 campus zones across 5 normalized dimensions.
- Statistical Correlation Matrix: In-depth Pearson correlation computations identifying relationships between ambient parameters.
-
Interactive REST API Documentation Explorer (
/api/docs): Web-based testing console with single-click live endpoint queries. -
Realistic Telemetry Simulation: Built-in mock IoT data generation service implementing solar diurnal equations, inverse humidity curves, and zone-specific occupancy spikes, plus instantaneous pulse firing (
/api/readings/simulate-pulse). -
Automated EPA Air Quality Indexing: Dynamic calculation of AQI based on EPA piecewise linear interpolation for
$PM_{2.5}$ and$PM_{10}$ . - Multi-Dimensional Dashboard Filtering: Instant filtering by Campus Zone, Primary Parameter, Calendar Date Range, and Daily Hour Window slider.
- Historical Data Seeding: Ready-to-run seeder generating 7+ days of realistic hourly telemetry across all campus zones.
- Automated 100% Passing Test Suite: 27 unit, integration, and live server tests executing seamlessly via pytest.
The application backend, analytics, dashboard authoring, API, and persistence workflow are Python-centered. Dash serves the reactive browser client, while the repository also includes a lightweight static GitHub Pages portal for project presentation.
| Layer | Technology | Purpose |
|---|---|---|
| Language | Python 3.10+ (verified with Python 3.14.7) | Core execution runtime |
| Web Framework | Flask 3.1+ | WSGI application, routing, and REST API |
| Visualization & Dashboard | Plotly Dash 2.17+ & Dash Bootstrap Components | Interactive reactive dashboard |
| ORM & Persistence | SQLAlchemy 2.0+ & Flask-SQLAlchemy | Object-relational mapping and database abstraction |
| Database Engine | SQLite 3 | Embedded zero-configuration ACID relational database |
| Data Science & Analytics | Pandas 2.2+ & NumPy 1.26+ | DataFrames, rolling metrics, and statistical aggregations |
| Authentication & Security | Flask-Login & Werkzeug Security | Session authentication and salted SHA-256 password hashing |
| Environment Management | python-dotenv | Secure .env configuration parsing |
| Synthetic Data Generation | Faker & custom math diurnal model | Realistic sensor data generation |
| Automated Testing | Pytest 8.0+ | Unit and integration test suite |
+----------------------------------+
| Web Browser |
| (Desktop / Tablet / Mobile UI) |
+----------------------------------+
|
HTTP GET/POST (HTML / JSON) & Dash Reactive Callbacks
|
v
+-----------------------------------------------------------------------------------+
| FLASK WSGI APPLICATION CORE |
| |
| +-----------------------+ +-----------------------+ +----------------------+ |
| | Jinja2 Web Views | | REST API Routes | | Plotly Dash App | |
| | - /login, /register | | - /api/zones | | - URL: /dashboard/ | |
| | - /admin/zones | | - /api/sensors | | - KPI Metric Cards | |
| | - /admin/sensors | | - /api/readings | | - Interactive Graphs | |
| | - /admin/thresholds | | - /api/alerts | | - Reactive Callbacks | |
| | - /admin/manual | | - /api/reports | | - Filter Controls | |
| +-----------------------+ +-----------------------+ +----------------------+ |
| | |
| v |
| +-----------------------------------------------------------------------------+ |
| | BUSINESS LOGIC | |
| | +---------------------+ +----------------------+ +----------------------+ | |
| | | Alert Rule Engine | | Analytics & Pandas | | EPA AQI Calculator | | |
| | +---------------------+ +----------------------+ +----------------------+ | |
| +-----------------------------------------------------------------------------+ |
| | |
| v |
| +-----------------------------------------------------------------------------+ |
| | SQLAlchemy ORM MODELS | |
| | User • CampusZone • Sensor • EnvironmentalReading • Alert • ... | |
| +-----------------------------------------------------------------------------+ |
+-----------------------------------------------------------------------------------+
|
v
+-------------------------------+
| SQLite Relational Storage |
| (campus_environment.db) |
+-------------------------------+
The repository adheres to a modular, decoupled architecture:
campus-environment-dashboard/
├── README.md # Comprehensive documentation and run guide
├── requirements.txt # Pinned Python package dependencies
├── .env.example # Template environment configuration file
├── .env # Local configuration instance
├── run.py # Application entry point script
├── config.py # Development, Testing, and Production configs
├── docs/
│ ├── thesis.md # Complete graduation thesis (University format)
│ ├── system-design.md # In-depth system architectural design
│ ├── api-documentation.md # Detailed REST API specification
│ └── screenshots/ # Interface screenshot placeholders
├── app/
│ ├── __init__.py # Application factory (create_app)
│ ├── extensions.py # SQLAlchemy and LoginManager instances
│ ├── models/ # Database schema models
│ │ ├── __init__.py
│ │ ├── user.py # User account & RBAC model
│ │ ├── campus_zone.py # Geographic campus zone model
│ │ ├── sensor.py # Hardware telemetry sensor model
│ │ ├── environmental_reading.py # Time-series environmental readings
│ │ └── alert.py # Alert thresholds and violation logs
│ ├── routes/ # Flask Web & REST API Blueprints
│ │ ├── __init__.py
│ │ ├── auth.py # Session login, logout, and token auth
│ │ ├── zones.py # Zone CRUD endpoints & admin views
│ │ ├── sensors.py # Sensor provisioning & admin views
│ │ ├── readings.py # Telemetry ingestion & query endpoints
│ │ ├── alerts.py # Threshold customization & alert resolve
│ │ └── reports.py # Aggregation reports & CSV downloads
│ ├── services/ # Business logic services
│ │ ├── __init__.py
│ │ ├── data_generator.py # Mock IoT telemetry generator & seeder
│ │ ├── analytics.py # Pandas time-series aggregation & KPIs
│ │ ├── alert_service.py # Real-time threshold evaluation
│ │ └── report_service.py # Period reports & CSV formatter
│ ├── dashboard/ # Plotly Dash analytical application
│ │ ├── __init__.py # Dash mounting onto Flask
│ │ ├── layout.py # Reactive layout tree
│ │ ├── callbacks.py # Interactivity and graph updates
│ │ └── components/ # Reusable UI components
│ │ ├── __init__.py
│ │ ├── navbar.py # Top navigation bar
│ │ ├── metric_cards.py # Real-time KPI summaries
│ │ ├── filter_panel.py # Zone, date, parameter filter controls
│ │ ├── charts.py # Plotly line, bar, gauge, box, heatmaps
│ │ ├── alerts_table.py # Active alert notification items
│ │ └── reports_view.py # Summary report tables
│ ├── templates/ # Jinja2 HTML templates
│ │ ├── base.html # Global layout and navigation wrapper
│ │ ├── login.html # User login interface
│ │ ├── register.html # Viewer registration interface
│ │ ├── admin_zones.html # Zone management panel
│ │ ├── admin_sensors.html # Sensor hardware management
│ │ ├── admin_thresholds.html # Alert rules configuration
│ │ └── manual_entry.html # Manual telemetry ingestion form
│ ├── static/ # Static assets
│ │ ├── css/
│ │ │ └── custom.css # Custom styling, elevations, animations
│ │ └── js/
│ │ └── main.js # Client-side utility scripts
│ └── utils/ # Helper utilities
│ ├── __init__.py
│ ├── aqi_calculator.py # US EPA piecewise AQI interpolation
│ ├── decorators.py # RBAC @admin_required guards
│ └── helpers.py # API response formatting & datetime parsers
├── seed/
│ ├── __init__.py
│ └── seed_data.py # Complete database seeder script
└── tests/ # Automated test suite
├── __init__.py
├── conftest.py # Pytest fixtures and test database
├── test_api.py # REST API integration tests
├── test_models.py # SQLAlchemy entity tests
└── test_alerts.py # Threshold rules and AQI calculation tests
- Python 3.10 or higher installed on your operating system (
python --version). - Git command line utility.
cd campus-environment-dashboardpython -m venv venv
.\venv\Scripts\activatepython3 -m venv venv
source venv/bin/activatepython -m pip install --upgrade pip
pip install -r requirements.txtCreate a local .env configuration file from the provided .env.example:
# Windows
copy .env.example .env
# macOS / Linux
cp .env.example .envContents of .env:
FLASK_APP=run.py
FLASK_ENV=development
FLASK_DEBUG=1
SECRET_KEY=campus-env-secret-key-super-secure-change-in-production-2026
DATABASE_URL=sqlite:///campus_environment.db
PORT=5000
HOST=127.0.0.1The database tables are automatically initialized upon launching the application or running the seeding script. To initialize manually:
python -c "from app import create_app, db; app = create_app('development'); app.app_context().push(); db.create_all(); print('Database tables created.')"Run the automated seeding script to provision system users, the 8 default campus zones, 8 sensor telemetry stations, safety thresholds, and 7 days of realistic historical hourly telemetry:
python seed/seed_data.pyExpected output:
Creating database schema tables...
Provisioning system user accounts...
[+] Created default Admin account: admin / admin123
[+] Created default Viewer account: viewer / viewer123
Provisioning campus geographic zones...
[+] Added Campus Zone: Main Gate (ZONE_GATE)
[+] Added Campus Zone: Library (ZONE_LIB)
[+] Added Campus Zone: Classroom Block (ZONE_CLASS)
...
Configuring safety thresholds...
[+] Alert thresholds verified.
Generating realistic 7-day time-series telemetry...
Successfully generated 1352 environmental readings.
DATABASE SEEDING COMPLETED SUCCESSFULLY!
Launch the full web server and integrated Plotly Dash analytical application:
python run.pyAccess the system in your web browser:
- Interactive Dashboard:
http://127.0.0.1:5000/dashboard/ - Admin Zone Management:
http://127.0.0.1:5000/admin/zones - Admin Sensor Provisioning:
http://127.0.0.1:5000/admin/sensors - Admin Alert Thresholds:
http://127.0.0.1:5000/admin/thresholds - Manual Data Ingestion:
http://127.0.0.1:5000/admin/readings/manual - REST API Root:
http://127.0.0.1:5000/api/
For local demonstration and evaluation:
| Account Type | Username | Password | Role | Permissions |
|---|---|---|---|---|
| System Administrator | admin |
admin123 |
admin |
Full CRUD zones, sensors, thresholds, manual ingestion |
| General Viewer | viewer |
viewer123 |
viewer |
View dashboard, filter telemetry, resolve alerts, download reports |
All endpoints use JSON payloads and return structured responses:
| Method | Endpoint | Access | Purpose |
|---|---|---|---|
POST |
/api/auth/login |
Public | Authenticate user session |
POST |
/api/auth/logout |
Authenticated | Terminate session |
GET |
/api/auth/me |
Public | Inspect current user session |
GET |
/api/zones |
Public | List all campus zones |
POST |
/api/zones |
Admin | Create a new campus zone |
PUT |
/api/zones/<id> |
Admin | Update campus zone |
DELETE |
/api/zones/<id> |
Admin | Remove campus zone |
GET |
/api/sensors |
Public | List sensors (filter by zone_id, status) |
POST |
/api/sensors |
Admin | Register new hardware sensor station |
GET |
/api/readings |
Public | Filter telemetry (zone_id, start_date, etc.) |
POST |
/api/readings |
Public | Ingest sensor telemetry (IoT hardware) |
GET |
/api/readings/latest |
Public | Latest readings for all campus zones |
GET |
/api/alerts |
Public | Query alerts (filter by severity, is_resolved) |
PUT |
/api/alerts/<id>/resolve |
Public | Mark active alert as resolved |
GET |
/api/alerts/thresholds |
Public | List parameter threshold rules |
PUT |
/api/alerts/thresholds/<id> |
Admin | Update threshold parameters |
GET |
/api/reports/summary |
Public | Daily, weekly, monthly aggregated report |
GET |
/api/reports/export-csv |
Public | Download filtered telemetry CSV file |
GET |
/api/dashboard/stats |
Public | Consolidated real-time metrics |
For complete payload and schema documentation, see docs/api-documentation.md.
The Plotly Dash dashboard at /dashboard/ provides:
-
Air Quality Index (AQI) Banner: Prominently displays campus composite AQI with dynamic color indicators:
-
Good (0–50): Emerald Green (
#10B981) -
Moderate (51–100): Amber (
#F59E0B) -
Poor (101–200): Crimson Red (
#EF4444) -
Dangerous (>200): Deep Maroon (
#7F1D1D)
-
Good (0–50): Emerald Green (
-
Key Metric Summary Cards: Displays current values and 24-hour comparative trend percentages for Temperature, Humidity,
$PM_{2.5}$ ,$PM_{10}$ ,$CO_2$ , and Noise. - Interactive Temporal Trend Chart: Multi-line Plotly visualization with range sliders, time-window buttons, and unified hover tooltips.
- Gauge Indicator Dial: Visualizes current pollutant concentration against safe, warning, and dangerous threshold arcs.
- Campus Zone Comparison Bar Chart: Horizontal bar chart comparing parameter averages across all zones.
- Variance Box Plot: Statistical distribution showing quartiles, medians, and outliers across campus blocks.
- Diurnal Heatmap: Matrix visualization of 24-hour daily cycles across zones.
- Interactive Telemetry Table: Native sorting, column filtering, and pagination for individual sensor records.
- One-Click CSV Export: Download filtered data directly to local disk.
Alerts are generated when ingested telemetry violates configured rules:
| Environmental Parameter | Warning Limit | Poor Limit | Dangerous Limit | Primary Risk |
|---|---|---|---|---|
| Fine Particulates ( |
Respiratory irritation, asthma | |||
| Coarse Particulates ( |
Airborne dust, vehicular exhaust | |||
| Carbon Dioxide ( |
Lethargy, cognitive fatigue | |||
| Acoustic Noise | Study disruption, hearing fatigue | |||
| Ambient Temperature |
|
|
|
Heat stress, thermal discomfort |
| Relative Humidity |
|
|
|
Mold growth, skin dryness |
Screenshots demonstrating the working system are organized in docs/screenshots/:
docs/screenshots/dashboard_overview.png: Main dashboard showing metric cards, AQI status, and trend charts.docs/screenshots/charts_comparison.png: Zone comparison bar chart, distribution box plot, and diurnal heatmap.docs/screenshots/alerts_panel.png: Active environmental alerts and resolution controls.docs/screenshots/admin_zones.png: Admin zone management interface.docs/screenshots/manual_entry.png: Manual telemetry ingestion interface.
The test suite includes unit tests for SQLAlchemy models, alert rules, and AQI calculations, plus integration tests for all REST API endpoints.
Execute the test suite with pytest:
pytest -vExpected output:
============================= test session starts =============================
platform win32 -- Python 3.15.0, pytest-9.1.1
collected 17 items
tests/test_alerts.py::test_aqi_calculation PASSED [ 5%]
tests/test_alerts.py::test_alert_rule_evaluation PASSED [ 11%]
tests/test_alerts.py::test_alert_resolution PASSED [ 17%]
tests/test_api.py::test_auth_login_and_me PASSED [ 23%]
tests/test_api.py::test_get_zones PASSED [ 29%]
tests/test_api.py::test_create_zone_unauthenticated PASSED [ 35%]
tests/test_api.py::test_create_zone_forbidden_for_viewer PASSED [ 41%]
tests/test_api.py::test_create_zone_admin_success PASSED [ 47%]
tests/test_api.py::test_sensor_endpoints PASSED [ 52%]
tests/test_api.py::test_telemetry_reading_ingestion PASSED [ 58%]
tests/test_api.py::test_get_readings_with_filters PASSED [ 64%]
tests/test_api.py::test_dashboard_stats_and_reports PASSED [ 70%]
tests/test_models.py::test_user_password_hashing PASSED [ 76%]
tests/test_models.py::test_admin_user_role PASSED [ 82%]
tests/test_models.py::test_campus_zone_model PASSED [ 88%]
tests/test_models.py::test_sensor_and_reading_relationship PASSED [ 94%]
tests/test_models.py::test_alert_model PASSED [100%]
====================== 17 passed in 8.65s =======================
- MQTT & LoRaWAN Gateway Integration: Add an MQTT broker bridge (such as Eclipse Mosquitto) for direct sensor transmission from ESP32 / Arduino microcontrollers over low-power LoRaWAN networks.
- Machine Learning Predictive Forecasting: Train ARIMA or LSTM neural network models in Python to forecast particulate concentrations 24 hours in advance.
- Automated Notification Dispatch: Integrate Webhooks, SMS (Twilio), or email alerts to campus security when Dangerous thresholds are exceeded.
- Geographic GIS Mapping: Embed a Leaflet or Mapbox interactive campus map showing real-time sensor node positions and air quality heat plumes.
This project is open-source and released under the MIT License. You are free to modify, distribute, and integrate this software into institutional and educational deployments.

