Design Documentation
Smart Route Planning is a full-stack web application that provides route optimization solutions for field service scheduling. The system leverages Google OR-Tools for combinatorial optimization and integrates with Google Maps APIs to deliver efficient route planning capabilities. Built with modern web technologies, it offers a responsive user interface for managing appointments, configuring fleets, and visualizing optimized routes.
Key Capabilities:
- CSV-based appointment data import and processing
- Real-time route optimization using vehicle routing algorithms
- Interactive map visualization with Google Maps integration
- Fleet management and company configuration
- Multi-day scheduling with constraint handling
The application follows a client-server architecture with clear separation between presentation, business logic, and data layers:
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Frontend │ │ Backend │ │ External APIs │
│ (React SPA) │◄──►│ (FastAPI) │◄──►│ Google Maps API │
│ │ │ │ │ Distance Matrix │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Browser Storage │ │ Redis Cache │ │ OR-Tools Solver │
│ (Redux Persist) │ │ (Distance Matrix│ │ │
└─────────────────┘ │ & Solutions) │ └─────────────────┘
└─────────────────┘
- Modularity: Clear separation of concerns with dedicated modules for optimization, data processing, and API handling
- Performance: Caching strategies and efficient algorithms to handle large datasets
- Scalability: Stateless API design supporting horizontal scaling
- Type Safety: End-to-end TypeScript implementation reducing runtime errors
- User Experience: Responsive design with real-time feedback and intuitive workflows
| Component | Technology | Version | Purpose |
|---|---|---|---|
| Framework | React | 19.x | Component-based UI development |
| Language | TypeScript | 5.7 | Type-safe JavaScript development |
| Build Tool | Vite | 6.2 | Fast development and optimized builds |
| UI Framework | Tailwind CSS | 4.1 | Utility-first styling |
| Component Library | ShadcnUI | Latest | Accessible, customizable components |
| Routing | TanStack Router | 1.119 | Type-safe routing with code splitting |
| State Management | Redux Toolkit | 2.7 | Predictable state container |
| Data Fetching | TanStack Query | 5.72 | Server state synchronization |
| Maps Integration | @react-google-maps/api | 2.20 | Google Maps React components |
| Form Handling | React Hook Form | 7.56 | Performant form management |
| Validation | Zod | 3.24 | Schema-based validation |
frontend/src/
├── components/ # Reusable UI components
├── routes/ # File-based routing pages
├── store/ # Redux state management
├── types/ # TypeScript definitions
├── utils/ # API client and utilities
└── lib/ # Third-party configurations
-
/- File upload and CSV processing interface -
/scenarios/- Calendar overview with appointment scheduling -
/map-view/- Interactive route visualization and optimization -
/daily-plan/- Detailed daily route breakdown -
/company-config/- Fleet and company settings management
The application uses Redux Toolkit with the following state slices:
-
scenarios- Appointment data from CSV uploads -
companyInfo- Fleet configuration and company settings -
solutions- Cached optimization results by date -
excludedAppointments- User-managed appointment exclusions -
routeVisibility- Map visualization controls
backend/
├── solver/ # Optimization engine
│ ├── models.py # Data models and schemas
│ ├── preprocessing.py # Data preparation
│ ├── solver.py # OR-Tools implementation
│ ├── postprocessing.py # Solution enhancement
│ └── validation.py # Constraint validation
├── testdata/ # Test datasets and samples
├── app.py # FastAPI application
├── distance_matrix.py # Google Maps integration with Redis caching
├── inputAnalyzer.py # CSV processing
└── redis_client.py # Caching layer
- Optimization Engine: OR-Tools VRP solver with constraint handling
- Data Processing: CSV parsing, validation, and geocoding
- External API Integration: Google Maps Distance Matrix and Geocoding with Redis caching
- Caching Layer: Redis-based performance optimization for distance matrices and solutions
- Validation Service: Business rule enforcement and data integrity
- Data Input: CSV appointment data uploaded via frontend
- Processing: Backend validates and geocodes addresses
- Distance Matrix: Calculate travel times with Redis caching for performance
- Optimization: OR-Tools generates optimal vehicle routes using cached distance data
- Enhancement: Route refinement and solution post-processing
- Caching: Results stored in Redis for performance
- Visualization: Routes displayed on interactive maps
The frontend communicates with the backend through RESTful APIs:
- GET /api/test - Handle test endpoint for API health verification
- GET /api/redis-health - Redis health check and connection status
- POST /api/appointments - Receive and process appointment data
- POST /api/distance-matrix - Calculate full distance matrix with Redis caching
- POST /api/enhance-opti-request - Enhanced optimization request processing
- POST /api/solve-without-check - Direct route optimization without validation
- POST /api/check-and-solve - Validate constraints and solve optimization
- POST /api/testdata/optimization-request - Test optimization with sample data
- GET /api/test - Basic API health verification
- GET /api/redis-health - Redis connection status and cache health
- POST /api/appointments - Process appointment data from CSV uploads
- POST /api/distance-matrix - Calculate travel times and distances with Redis caching
- POST /api/enhance-opti-request - Enhanced optimization with additional constraints
- POST /api/solve-without-check - Direct optimization without pre-validation
- POST /api/check-and-solve - Validate data and constraints before optimization
- POST /api/testdata/optimization-request - Test optimization using sample datasets
- Maps JavaScript API: Interactive map visualization
- Distance Matrix API: Travel time and distance calculations with Redis caching
- Geocoding API: Address validation and coordinate conversion
- Google OR-Tools: Vehicle routing problem optimization
- Redis: High-performance caching for distance matrices, solutions, and session storage
- Docker: Containerized deployment and scaling
- Environment-based API key management
- Input validation using Pydantic models
- CORS configuration for cross-origin requests
- Rate limiting for external API calls
- Client-side validation with Zod schemas
- Secure credential storage in environment variables
- Type safety preventing common security vulnerabilities
- Code splitting with TanStack Router
- Redux state persistence for improved UX
- TanStack Query caching for reduced API calls
- Lazy loading of components and routes
- Redis caching for expensive operations including distance matrix calculations
- Efficient OR-Tools algorithm configuration
- Asynchronous API endpoints with FastAPI
- Cached distance matrix results to minimize Google Maps API calls
- Intelligent cache invalidation strategies for location-based data
# Frontend
VITE_API_URL=http://localhost:8080
VITE_GOOGLE_MAPS_API_KEY=your_api_key
# Backend
GOOGLE_MAPS_API_KEY=your_api_key
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_DB=0
- Docker containers for consistent deployment
- Separate development and production configurations
- Environment-specific Docker Compose files
- Frontend: Modern web browser with JavaScript support
- Backend: Python 3.11+, Redis server
- External: Google Maps API access with sufficient quotas
- Node.js 18+ for frontend development
- Python 3.11+ with pip for backend development
- Docker and Docker Compose for containerization
- Redis server for caching functionality
Smart Route Planning delivers a comprehensive solution for field service route optimization through modern web technologies and proven optimization algorithms. The architecture supports scalability, maintainability, and performance while providing an intuitive user experience for complex route planning scenarios. The Redis caching layer significantly improves performance by reducing redundant Google Maps API calls and storing frequently accessed distance matrices.