Upgrade Logistics App: UI & KMeans++
Budget: $8 – $15 USD
Application Goals & Existing Framework
Our application aims to provide a robust scheduling and route optimization system for service-based businesses. We have already established a basic Next.js/React framework, connected to Firebase for data storage, and implemented initial UI components for managing crews and customers. Building on this foundation, we will introduce the logic for KMeans++ customer distribution, MapQuest route optimization, and a user-friendly “lock” feature to ensure certain stops remain in fixed positions within any given route.
1. Overview and Objectives
Objective:
Automatically assign customers whose Next Service Date equals the Current Day to the correct crews.
Use KMeans++ (or a similar clustering algorithm) to distribute any unassigned customers evenly among active crews.
Integrate MapQuest route optimization to produce the most efficient routes for each crew.
Allow manual reordering of stops within each route and provide a “lock” feature to fix the position of certain customers.
Maintain locked positions even if a customer’s Next Service Date is changed from another tab.
Scope:
This logic affects crew management and routing for Next Service Date = Current Day within the Next.js/React application.
Utilizes Firebase as the database solution, ensuring no null values are stored (either use empty strings or omit fields).
Integrates with MapQuest (or a comparable routing service) for route optimization.
Hosted on a GitHub repository for code collaboration.
Testing will be done locally throughout development.
Assumptions & Constraints:
Firebase is the primary data store; disallowing null means storing empty strings ("") or omitting fields when data is not present.
Each Customer record includes fields for nextServiceDate, serviceFrequency, assignedCrew, and location data.
A valid MapQuest API key is available.
The user’s business “starting location” is stored in the account settings.
2. Functional Requirements
2.1 KMeans++ Distribution Logic
Trigger Condition:
When a customer’s Next Service Date is set to the current day.
When new customers are added with Next Service Date = current day.
Behavior:
Find unassigned customers (where assignedCrew is "" or the key is omitted) with Next Service Date = Current Day.
Count how many customers each active crew already has for the day.
Use KMeans++ (or a similar approach) to distribute these newly unassigned customers evenly among all active crews.
If one crew has fewer total customers, fill it until balanced before moving on.
Update each customer’s assignedCrew in Firebase (avoiding null).
Constraints & Considerations:
If there are no active crews, show an error or skip assignment.
KMeans++ must handle both large and small data sets.
Ensure Firebase writes do not use null values.
2.2 Route Optimization with MapQuest
Routing Trigger Condition:
After KMeans++ completes daily assignments.
Whenever the user initiates a “route optimization” (e.g., via a button click).
Behavior:
For each crew:
Gather the customers assigned for the current day.
Include the business starting location as the first stop.
Call MapQuest’s route optimization API to get an optimized stop order.
Update route data for each crew in Firebase, respecting any locked positions.
Constraints & Considerations:
Handle MapQuest rate limits and potential errors.
Must retain locked stops in their fixed positions (see Section 2.3).
2.3 “Locked Position” and Manual Reordering
User Interface Requirements:
A route list (possibly via drag-and-drop) to change stop order.
A lock/unlock toggle or checkbox next to each stop.
Behavior:
Locked stops remain at their exact index during future optimizations.
Unlocked stops are free to be reordered by the optimization logic.
If a new customer is added or a customer’s date changes to today, the system inserts that stop in the optimal position while preserving locked stops.
If a user unlocks a stop, it becomes movable in the next optimization.
Constraints & Considerations:
Clear visual indicators in the UI for locked vs. unlocked stops.
Partial re-optimization (only for unlocked stops) if locks exist.
3. Technical Specifications
3.1 Data Model Updates (Firebase)
Customer Collection (e.g., /customers/{customerId}):
assignedCrew: String for the crew ID or "" if unassigned.
nextServiceDate: String or Timestamp (cannot be null).
serviceFrequency: String (e.g., "one-time", "weekly", etc.).
location: Either lat/lng coordinates or an address string.
isLocked: Boolean (true = locked, false = unlocked). If the field is missing, treat as unlocked.
Crews Collection (e.g., /crews/{crewId}):
crewName: String.
isActive: Boolean.
Route Assignments (optional):
A sub-collection (e.g., /routes/{date}/{crewId}/stops) can store each stop’s customerId, stopIndex, and isLocked if you want daily historical data.
3.2 Next.js / React Integration
Front-End Components:
CrewTabs: Displays each crew’s route for the day.
RouteList: Shows assigned customers in route order (optionally using drag-and-drop).
LockToggle: Next to each item for locking/unlocking.
Firebase Integration:
Use the Firebase SDK to read/write data; do not store null.
Organize queries based on Next Service Date = current day.
MapQuest Service:
Helper function to send addresses/coordinates to the MapQuest route optimization API.
Parse and return the optimized route sequence.
3.3 KMeans++ Algorithm Details
Inputs:
Coordinates of unassigned customers.
Number of clusters = number of active crews.
Algorithm:
Initialize cluster centers using KMeans++ seeding.
Assign customers to the nearest cluster center.
Update cluster centers until distribution is balanced or stable.
Persist final assignedCrew assignments in Firebase.
3.4 Route Optimization with Locked Positions
Input:
A list of stops for each crew, plus the business start location.
A flag (isLocked) indicating which stops are locked.
Algorithm:
If the route optimization API cannot directly handle locked stops:
Segment the route around locked stops.
Optimize only the unlocked segments.
Merge them back into a final sequence with locked stops in place.
3.5 Edge Cases
No active crews -> skip assignment or show an alert.
All customers already assigned -> no distribution needed.
Invalid addresses -> handle or skip them.
Locked stops may reduce overall optimization, which is acceptable per user’s choice.
4. GitHub Repository and Collaboration
Repository Structure:
/client (Next.js/React)
/firebase (config and initialization)
/services (KMeans++, MapQuest integration)
/docs (any additional reference material)
Branching Model:
Use feature branches (e.g., feature/kmeans-logic, feature/route-optimization).
Merge to main only after code review via Pull Requests.
Issue Tracking:
Create GitHub Issues/Projects for each feature, referencing acceptance criteria.
Use labels/milestones to stay organized.
5. Deliverables
Codebase on GitHub:
KMeans++ logic for assigning customers to crews.
MapQuest route optimization integration (respecting locked stops).
UI components for manual reordering (drag-and-drop) and lock toggling.
Firebase integration (avoiding null values).
Documentation:
README.md covering Firebase and MapQuest setup, local environment configuration.
Additional reference docs in /docs (if needed).
Flowcharts or diagrams explaining the data flow and logic.
Local Testing:
Team members will run and verify the application features on their local machines.
Manual and light automated checks for KMeans++ distribution, route optimization, and lock functionality.
6. Summary
This plan will enhance our existing Next.js/React service scheduling framework with KMeans++ clustering, MapQuest route optimization, and a locked stops mechanism. Unassigned customers for the current day are automatically distributed to active crews, routes are optimized, and any manually locked positions remain fixed during updates or daily recalculations. All data is stored in Firebase without null values, and the entire project is version-controlled on GitHub for easy collaboration and local testing.
Our application aims to provide a robust scheduling and route optimization system for service-based businesses. We have already established a basic Next.js/React framework, connected to Firebase for data storage, and implemented initial UI components for managing crews and customers. Building on this foundation, we will introduce the logic for KMeans++ customer distribution, MapQuest route optimization, and a user-friendly “lock” feature to ensure certain stops remain in fixed positions within any given route.
1. Overview and Objectives
Objective:
Automatically assign customers whose Next Service Date equals the Current Day to the correct crews.
Use KMeans++ (or a similar clustering algorithm) to distribute any unassigned customers evenly among active crews.
Integrate MapQuest route optimization to produce the most efficient routes for each crew.
Allow manual reordering of stops within each route and provide a “lock” feature to fix the position of certain customers.
Maintain locked positions even if a customer’s Next Service Date is changed from another tab.
Scope:
This logic affects crew management and routing for Next Service Date = Current Day within the Next.js/React application.
Utilizes Firebase as the database solution, ensuring no null values are stored (either use empty strings or omit fields).
Integrates with MapQuest (or a comparable routing service) for route optimization.
Hosted on a GitHub repository for code collaboration.
Testing will be done locally throughout development.
Assumptions & Constraints:
Firebase is the primary data store; disallowing null means storing empty strings ("") or omitting fields when data is not present.
Each Customer record includes fields for nextServiceDate, serviceFrequency, assignedCrew, and location data.
A valid MapQuest API key is available.
The user’s business “starting location” is stored in the account settings.
2. Functional Requirements
2.1 KMeans++ Distribution Logic
Trigger Condition:
When a customer’s Next Service Date is set to the current day.
When new customers are added with Next Service Date = current day.
Behavior:
Find unassigned customers (where assignedCrew is "" or the key is omitted) with Next Service Date = Current Day.
Count how many customers each active crew already has for the day.
Use KMeans++ (or a similar approach) to distribute these newly unassigned customers evenly among all active crews.
If one crew has fewer total customers, fill it until balanced before moving on.
Update each customer’s assignedCrew in Firebase (avoiding null).
Constraints & Considerations:
If there are no active crews, show an error or skip assignment.
KMeans++ must handle both large and small data sets.
Ensure Firebase writes do not use null values.
2.2 Route Optimization with MapQuest
Routing Trigger Condition:
After KMeans++ completes daily assignments.
Whenever the user initiates a “route optimization” (e.g., via a button click).
Behavior:
For each crew:
Gather the customers assigned for the current day.
Include the business starting location as the first stop.
Call MapQuest’s route optimization API to get an optimized stop order.
Update route data for each crew in Firebase, respecting any locked positions.
Constraints & Considerations:
Handle MapQuest rate limits and potential errors.
Must retain locked stops in their fixed positions (see Section 2.3).
2.3 “Locked Position” and Manual Reordering
User Interface Requirements:
A route list (possibly via drag-and-drop) to change stop order.
A lock/unlock toggle or checkbox next to each stop.
Behavior:
Locked stops remain at their exact index during future optimizations.
Unlocked stops are free to be reordered by the optimization logic.
If a new customer is added or a customer’s date changes to today, the system inserts that stop in the optimal position while preserving locked stops.
If a user unlocks a stop, it becomes movable in the next optimization.
Constraints & Considerations:
Clear visual indicators in the UI for locked vs. unlocked stops.
Partial re-optimization (only for unlocked stops) if locks exist.
3. Technical Specifications
3.1 Data Model Updates (Firebase)
Customer Collection (e.g., /customers/{customerId}):
assignedCrew: String for the crew ID or "" if unassigned.
nextServiceDate: String or Timestamp (cannot be null).
serviceFrequency: String (e.g., "one-time", "weekly", etc.).
location: Either lat/lng coordinates or an address string.
isLocked: Boolean (true = locked, false = unlocked). If the field is missing, treat as unlocked.
Crews Collection (e.g., /crews/{crewId}):
crewName: String.
isActive: Boolean.
Route Assignments (optional):
A sub-collection (e.g., /routes/{date}/{crewId}/stops) can store each stop’s customerId, stopIndex, and isLocked if you want daily historical data.
3.2 Next.js / React Integration
Front-End Components:
CrewTabs: Displays each crew’s route for the day.
RouteList: Shows assigned customers in route order (optionally using drag-and-drop).
LockToggle: Next to each item for locking/unlocking.
Firebase Integration:
Use the Firebase SDK to read/write data; do not store null.
Organize queries based on Next Service Date = current day.
MapQuest Service:
Helper function to send addresses/coordinates to the MapQuest route optimization API.
Parse and return the optimized route sequence.
3.3 KMeans++ Algorithm Details
Inputs:
Coordinates of unassigned customers.
Number of clusters = number of active crews.
Algorithm:
Initialize cluster centers using KMeans++ seeding.
Assign customers to the nearest cluster center.
Update cluster centers until distribution is balanced or stable.
Persist final assignedCrew assignments in Firebase.
3.4 Route Optimization with Locked Positions
Input:
A list of stops for each crew, plus the business start location.
A flag (isLocked) indicating which stops are locked.
Algorithm:
If the route optimization API cannot directly handle locked stops:
Segment the route around locked stops.
Optimize only the unlocked segments.
Merge them back into a final sequence with locked stops in place.
3.5 Edge Cases
No active crews -> skip assignment or show an alert.
All customers already assigned -> no distribution needed.
Invalid addresses -> handle or skip them.
Locked stops may reduce overall optimization, which is acceptable per user’s choice.
4. GitHub Repository and Collaboration
Repository Structure:
/client (Next.js/React)
/firebase (config and initialization)
/services (KMeans++, MapQuest integration)
/docs (any additional reference material)
Branching Model:
Use feature branches (e.g., feature/kmeans-logic, feature/route-optimization).
Merge to main only after code review via Pull Requests.
Issue Tracking:
Create GitHub Issues/Projects for each feature, referencing acceptance criteria.
Use labels/milestones to stay organized.
5. Deliverables
Codebase on GitHub:
KMeans++ logic for assigning customers to crews.
MapQuest route optimization integration (respecting locked stops).
UI components for manual reordering (drag-and-drop) and lock toggling.
Firebase integration (avoiding null values).
Documentation:
README.md covering Firebase and MapQuest setup, local environment configuration.
Additional reference docs in /docs (if needed).
Flowcharts or diagrams explaining the data flow and logic.
Local Testing:
Team members will run and verify the application features on their local machines.
Manual and light automated checks for KMeans++ distribution, route optimization, and lock functionality.
6. Summary
This plan will enhance our existing Next.js/React service scheduling framework with KMeans++ clustering, MapQuest route optimization, and a locked stops mechanism. Unassigned customers for the current day are automatically distributed to active crews, routes are optimized, and any manually locked positions remain fixed during updates or daily recalculations. All data is stored in Firebase without null values, and the entire project is version-controlled on GitHub for easy collaboration and local testing.