🛠️ GearGuard – Maintenance & Equipment Management System

GearGuard is a comprehensive web-based maintenance and equipment management system built using Django 5.2 and PostgreSQL. It helps organizations efficiently track equipment, manage maintenance requests, assign teams, and monitor maintenance status through sophisticated role-based access control.

This project is designed to be scalable, secure, and production-ready, making it suitable for enterprise use cases such as factories, workshops, IT infrastructure, and industrial facilities.

---

✨ Key Features

👥 User & Role Management

• Four-tier role-based access control:
  • Admin: Full system access, user management, team management, equipment management, reports
  • Manager: Dashboard access, maintenance request management, preventive maintenance scheduling, team oversight, technician reports
  • Technician: Task assignment, work tracking, time logging, completion reports
  • User: Create maintenance requests, view own requests, equipment status
• User profile management with roles and avatars
• User registration system with admin approval workflow
• Active/inactive user status handling

🏭 Equipment Management

• Comprehensive equipment tracking with:
  • Equipment details (name, serial number, category, department)
  • Location and specifications
  • Purchase date and warranty expiry tracking
  • Preventive maintenance interval configuration
  • Equipment-to-team assignment
  • Default technician assignment
  • Scrap status and reason tracking
• Equipment filtering and search capabilities
• Equipment history and maintenance tracking

🛠️ Maintenance Requests

• Two request types:
  • Corrective: Breakdown/repair requests
  • Preventive: Scheduled maintenance tasks
• Request lifecycle tracking:
  • New → In Progress → Repaired/Scrap
• Priority-based handling (Low, Medium, High, Critical)
• Request assignment to teams and technicians
• Time tracking (estimated and actual duration)
• Technician notes and resolution summaries
• Overdue request detection
• Scheduled date and due date management

👨‍🔧 Maintenance Teams

• Create and manage maintenance teams
• Assign technicians to multiple teams
• Team-based request routing
• Team performance tracking
• Active/inactive team status

📊 Reporting & Analytics

• Admin dashboard with system-wide statistics
• Manager dashboard with team performance metrics
• Technician reports with completed task history
• Equipment reports by category and team
• Request analytics by status and type
• Manager hours tracking
• Custom 404 error page

🎨 Modern UI/UX

• Odoo-inspired modern interface design
• Responsive design for all devices
• Clean, professional color scheme
• Smooth animations and transitions
• Intuitive navigation with sidebar and top navbar
• Role-based dashboard customization

---

🧱 Tech Stack

Layer	Technology
Backend Framework	Django 5.2.9 (Python)
Database	PostgreSQL
ORM	Django ORM
Authentication	Django Auth System with custom role-based access
Frontend	Bootstrap 5.3, Bootstrap Icons
Templates	Django Templates
Deployment	WSGI / ASGI
Font	Inter (Google Fonts)

---

📁 Project Structure

GearGuard/
│
├── gearguard/                 # Main Django project directory
│   ├── __init__.py
│   ├── settings.py           # Django settings configuration
│   ├── urls.py               # Root URL configuration
│   ├── asgi.py               # ASGI configuration
│   ├── wsgi.py               # WSGI configuration
│
├── maintenance/              # Main application
│   ├── models.py             # Database models
│   ├── views.py              # View functions and class-based views
│   ├── urls.py               # Application URL patterns
│   ├── forms.py              # Django forms
│   ├── admin.py              # Django admin configuration
│   ├── signals.py            # Django signals
│   ├── mixins.py             # Permission mixins
│   ├── utils.py              # Utility functions
│   ├── decorators.py         # Custom decorators
│   ├── error_handlers.py     # Custom error handlers (404, 500, etc.)
│   ├── management/
│   │   └── commands/         # Django management commands
│   │       ├── add_sample_data.py
│   │       ├── create_all_users.py
│   │       └── create_manager.py
│   ├── migrations/           # Database migrations
│   └── templatetags/         # Custom template tags
│
├── templates/                # HTML templates
│   ├── 404.html              # Custom 404 error page
│   └── maintenance/          # Application templates
│       ├── base.html         # Base template
│       ├── login.html        # Login page
│       ├── admin_dashboard.html
│       ├── manager_dashboard.html
│       ├── technician_dashboard.html
│       └── ...               # Other templates
│
├── gearguard-postgres-schema.sql  # PostgreSQL schema (optional)
├── database.py               # Database utility script
├── populate_database.py      # Script to populate database with dummy data
├── manage.py                # Django management script
├── requirements.txt         # Python dependencies
└── README.md               # This file

---

🗄️ Database Design

Core Models

1. UserProfile (extends Django User)

   • Role assignment (Admin, Manager, Technician, User)
   • Avatar URL
   • Active status

2. MaintenanceTeam

   • Team name and description
   • Active status
   • Timestamps

3. TeamMember (Junction Table)

   • Many-to-many relationship between Teams and Users
   • Role in team
   • Join date

4. Equipment

   • Equipment details (name, serial number, category)
   • Department and location
   • Maintenance team assignment
   • Default technician assignment
   • Purchase and warranty dates
   • Preventive maintenance interval
   • Scrap status

5. MaintenanceRequest

   • Request type (Corrective/Preventive)
   • Stage (New, In Progress, Repaired, Scrap)
   • Priority (Low, Medium, High, Critical)
   • Equipment, team, and technician assignment
   • Time tracking (start, end, duration)
   • Notes and resolution summary
   • Overdue detection

6. UserRegistration

   • Pending user registrations
   • Approval workflow
   • Role requests

Relationships

• Equipment → MaintenanceTeam (Many-to-One)
• Equipment → User (assigned_to_user, default_technician)
• MaintenanceRequest → Equipment (Many-to-One)
• MaintenanceRequest → MaintenanceTeam (Many-to-One)
• MaintenanceRequest → User (assigned_technician, created_by)
• TeamMember → MaintenanceTeam & User (Many-to-Many)

---

⚙️ Setup & Installation

Prerequisites

• Python 3.10 or higher
• PostgreSQL 12 or higher
• pip (Python package manager)

1️⃣ Clone the Repository

git clone https://github.com/your-username/GearGuard.git
cd GearGuard

2️⃣ Create Virtual Environment

# Windows
python -m venv venv
venv\Scripts\activate

# Linux/Mac
python3 -m venv venv
source venv/bin/activate

3️⃣ Install Dependencies

pip install -r requirements.txt

4️⃣ Configure PostgreSQL Database

1. Create PostgreSQL database:

CREATE DATABASE gearguard;

2. Update database credentials in gearguard/settings.py:

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "NAME": "gearguard",
        "USER": "postgres",
        "PASSWORD": "your_password",
        "HOST": "localhost",
        "PORT": "5432",  # Default PostgreSQL port
    }
}

5️⃣ Apply Database Migrations

python manage.py makemigrations
python manage.py migrate

6️⃣ Create Superuser (Admin)

python manage.py createsuperuser

Follow the prompts to create an admin account.

7️⃣ (Optional) Populate Database with Sample Data

You have two options to populate the database:

Option 1: Using the standalone Python script

python populate_database.py

(Located at project root: populate_database.py)

Option 2: Using Django management command

python manage.py add_sample_data

(Located at: maintenance/management/commands/add_sample_data.py)

8️⃣ Collect Static Files

python manage.py collectstatic

9️⃣ Run the Development Server

python manage.py runserver

The application will be available at http://127.0.0.1:8000/

---

🔐 Roles & Permissions

Role	Dashboard Access	Equipment Management	Request Management	Team Management	User Management	Reports
Admin	✅ Admin Dashboard	✅ Full Access	✅ Full Access	✅ Full Access	✅ Full Access	✅ All Reports
Manager	✅ Manager Dashboard	✅ View Only	✅ Full Access	✅ View Only	❌	✅ Manager Reports
Technician	✅ Technician Dashboard	✅ View Only	✅ Assigned Tasks Only	❌	❌	✅ Own Reports
User	✅ User Dashboard	✅ View Only	✅ Create/View Own	❌	❌	❌

---

🚀 Key Features Explained

Dashboard System

• Admin Dashboard: System-wide statistics, equipment overview, team management, user registrations
• Manager Dashboard: Team performance, request overview, preventive maintenance calendar, technician reports
• Technician Dashboard: Assigned tasks, team requests, work history, time tracking
• User Dashboard: Personal requests, equipment status, request creation

Request Management

• Kanban Board: Visual board for request status management
• Calendar View: Preventive maintenance scheduling
• Request List: Filterable list with search capabilities
• Request Detail: Comprehensive request information and updates

Preventive Maintenance

• Automatic scheduling based on equipment maintenance intervals
• Calendar integration
• Recurring maintenance tracking
• Next maintenance date calculation

Time Tracking

• Start/end task functionality for technicians
• Automatic duration calculation
• Estimated vs actual duration comparison
• Hours reporting for managers

---

📝 Usage Examples

Creating a Maintenance Request (User)

1. Login as a User
2. Navigate to "Create Request"
3. Select equipment
4. Fill in subject, description, and priority
5. Submit request

Assigning a Request (Manager)

1. Login as Manager
2. Go to "Maintenance Requests"
3. Select a request
4. Assign to technician and team
5. Set priority and scheduled date

Completing a Task (Technician)

1. Login as Technician
2. View assigned tasks
3. Click "Start Task" when beginning work
4. Update notes and status
5. Click "End Task" when finished
6. Add resolution summary

---

🛠️ Management Commands

Django management commands are located in maintenance/management/commands/ directory.

Add Sample Data

python manage.py add_sample_data

Creates sample teams, equipment, and maintenance requests.

• File location: maintenance/management/commands/add_sample_data.py

Create All Users

python manage.py create_all_users

Creates users for all roles with default passwords.

• File location: maintenance/management/commands/create_all_users.py

Create Manager

python manage.py create_manager

Creates a manager user.

• File location: maintenance/management/commands/create_manager.py

Alternative: Standalone Population Script

You can also use the standalone script at the project root:

python populate_database.py

• File location: populate_database.py (project root)

---

🔧 Configuration

Settings File (gearguard/settings.py)

Important Settings:

• DEBUG: Set to False in production
• ALLOWED_HOSTS: Configure for production deployment
• SECRET_KEY: Generate a new secret key for production
• DATABASES: Configure PostgreSQL connection
• STATIC_ROOT: Directory for collected static files

Environment Variables (Recommended for Production)

Create a .env file:

SECRET_KEY=your-secret-key-here
DEBUG=False
DB_NAME=gearguard
DB_USER=postgres
DB_PASSWORD=your-password
DB_HOST=localhost
DB_PORT=5432

---

🧪 Testing

Run Django tests:

python manage.py test

---

📦 Deployment

Production Checklist

• Set DEBUG = False
• Configure ALLOWED_HOSTS
• Generate new SECRET_KEY
• Set up PostgreSQL database
• Configure static files serving
• Set up SSL/HTTPS
• Configure email settings (for notifications)
• Set up backup strategy
• Configure logging
• Set up monitoring

Static Files

python manage.py collectstatic

Database Backup

pg_dump -U postgres gearguard > backup.sql

---

🐛 Troubleshooting

Database Connection Issues

• Verify PostgreSQL is running
• Check database credentials in settings.py
• Ensure database exists
• Check PostgreSQL port (default: 5432)

Migration Issues

python manage.py makemigrations
python manage.py migrate --run-syncdb

Static Files Not Loading

python manage.py collectstatic

Ensure STATIC_ROOT is configured correctly.

---

📈 Future Enhancements

• Email notifications for request updates
• REST API for mobile applications
• Advanced analytics and reporting
• Equipment QR code scanning
• Mobile-responsive improvements
• Multi-language support
• Document attachment support
• Automated preventive maintenance scheduling
• Equipment maintenance history timeline
• Cost tracking and budgeting

---

🏆 Use Cases

• Manufacturing Plants: Track production equipment maintenance
• Facility Management: Manage building systems and infrastructure
• IT Infrastructure: Monitor server and network equipment
• Industrial Maintenance: Schedule and track industrial machinery
• Asset Tracking: Comprehensive equipment lifecycle management
• Healthcare Facilities: Medical equipment maintenance tracking
• Educational Institutions: Campus equipment management

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

📄 License

This project is licensed for educational use.

---

👨‍💻 Author

GearGuard Development Team
Built with ❤️ using Django & PostgreSQL

---

📞 Support

For issues, questions, or contributions, please open an issue on the GitHub repository.

---

Version: 1.0.0
Last Updated: 2025
Status: Production Ready