Skip to content

Tracker Routes Refactoring

The tracker API routes have been refactored from a single monolithic file into smaller, more manageable modules for better maintainability and code organization.

Background

The original app/api/routes/trackers.py file had grown to over 700 lines and contained multiple distinct areas of functionality, making it difficult to maintain and edit. This refactoring splits the functionality into logical modules while maintaining full backward compatibility.

File Structure

The tracker routes are now organized in app/api/routes/trackers/ with the following structure:

__init__.py

  • Main router that combines all tracker endpoints
  • Imports functions from individual modules and registers them with the router
  • Maintains backward compatibility with the original API structure

listing.py

  • Purpose: Main tracker listing and search functionality
  • Endpoints:
  • GET / - List trackers with filtering, pagination, and sorting
  • Supports filters: id, production_run_id, status, name
  • Includes caching and performance tracking
  • Optional latest location inclusion

crud.py

  • Purpose: Core CRUD (Create, Read, Update, Delete) operations
  • Endpoints:
  • POST / - Create new tracker
  • GET /{tracker_id} - Get tracker by ID (full details)
  • PUT /{tracker_id} - Update tracker
  • DELETE /{tracker_id} - Delete tracker
  • Features: Client filtering, permission checks, cache invalidation

location_history.py

  • Purpose: Location history operations for trackers
  • Endpoints:
  • GET /{tracker_id}/location-history - Get paginated location history
  • Features: Date filtering, coordinate processing, pagination

status.py

  • Purpose: Status-related operations
  • Endpoints:
  • GET /status-counts - Get tracker counts by status
  • GET /{tracker_id}/status-history - Get status history for a tracker
  • POST /{tracker_id}/status - Create new status entry
  • Features: Status enumeration, client filtering, cache invalidation

csv_import.py

  • Purpose: CSV import functionality
  • Endpoints:
  • POST /import-csv - Import trackers from CSV file
  • Features:
  • Flexible column name matching (case-insensitive)
  • Duplicate detection
  • Error handling and rollback
  • Temporary file management

Benefits of Refactoring

  1. Maintainability: Each file focuses on a specific area of functionality
  2. Readability: Smaller files (80-180 lines vs 700+ lines) are easier to understand and navigate
  3. Testing: Individual modules can be tested in isolation
  4. Collaboration: Multiple developers can work on different aspects without conflicts
  5. Code Organization: Related functionality is grouped together
  6. Reduced Merge Conflicts: Changes to different functional areas are less likely to conflict

Backward Compatibility

The refactoring maintains full backward compatibility:

  • All existing API endpoints work exactly as before
  • Response formats are unchanged
  • Import paths remain the same (from app.api.routes import trackers)
  • All route decorators and response models are preserved
  • Client filtering and permission checks remain intact
  • Caching behavior is unchanged

File Size Comparison

Module Lines Purpose
Original trackers.py 700+ All tracker functionality
listing.py ~170 Listing and search
crud.py ~180 CRUD operations
location_history.py ~80 Location history
status.py ~100 Status operations
csv_import.py ~170 CSV import
__init__.py ~45 Router combination

Migration Notes

  • No changes required for existing API clients
  • The original file has been backed up as trackers_backup.py
  • All functionality has been preserved and tested
  • Import statements continue to work as before

Future Considerations

This modular structure makes it easier to:

  • Add new tracker-related functionality
  • Implement feature-specific optimizations
  • Write focused unit tests
  • Onboard new developers to specific areas
  • Maintain and debug individual features