savko-fleet-management

A production fleet management platform built from scratch to manage construction equipment, fuel trucks, and trailers across multiple operating companies.

Live system — actively used by Savko, Scioto, and Sarasota Transport operations out of Columbus, Ohio.

---

Overview

This started as a simple equipment tracker and grew into a full operations platform. It handles preventive maintenance scheduling, filter inventory, service documentation, real-time GPS/telematics via Samsara, and fuel dispensing data — all in one place, built and maintained by one engineer.

---

Architecture

┌─────────────────────┐         ┌──────────────────────┐
│   React Frontend    │ ──────▶ │   Flask REST API      │
│   (Web Browser)     │ ◀────── │   (Python/Gunicorn)   │
└─────────────────────┘         └──────────┬───────────┘
                                           │
                        ┌──────────────────┼──────────────────┐
                        │                  │                  │
               ┌────────▼──────┐  ┌────────▼──────┐  ┌───────▼────────┐
               │  MySQL DB     │  │  Kafka Topics  │  │  Samsara API   │
               │  (Equipment,  │  │  (Vehicles,    │  │  (Telematics,  │
               │   PM, Filters)│  │   Fuel, Faults)│  │   GPS, ELD)    │
               └───────────────┘  └───────────────┘  └────────────────┘

Infrastructure:

• Ubuntu VM server (savko-fuelsysserver)
• Kafka in KRaft mode (no Zookeeper) with persistent log directories
• Tailscale mesh VPN for secure remote access across all nodes
• Systemd services for auto-start/restart

---

Features

Equipment Management

• Multi-company asset tracking across Savko, Scioto, and Sarasota Transport
• Equipment types: excavators, bulldozers, scrapers, graders, compactors, fuel trucks, trailers
• Meter reset / baseline system for replaced hour meters
• Equipment archiving and generation system for reusing unit numbers

Preventive Maintenance

• Rotating PM service schedules: 250 → 500 → 750 → 1000 hour cycles for heavy equipment
• Automatic due-date calculations based on current meter readings
• Service history tracking with technician notes
• PDF service sheet generation with company branding

Filter Inventory

• Cross-reference database: CAT · Donaldson · Baldwin · Fleetguard · WIX · NAPA · Paccar · AGCO
• Stock level tracking with low-inventory alerts
• Filter-to-equipment associations for quick lookup during service

Telematics Integration

• Samsara API consumer publishing to Kafka topics:
  • samsara_vehicles — GPS position, odometer, engine hours
  • samsara_fuel — fuel level telemetry
  • samsara_faults — active DTCs and fault codes
• Real-time dashboard with vehicle status

AI Assistant

• Integrated Anthropic API assistant for maintenance Q&A
• Context-aware: knows your fleet, your equipment, your service history

---

Tech Stack

Layer	Technology
Frontend	React, JavaScript, CSS
Backend	Python, Flask, Gunicorn
Database	MySQL
Message Broker	Apache Kafka (KRaft mode)
Telematics	Samsara API
Networking	Tailscale VPN
AI	Anthropic Claude API
Server OS	Ubuntu 24 LTS
PDF Generation	ReportLab

---

Project Structure

savko-fleet-management/
├── backend/
│   ├── app.py                  # Flask application entry point
│   ├── routes/
│   │   ├── equipment.py        # Equipment CRUD endpoints
│   │   ├── maintenance.py      # PM schedule logic
│   │   ├── filters.py          # Filter inventory endpoints
│   │   └── telematics.py       # Samsara/Kafka consumer
│   ├── models/                 # SQLAlchemy models
│   └── services/
│       ├── kafka_consumer.py   # Samsara topic consumers
│       ├── pdf_generator.py    # Service sheet PDF builder
│       └── ai_assistant.py     # Anthropic API integration
└── frontend/
    ├── src/
    │   ├── components/
    │   │   ├── EquipmentList/
    │   │   ├── PMSchedule/
    │   │   ├── FilterInventory/
    │   │   └── Dashboard/
    │   └── App.js
    └── public/

---

Background

Built to solve a real problem: paper-based PM tracking across a mixed fleet of 50+ pieces of heavy equipment was causing missed services and unexpected downtime. The system now drives daily operations — mechanics pull up service sheets on their phones, office staff track filter stock, and management sees the whole fleet at a glance.

---

Status

🟢 Production — running daily across active fleet operations in Columbus, Ohio.

---

Built by Keith Soderberg