A comprehensive, enterprise-grade cleaning management system with time-based attendance tracking, real-time task management, and role-based access control.
Features • Quick Start • Documentation • Architecture • Contributing
- Overview
- Features
- Tech Stack
- System Architecture
- Quick Start
- Installation
- Configuration
- Usage
- API Documentation
- Testing
- Deployment
- Contributing
- License
- Support
The Cleaning Management System is a full-stack web application designed to streamline cleaning operations for organizations of any size. Built with modern technologies and best practices, it provides real-time task management, time-based attendance tracking, and comprehensive reporting capabilities.
- ⏰ Time-Based Attendance: Simple and efficient check-in/check-out tracking
- ⚡ Real-Time Updates: Track task progress instantly across all devices
- 🔐 Secure Authentication: JWT-based authentication with role-based access control
- 📊 Comprehensive Reporting: Generate detailed performance and attendance reports
- 📱 Mobile-Friendly: Responsive design works seamlessly on all devices
- 🔄 RESTful API: Well-documented API for easy integration
- 👥 Staff Management: Add, edit, and manage staff profiles with role assignments
- 📋 Task Assignment: Create and assign cleaning tasks with detailed specifications
- 📊 Dashboard Analytics: View real-time statistics and performance metrics
- 📢 Announcements: Broadcast important messages to all staff members
- 📈 Reports: Generate comprehensive reports on tasks, attendance, and performance
- 🗓️ Calendar View: Visualize tasks and schedules in an interactive calendar
- 👁️ Task Monitoring: Real-time tracking of task status and completion
- 👀 Team Oversight: Monitor assigned team members and their tasks
- ✅ Task Verification: Review and approve completed tasks with photo evidence
- 📊 Team Performance: Track team statistics and productivity metrics
- 📝 Task Management: Assign and reassign tasks to team members
- 🎯 Performance Tracking: Monitor individual and team KPIs
- 📱 Task Dashboard: View assigned tasks with priorities and deadlines
- ✓ Task Completion: Mark tasks complete with photo uploads
- 📸 Photo Documentation: Upload before/after photos for task verification
- ⏰ Attendance System: Simple time-based check-in/check-out functionality
- 📜 Attendance History: View personal attendance records
- 📢 View Announcements: Stay updated with organizational news
- ❓ FAQ Access: Quick access to common questions and procedures
- 🔐 JWT Authentication: Secure token-based authentication system
- ⏰ Time Tracking: Simple and reliable attendance time recording
- 🖼️ Image Management: Upload and manage task completion photos
- 🔄 Real-Time Sync: Instant updates across all connected devices
- 📱 Responsive Design: Works on desktop, tablet, and mobile
- 🎨 Modern UI/UX: Clean, intuitive interface built with Vuetify
- 🔍 Advanced Filtering: Search and filter tasks by multiple criteria
- 📅 Weekly Routines: Set up recurring weekly cleaning schedules
- Framework: Spring Boot 3.x
- Language: Java 17+
- Security: Spring Security + JWT
- Database: MySQL 8.0+
- ORM: Spring Data JPA / Hibernate
- Build Tool: Maven
- API: RESTful architecture
- Framework: Vue.js 3.x
- UI Library: Vuetify 3.x
- State Management: Vue Router
- HTTP Client: Axios
- Build Tool: Vue CLI / Webpack
- Maps: Geolocation API
- Version Control: Git
- Database Migration: SQL Scripts
- API Testing: Postman (recommended)
- Code Quality: ESLint, Prettier
┌─────────────────────────────────────────────────────────────┐
│ Frontend Layer │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Admin │ │Supervisor│ │ Janitor │ │ Login │ │
│ │ View │ │ View │ │ View │ │ View │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ Vue.js + Vuetify + Vue Router │
└─────────────────────────────────────────────────────────────┘
│
HTTP/HTTPS (REST API)
│
┌─────────────────────────────────────────────────────────────┐
│ Backend Layer (Spring Boot) │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Controllers (REST Endpoints) │ │
│ ├──────────────────────────────────────────────────────┤ │
│ │ Security Layer (JWT + Spring Security) │ │
│ ├──────────────────────────────────────────────────────┤ │
│ │ Service Layer │ │
│ │ (Business Logic, Validation, GPS Verification) │ │
│ ├──────────────────────────────────────────────────────┤ │
│ │ Repository Layer (JPA) │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────────────┐
│ Database Layer │
│ MySQL 8.0+ │
│ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │
│ │ Users │ │ Tasks │ │Attend. │ │ Images │ │Announce│ │
│ └────────┘ └────────┘ └────────┘ └────────┘ └────────┘ │
└─────────────────────────────────────────────────────────────┘
- MVC Architecture: Clear separation of concerns
- Repository Pattern: Data access abstraction
- Service Layer Pattern: Business logic encapsulation
- DTO Pattern: Data transfer objects for API responses
- JWT Authentication: Stateless authentication mechanism
Ensure you have the following installed:
| Tool | Version | Download |
|---|---|---|
| Java JDK | 17 or higher | Download |
| Maven | 3.6+ | Download |
| Node.js | 14+ | Download |
| MySQL | 8.0+ | Download |
| Git | Latest | Download |
-
Clone the repository
git clone https://github.com/teosam89/Cleaning-System.git cd Cleaning-System -
Set up the database
CREATE DATABASE cleaning_system; USE cleaning_system; SOURCE cleaning_system_2025_10_06_14_42_40-dump.sql;
-
Run the application
# Simply double-click start-full-stack.bat -
Access the application
- Frontend: http://localhost:3000
- Backend API: http://localhost:8765/api
# Navigate to backend directory
cd cleaning-system-backend
# Install dependencies and build
mvn clean install
# Run the application
mvn spring-boot:runThe backend server will start on http://localhost:8765
# Navigate to frontend directory
cd cleaning-system-frontend
# Install dependencies
npm install
# Run development server
npm run serveThe frontend will be available at http://localhost:3000
Edit cleaning-system-backend/src/main/resources/application.properties:
# Database Configuration
spring.datasource.url=jdbc:mysql://localhost:3306/cleaning_system
spring.datasource.username=your_username
spring.datasource.password=your_password
# JWT Configuration
app.jwt.secret=your-secret-key-here
app.jwt.expiration=86400000
# Server Configuration
server.port=8765
# File Upload Configuration
spring.servlet.multipart.max-file-size=10MB
spring.servlet.multipart.max-request-size=10MBEdit cleaning-system-frontend/src/utils/request.js:
const API_BASE_URL = 'http://localhost:8765/api';After database setup, use these credentials to log in:
| Role | Username | Password | Description |
|---|---|---|---|
| Admin | admin | admin123 | Full system access |
| Supervisor | supervisor1 | super123 | Team management access |
| Janitor | janitor1 | janitor123 | Task execution access |
⚠️ Security Note: Change default passwords immediately in production!
- Navigate to Task Management
- Click "Create Task"
- Fill in task details (title, description, location, priority)
- Assign to janitor
- Set deadline
- Submit
- Navigate to Attendance page
- Click "Check In"
- System records current time
- Optional: Add location notes
- Check-in confirmed
- Navigate to Task Monitor
- View completed tasks
- Review uploaded photos
- Approve or request revision
POST /api/auth/login # User login
POST /api/auth/register # User registration
GET /api/auth/me # Get current user
GET /api/tasks # Get all tasks
GET /api/tasks/{id} # Get task by ID
POST /api/tasks # Create new task
PUT /api/tasks/{id} # Update task
DELETE /api/tasks/{id} # Delete task
GET /api/tasks/filter # Filter tasks
POST /api/attendance/checkin # Check in
POST /api/attendance/checkout # Check out
GET /api/attendance/status # Get attendance status
GET /api/attendance/history # Get attendance history
For complete API documentation, see docs/API.md
cd cleaning-system-backend
mvn testcd cleaning-system-frontend
npm run test:unitcd cleaning-system-backend
mvn clean package
java -jar target/cleaning-system-backend-1.0.0.jarcd cleaning-system-frontend
npm run build
# Deploy the 'dist' folder to your web server# Coming soon
docker-compose up -dFor detailed deployment instructions, see docs/DEPLOYMENT.md
We welcome contributions! Please follow these steps:
- Fork the repository
- Create a feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
See CONTRIBUTING.md for detailed guidelines.
This project is licensed under the MIT License - see the LICENSE file for details.
- Issues: GitHub Issues
- Email: qianyi220822@gmail.com
- Documentation: Wiki
- Spring Boot team for the excellent framework
- Vue.js community for the reactive framework
- Vuetify for the beautiful Material Design components
- All contributors who have helped this project grow
- ✅ Core Features: Complete
- ✅ Authentication: Complete
- ✅ Time-Based Attendance: Complete
- ✅ Task Management: Complete
- 🚧 Reporting System: In Progress
- 📅 Mobile App: Planned
Made with ❤️ by the Cleaning System Team
⭐ Star us on GitHub — it helps!