A modern, multi-tenant web application designed for comprehensive industrial and commercial equipment maintenance, fault tracking, and preventive maintenance scheduling.
Live demo: https://fixfleet-app.onrender.com/ - first load may take ~30 seconds (free hosting).
| Operations & Maintenance Dashboard | Equipment Fleet Management |
|---|---|
![]() |
![]() |
- Multi-Tenant Architecture: Strict organizational data isolation enforced per tenant (
companyId) across all database queries, operations, and file storage. - Equipment & Tool Management: Track equipment catalog, upload technical manuals (PDFs), manage machine status, and attach maintenance routines.
- Fault Tracking & Reporting: Log faults with multi-photo uploads, status workflows (Open, In Progress, Closed, Reopened), severity/priority levels, and mechanic assignments.
- Preventive Maintenance Schedules: Set recurring maintenance plans with actionable task checklists, completion tracking, and historical logs.
- Role-Based Access Control (RBAC):
admin: Organization setup, user management, and equipment catalog configuration.mechanic: Equipment maintenance, schedule execution, checklist management, and fault resolution.operator: Equipment status view, fault reporting with photo uploads, and task visibility.
- Notifications & Web Push: Mechanics and admins are alerted the moment a fault is reported, and admins can broadcast announcements to their organization (optionally targeting a single role). Every notification lands in an in-app feed with an unread badge, and is also delivered as a PWA push notification to each device the user has opted in on. Push is optional -- without VAPID keys configured, the in-app feed works unchanged.
- Progressive Web App (PWA): Built with
vite-plugin-pwafor offline capability, pull-to-refresh on every screen, and mobile-friendly field operations. - Robust Security: Rate-limited authentication, HTTP-only JWT cookies, Helmet HTTP headers, strict CORS origin controls, tenant-scoped media delivery, and recursive NoSQL-operator sanitization on every request body/query/params.
- Framework & Tooling: React 19, Vite, Vite PWA
- UI & Components: Material-UI (MUI v9), Emotion
- State & Routing: React Context API, React Router v7
- Data Visualization: Recharts
- HTTP Client: Axios with global auth interceptors and silent token refresh
- Testing & Quality: Jest, React Testing Library, ESLint 9
- Runtime & Framework: Node.js, Express 5
- Database: MongoDB with Mongoose 8
- Authentication: JWT (
jsonwebtoken) delivered via secure, HTTP-only cookies (cookie-parser) with bcrypt password hashing - File Uploads: Multer (in-memory parsing) storing into MongoDB GridFS, with tenant-validated media streaming on download
- Security & Rate Limiting: Helmet, CORS, express-rate-limit
- Testing: Jest, Supertest, mongodb-memory-server
FixFleet/
├── backend/ # Express REST API
│ ├── config/ # Database and server configuration
│ ├── constants/ # Shared enums/config (roles, rate limits, fault/schedule status, auth)
│ ├── controllers/ # Thin HTTP layer: parse request, call service, shape response
│ ├── middleware/ # Auth, validation, upload, sanitize, and centralized error middleware
│ ├── models/ # Mongoose data schemas (Tenant-scoped)
│ ├── routes/ # Express API route declarations
│ ├── scripts/ # One-off operational scripts (e.g. GridFS upload migration)
│ ├── seeders/ # Database seeding scripts
│ ├── services/ # Business logic and data access, called by controllers
│ ├── utils/ # Shared helpers (logger, GridFS media storage, error helpers)
│ └── __tests__/ # Backend unit and integration tests
├── frontend/ # React Single Page Application (PWA)
│ ├── src/
│ │ ├── components/ # Feature-specific components (Fault, Tool, User, etc.)
│ │ ├── constants/ # Shared literals (roles, fault status, route paths)
│ │ ├── contexts/ # React contexts (Auth, Equipment, Fault, Notification, Theme, Tool)
│ │ ├── hooks/ # Shared hooks (e.g. useForm)
│ │ ├── pages/ # View pages and route layouts
│ │ ├── services/ # Axios API clients and endpoint wrappers
│ │ └── *.test.jsx / *.test.js # Co-located component/hook/service tests
│ └── __tests__/ # Additional component tests (login/legal flows)
├── docs/ # Detailed project documentation
│ ├── API.md # Full REST API endpoint specification
│ ├── CONTRIBUTING.md # Development guide, testing, and PR checklist
│ ├── ENV.md # Environment variable reference
│ └── RUNBOOK.md # Operations, deployment, health checks, & runbook
├── LICENSE # MIT License
└── README.md # Project overview and quickstart guide
- Node.js: v18.0.0+ or v20.0.0+ LTS
- npm: v9.0.0+
- MongoDB: Local instance running on
localhost:27017or a MongoDB Atlas URI
git clone https://github.com/yaronserlin/FixFleet.git
cd FixFleet# Install backend dependencies
cd backend
npm install
# Install frontend dependencies
cd ../frontend
npm installCopy template environment files:
# In backend directory
cp .env.example .env
# In frontend directory
cp .env.example .envSee docs/ENV.md for detailed descriptions of all available environment configuration options.
Populate your local MongoDB instance with initial test users, sample equipment and maintenance schedules:
cd backend
npm run seedOpen two terminal tabs:
Terminal 1 (Backend API on port 5001):
cd backend
npm run devTerminal 2 (Frontend on port 5173):
cd frontend
npm run devNavigate to http://localhost:5173 in your browser.
| Command | Description |
|---|---|
npm run dev |
Start backend with nodemon hot-reloading on port 5001 |
npm start |
Run backend in production mode |
npm run build |
Validate syntax with node --check app.js |
npm run seed |
Seed database with initial sample data |
npm test |
Run backend tests with Jest and in-memory MongoDB |
| Command | Description |
|---|---|
npm run dev |
Start Vite dev server on port 5173 with HMR |
npm run build |
Build production assets to dist/ |
npm run preview |
Locally preview production build |
npm run lint |
Run ESLint static analysis |
npm test |
Run frontend unit & component tests |
Comprehensive project documentation is maintained in the docs/ directory:
- 🧭 User Guide: Illustrated, step-by-step guide for operators, mechanics, and admins. In the app at
/guide; content source: frontend/public/user-guide/index.html. - 📖 REST API Specification: Full endpoint reference, authentication patterns, request parameters, and response structures.
- ⚙️ Environment Variables: Detailed reference table for backend and frontend environment configuration.
- 🛠️ Contributing Guide: Development workflow, environment setup, testing procedures, code style rules, and PR checklist.
- 🚀 Operations Runbook: Cloud deployment instructions, health check monitoring, common issues and troubleshooting, and incident response.
This project is licensed under the MIT License - see the LICENSE file for details.

