comminusense

Important project context:

• This project was built for NMDC (National Mineral Development Corporation) - India’s largest iron ore mining PSU
  https://www.nmdc.co.in/

• This project was selected as Top 5 National Project for the Smart India Hackathon (SIH) Grand Finale 2025

• The deployed project can be accessed here too: https://www.comminusense.tech/

• Problem statement regarding this project was SIH 25210 Title: Efficient Energy Use in Iron Ore Mining Operations
  Organization: Ministry of Steel (MoS)

• This project is a collaborative effort of 6 members
  The project was built collaboratively, with each member contributing to different components including system design, frontend, backend, ML models, simulation, and integration.

• This project was developed exclusively for the Smart India Hackathon Grand Finals and will not remain under active development beyond the hackathon.

• A detailed YouTube video explaining the architecture, ML workflows, simulations, and implementation will be published as part of our SIH project series.
  (YouTube link will be added here once released.)

• CommuniSense was built through extensive domain research, planning, system architecture design, and large-scale implementation, combining industrial IoT, time-series analytics, ML optimization, and digital twin simulations.

• This README and related documentation will be updated incrementally for clarity and completeness.

About the project:

ComminuSense is a software platform that ingests high-frequency machine telemetry (real sensors or simulated IoT), stores time-series data, runs ML models (energy optimizer, predictive maintenance), exposes model recommendations and simulation results (digital twin), and provides a role-based dashboard for Operators / Engineers / Maintenance / Management. The system supports simulated closed-loop control (for demo) and a path to safe on-site integration (edge gateway, IEC/ISA security guidance

Roles:

Operator — view live telemetry, acknowledge alarms, start/stop local simulator runs. (Can’t change model thresholds.)

Shift Supervisor — all Operator + accept/implement AI suggestions, manual setpoint override.

Process Engineer — can run simulations, view ML model explainability data, change recommended setpoint tolerances, export reports.

Maintenance Engineer — view PdM alerts, schedule maintenance tasks, download vibration logs.

Plant Manager — view KPIs, confirm major parameter changes, approve maintenance budgets.

NMDC Admin / Auditor — view audit logs, system health; higher-level governance access (read-only to raw data, download permitted).

Quickstart (dev)

• to be updated

1. Install Docker & Docker Compose
2. docker-compose up --build
3. Open http://localhost:3000 (frontend)
4. Run python simulator/iot_simulator.py to publish telemetry (optional)

Components

• frontend: Next.js dashboard
• ingestion-service: MQTT/REST ingestion into Influx
• api-service: main API & auth
• model-service: model predictions

Contributing

• Follow coding standards; run tests before PR.
• See docs/ for architecture & SIH submission.

Contact

Team Synapsee — arshtiwari12345@gmail.com

Folder Structure

comminusense/
├── comminusense-next/              # [EXISTING] Frontend (Next.js)
│   └── [... your existing frontend structure ...]
│
├── backend/                        # [NEW] Express.js Core Backend
│   ├── src/
│   │   ├── app.js                 # Express app setup
│   │   ├── server.js              # Server entry point
│   │   ├── config/
│   │   │   ├── env.js             # Environment variables
│   │   │   ├── db.js              # PostgreSQL connection (Sequelize)
│   │   │   ├── mqtt.js            # MQTT broker config
│   │   │   ├── logger.js          # Winston logger
│   │   │   └── rbac.js            # Role definitions & permissions
│   │   │
│   │   ├── routes/
│   │   │   ├── index.js           # Route aggregator
│   │   │   ├── auth.routes.js     # /api/auth/*
│   │   │   ├── telemetry.routes.js # /api/telemetry/*
│   │   │   ├── metrics.routes.js  # /api/metrics/*
│   │   │   ├── maintenance.routes.js # /api/maintenance/*
│   │   │   ├── simulate.routes.js # /api/simulate/*
│   │   │   ├── user.routes.js     # /api/users/*
│   │   │   └── report.routes.js   # /api/reports/*
│   │   │
│   │   ├── controllers/
│   │   │   ├── auth.controller.js
│   │   │   ├── telemetry.controller.js
│   │   │   ├── metrics.controller.js
│   │   │   ├── maintenance.controller.js
│   │   │   ├── simulate.controller.js
│   │   │   ├── user.controller.js
│   │   │   └── report.controller.js
│   │   │
│   │   ├── services/
│   │   │   ├── auth.service.js     # JWT, login, refresh
│   │   │   ├── telemetry.service.js # Time-series queries
│   │   │   ├── metrics.service.js  # KPI calculations
│   │   │   ├── maintenance.service.js # Ticket CRUD
│   │   │   ├── simulation.service.js # Forward to FastAPI
│   │   │   ├── ml.service.js       # HTTP client to FastAPI
│   │   │   ├── user.service.js     # User CRUD
│   │   │   └── report.service.js   # CSV/PDF export
│   │   │
│   │   ├── models/                 # Sequelize models (PostgreSQL)
│   │   │   ├── index.js            # Model loader
│   │   │   ├── User.js
│   │   │   ├── Role.js
│   │   │   ├── Permission.js
│   │   │   ├── RolePermission.js
│   │   │   ├── Plant.js
│   │   │   ├── Machine.js
│   │   │   ├── MaintenanceTicket.js
│   │   │   └── AuditLog.js
│   │   │
│   │   ├── middlewares/
│   │   │   ├── auth.middleware.js  # Verify JWT
│   │   │   ├── rbac.middleware.js  # Check permissions
│   │   │   ├── error.middleware.js # Global error handler
│   │   │   └── validator.middleware.js # Request validation
│   │   │
│   │   ├── utils/
│   │   │   ├── apiResponse.js      # Standardized responses
│   │   │   ├── jwt.js              # Token generation/verification
│   │   │   ├── mqttHandler.js      # MQTT subscriber
│   │   │   ├── httpClient.js       # Axios wrapper
│   │   │   └── csvExporter.js      # CSV generation
│   │   │
│   │   ├── jobs/                   # Background tasks (node-cron)
│   │   │   ├── maintenanceCheck.job.js # Check PdM alerts
│   │   │   └── analyticsAggregation.job.js
│   │   │
│   │   └── sockets/
│   │       └── telemetry.socket.js # WebSocket for live data
│   │
│   ├── scripts/
│   │   ├── seedRoles.js            # Initialize roles & permissions
│   │   └── seedMachines.js         # Sample plant/machine data
│   │
│   ├── tests/                      # Jest tests
│   │   ├── auth.test.js
│   │   └── telemetry.test.js
│   │
│   ├── .env.example
│   ├── .gitignore
│   ├── package.json
│   ├── Dockerfile
│   └── README.md
│
├── fastapi_backend/                # [EXISTING] Python ML/Simulation
│   ├── app.py                      # FastAPI main
│   ├── maintenance_model/
│   │   ├── router.py
│   │   └── maintenance_model.pkl
│   ├── energy_model/               # [NEW] Energy optimizer
│   │   ├── router.py
│   │   └── energy_model.pkl
│   ├── simulator/                  # [NEW] Digital twin
│   │   ├── router.py
│   │   └── surrogate_model.pkl
│   ├── requirements.txt
│   └── Dockerfile
│
├── iot_simulator/                  # [NEW] MQTT simulator
│   ├── simulator.py
│   ├── config.json
│   └── requirements.txt
│
├── docker-compose.yml              # Full stack orchestration
├── .env.shared                     # Shared environment vars
└── README.md                       # Main project README