Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/BhaveshBytess/PREDICTIVE-MAINTENANCE/llms.txt

Use this file to discover all available pages before exploring further.

Set up the Predictive Maintenance System manually for local development without Docker. This approach gives you direct access to source code and dependencies for debugging and feature development.

​
Prerequisites

Ensure you have installed:
  • Python 3.11+ (Backend)
  • Node.js 18+ and npm (Frontend)
  • Git
  • InfluxDB Cloud account (or local InfluxDB 2.x)

​
Backend Setup

The backend is built with FastAPI and requires a Python virtual environment.
1

Clone the repository

git clone https://github.com/BhaveshBytess/PREDICTIVE-MAINTENANCE.git
cd PREDICTIVE-MAINTENANCE
2

Navigate to backend directory

cd backend
3

Create virtual environment

Create an isolated Python environment:
python -m venv venv
.\venv\Scripts\activate
Your terminal prompt should now show (venv) indicating the virtual environment is active.
4

Install dependencies

Install all required Python packages:
pip install -r requirements.txt
This installs:
  • FastAPI: Web framework
  • Uvicorn: ASGI server
  • InfluxDB Client: Time-series database connector
  • Scikit-learn: Machine learning (Isolation Forest)
  • Pandas & NumPy: Data processing
  • ReportLab & OpenPyXL: PDF/Excel report generation
  • Pydantic: Data validation
5

Configure environment variables

Create .env file from the example:
cp .env.example .env
Edit backend/.env with your InfluxDB credentials:
# Environment
ENVIRONMENT=local

# API Configuration
API_V1_STR=/api/v1
PROJECT_NAME=Predictive Maintenance

# InfluxDB Configuration
INFLUX_URL=https://us-east-1-1.aws.cloud2.influxdata.com
INFLUX_TOKEN=your-influxdb-token-here
INFLUX_ORG=your-organization-id
INFLUX_BUCKET=sensor_data
Never commit .env files to version control. They contain sensitive credentials.
6

Start the development server

Run the FastAPI application with hot-reload:
uvicorn backend.api.main:app --reload
The server will start on http://localhost:8000
The --reload flag enables auto-restart when code changes are detected. Remove it for production.
7

Verify installation

Test the backend in a new terminal:
curl http://localhost:8000/health
Expected response:
{
  "status": "healthy",
  "db_connected": true
}
Or visit the interactive API docs at:

​
Frontend Setup

The frontend is built with React 18, Vite, and Recharts for real-time visualization.
1

Navigate to frontend directory

Open a new terminal (keep backend running) and navigate:
cd frontend
2

Install dependencies

Install all Node.js packages:
npm install
This installs:
  • React 18: UI framework
  • Vite: Build tool and dev server
  • Recharts: Real-time charting library
  • Axios: HTTP client
  • React Router: Navigation (if used)
3

Configure environment (optional)

Create .env.local if you need custom API URL:
cp .env.example .env.local
Edit frontend/.env.local:
VITE_API_URL=http://localhost:8000
By default, the frontend assumes the backend is at http://localhost:8000. Only create this file if using a different URL.
4

Start the development server

Launch the Vite dev server with hot module replacement:
npm run dev
The frontend will start on http://localhost:5173
5

Access the dashboard

Open your browser and navigate to:http://localhost:5173You should see the Predictive Maintenance dashboard with:
  • Real-time sensor metrics
  • Health score visualization
  • Anomaly detection charts
  • System control panel

​
Development Workflow

​
Running Both Services

For active development, run both backend and frontend concurrently:
  1. Terminal 1 (Backend): 
    cd backend
source venv/bin/activate  # or .\venv\Scripts\activate on Windows
uvicorn backend.api.main:app --reload
  2. Terminal 2 (Frontend): 
    cd frontend
npm run dev

​
Hot Reload Behavior

  • Backend: Uvicorn automatically restarts when Python files change
  • Frontend: Vite hot-reloads React components without full page refresh

​
Testing the System

curl http://localhost:8000/health

​
Running Tests

The project includes 182 unit tests covering all major components.
1

Install test dependencies

Ensure pytest is installed (included in requirements.txt):
pip install pytest pytest-cov
2

Run all tests

From the project root:
pytest tests/ -v
3

Run specific test modules

pytest tests/test_features.py -v
4

Generate coverage report

pytest tests/ --cov=backend --cov-report=html
View the report by opening htmlcov/index.html in your browser.

​
Data Generation for Testing

Use the built-in data generator to simulate sensor readings: 
python scripts/generate_data.py \
  --asset-id Motor-01 \
  --mode healthy \
  --duration 60 \
  --frequency 100

​
Troubleshooting

​
Backend Issues

​
ModuleNotFoundError: No module named ‘backend’

Solution: Ensure PYTHONPATH includes the project root: 
export PYTHONPATH="${PYTHONPATH}:/path/to/PREDICTIVE-MAINTENANCE"
Or run from the project root: 
cd PREDICTIVE-MAINTENANCE
uvicorn backend.api.main:app --reload

​
InfluxDB Connection Failed

Solution: Verify credentials in backend/.env: 
grep INFLUX backend/.env
Test connection: 
from backend.database import get_database_client
client = get_database_client()
print(client.health())

​
Port 8000 Already in Use

Solution: Kill the existing process: 
lsof -ti:8000 | xargs kill -9
Or use a different port: 
uvicorn backend.api.main:app --reload --port 8001

​
Frontend Issues

​
API Connection Error

Problem: Network Error in browser console Solution: Verify backend is running: 
curl http://localhost:8000/health
Check CORS configuration in backend/api/main.py: 
CORS_ORIGINS = [
    "http://localhost:5173",
    "http://localhost:3000",
]

​
npm install Fails

Problem: Package installation errors Solution: Clear cache and reinstall: 
rm -rf node_modules package-lock.json
npm cache clean --force
npm install

​
Port 5173 Already in Use

Solution: Vite will automatically try the next available port (5174, 5175, etc.). Or specify a port: 
npm run dev -- --port 3000

​
Windows-Specific Issues

​
Python Virtual Environment Won’t Activate

Problem: PowerShell execution policy error Solution: Allow script execution: 
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Then activate: 
.\venv\Scripts\activate

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us