🏭 FacCheck AI

An AI-driven predictive maintenance platform that monitors industrial machine health, analyzes high-frequency telemetry, and visualizes real-time digital twins.

---

📑 Table of Contents

• Overview
• Why FacCheck AI?
• Features
• System Design & Architecture
• Tech Stack
• Project Structure
• Installation
• Environment Variables
• Run Project
• API & WebSockets
• AI Workflow & Features
• Performance
• Future Vision & Roadmap
• Contributing
• License
• Developer

---

🔭 Overview

FacCheck AI is a full-stack, AI-driven predictive maintenance platform engineered to monitor, analyze, and visualize industrial machine health. By combining a realistic simulation of high-frequency sensor telemetry with machine learning, the platform accurately predicts failure probabilities before they cause downtime.

The system features a real-time WebSocket architecture that feeds live telemetry directly into a sleek, futuristic UI dashboard complete with interactive 3D digital twins.

---

🏆 Why FacCheck AI?

Unplanned downtime in manufacturing and industrial sectors costs millions of dollars annually. Traditional maintenance is purely reactive (fixing things after they break) or rigidly preventative (replacing parts on a strict schedule, regardless of actual wear).

• Proactive AI Maintenance: Transition to predictive maintenance—fixing machines exactly when they are about to fail using a Scikit-Learn Random Forest model.
• Real-Time Digital Twins: Instead of flat graphs, monitor actual 3D WebGL models that change state and materials dynamically based on live heat and vibration data.
• Premium UX: Built to feel like a high-end sci-fi command center with smooth Framer Motion animations, glassmorphism UI, and customized SVG telemetry charts.

---

✨ Features

Feature	Description	Status	Examples
Real-Time Telemetry	WebSocket-powered architecture delivering sub-second sensor updates	✅	Emits live machine_telemetry
AI Failure Prediction	Integrated ML model assigning risk levels based on 10D vectors	✅	Detects anomalies on the fly
Interactive Digital Twins	React Three Fiber 3D models representing live machine health	✅	Colors shift from green to red
Dynamic Fleet Filtering	Instantly filter global fleets by type and risk level	✅	Isolate "High Risk Machines"
Responsive UI	Flawless glassmorphism experience across all breakpoints	✅	Adapts to mobile/desktop
Live Analytical Charts	Custom Recharts and SVG sparklines updating dynamically	✅	OEE & Yield metrics
Event Logging	Automated notification system tracking critical machine events	✅	History of warnings/errors
Theme Customization	Dark mode UI with system preference syncing	✅	Persistent via localStorage

---

📊 System Design & Architecture

 ┌────────────────────────────────────────────────────────┐
 │                      REACT UI                          │
 │  (Next.js, Tailwind, Zustand, Recharts, Three.js)      │
 └──────────────────────────┬─────────────────────────────┘
                            │ (WebSockets & REST)
 ┌──────────────────────────▼─────────────────────────────┐
 │                     API LAYER                          │
 │      (Socket.io Multiplexing & Request Handlers)       │
 └──────────────────────────┬─────────────────────────────┘
                            │
 ┌──────────────────────────▼─────────────────────────────┐
 │                   EXPRESS SERVER                       │
 │      (Node.js, Simulation Engine, Socket Manager)      │
 └─────────────┬───────────────────────────┬──────────────┘
               │                           │
 ┌─────────────▼──────────────┐  ┌─────────▼──────────────┐
 │         DATASET            │  │        AI ENGINE       │
 │  (CSV Telemetry Stream)    │  │ (Random Forest ML)     │
 └────────────────────────────┘  └────────────────────────┘

---

💻 Tech Stack

Frontend

• Framework: React 19 / Next.js (App Router)
• Styling: Tailwind CSS (Glassmorphism & Cyber-Industrial UI)
• Animations: Framer Motion
• 3D Rendering: React Three Fiber / Drei
• Data Visualization: Recharts & Custom SVGs
• State Management: Zustand
• Networking: Socket.io Client

Backend

• Runtime: Node.js
• Framework: Express.js
• Real-Time: Socket.io
• Data Loading: Fast CSV Loader

Machine Learning

• Model: Random Forest Classifier (Scikit-learn)
• API Engine: Python / FastAPI
• Data Processing: Pandas / NumPy

---

📁 Project Structure

fac-Check/
├── backend/
│   ├── src/
│   │   ├── services/       # CSV Loader, AI inference, Telemetry simulation
│   │   ├── websocket/      # Socket.io room management
│   │   └── index.js        # Express Server entry point
│   └── package.json
│
└── frontend/
    ├── src/
    │   ├── app/            # Next.js routes (Dashboard, Analytics, Alerts)
    │   ├── components/     # UI, 3D Models, Charts, Metric Cards
    │   ├── lib/            # Utility functions
    │   ├── services/       # Socket.io service layer
    │   ├── store/          # Zustand state management
    │   └── styles/         # Global CSS
    ├── tailwind.config.ts  
    └── package.json

---

🚀 Installation

Follow these steps to get the project running locally.

1. Clone the repository

git clone https://github.com/MaybeSomeone-arc18/fac-Check.ai.git
cd fac-Check.ai

2. Install Backend Dependencies

cd backend
npm install

3. Install Frontend Dependencies

cd ../frontend
npm install

---

🔐 Environment Variables

Create .env files in both backend and frontend directories:

Backend (backend/.env):

Variable	Description	Example
PORT	The port for the Express server	3001
CSV_PATH	Path to telemetry dataset	./predictive_maintenance_dataset.csv

Frontend (frontend/.env.local):

Variable	Description	Example
NEXT_PUBLIC_SOCKET_URL	WebSocket server URL	http://localhost:3001
NEXT_PUBLIC_API_URL	REST API server URL	http://localhost:3001/api

---

⚡ Run Project

You will need two terminal windows to run both the frontend and backend simultaneously.

Development

Terminal 1 (Backend):

cd backend
npm run dev

Terminal 2 (Frontend):

cd frontend
npm run dev

---

🌐 API & WebSockets

While primary data flows via WebSockets, the backend also exposes standard REST API endpoints for initial configurations.

WebSocket Events

• subscribe_machine / unsubscribe_machine: Manage active telemetry listeners to conserve bandwidth.
• machine_telemetry: Emitted ~10 times a second containing live sensor payloads and AI risk scores.

REST Endpoints

• GET /api/machines - Retrieve registered machine fleet
• GET /api/alerts - Fetch recent anomaly logs
• GET /api/analytics/history - Fetch historical OEE and Yield metrics

---

🧠 AI Workflow & Features

FacCheck AI seamlessly integrates a Scikit-learn Random Forest Model to elevate operations from passive tracking to proactive management.

• Risk Classification: Evaluates 10-dimensional sensor feature vectors to predict failure probabilities.
• Categorization: Classifies incoming live streams into statuses: NOMINAL, WARNING, and CRITICAL.
• Automated Alerts: When anomaly thresholds are breached, the AI triggers immediate visual alerts on the dashboard and event logs.
• Digital Twin Sync: Risk levels are actively bound to the React Three Fiber materials, turning a healthy blue model into a glowing red model dynamically.

---

⚡ Performance

• Zustand Granular Subscriptions: Telemetry store uses advanced selector mechanisms so only individual Machine Cards re-render upon WebSocket pings, rather than the entire dashboard.
• Socket Multiplexing: The application avoids heavy REST polling. As you navigate between global dashboards and machine detail views, the frontend dynamically joins and leaves Socket.io rooms, optimizing network bandwidth.
• Decoupled 3D Rendering: The 3D Digital Twin canvas leverages memo and strictly segregated state to prevent React from re-rendering the heavy WebGL context when overlay UI updates occur.
• Immutable Rolling Buffers: Sanitizes corrupt payloads (Number.isFinite) and precisely synchronizes dynamic SVG sparklines with updating numeric DOM elements.

---

📈 Future Vision & Roadmap

• Hardware Integration API: Allow real PLCs / IoT gateways to replace the CSV simulator.
• Advanced AI Models: Expand the ML pipeline with LSTM neural networks for advanced time-series forecasting.
• VR/AR Digital Twin: Immersive diagnostic capabilities utilizing WebXR.
• Real-time Collaboration: Multiple operators interacting with the same digital twin.
• Email & Slack Notifications: Push notifications for critical machine alerts.

---

🤝 Contributing

Contributions make the open-source community an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (`git commit -m 'Add some Amazin