🚛 FleetTracker Pro

Comprehensive Driver Tracking SaaS Application for Indonesian Fleet Management

🎯 Overview

FleetTracker Pro is a comprehensive SaaS application designed specifically for Indonesian logistics companies and fleet operators. The platform provides real-time GPS tracking, driver behavior analysis, and operational efficiency through advanced analytics and reporting.

🌟 Key Features

📍 Real-Time GPS Tracking - 30-second update intervals with 99.5% accuracy
👨‍💼 Driver Behavior Monitoring - Comprehensive scoring system (0-100 scale)
⛽ Fuel Consumption Analytics - Advanced tracking with IDR cost analysis
🗺️ ETA Prediction & Route Optimization - AI-powered route suggestions
💳 Indonesian Payment Integration - QRIS, GoPay, OVO, DANA support
🌏 Multi-language Support - Bahasa Indonesia & English
📊 Advanced Analytics - Custom reports and compliance tracking

🏗️ Architecture

Technology Stack

Backend

Go (Golang) - High-performance backend with excellent concurrency
PostgreSQL 18 - Robust database with PostGIS for geospatial data
TimescaleDB - Time-series data optimization for GPS tracking
Gin Framework - Lightweight, fast HTTP web framework
JWT Authentication - Stateless, scalable authentication

Frontend

Vite + TypeScript - Modern build tool with type safety
TanStack Query - Powerful server state management
Better Auth - Modern authentication with excellent TypeScript support
TailwindCSS - Utility-first CSS framework
React Leaflet - Interactive maps for fleet visualization

Infrastructure

Docker - Containerized deployment
Redis - Caching and session storage
WebSocket - Real-time GPS updates
Indonesian Cloud Providers - Data residency compliance

System Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │    Backend      │    │   Database      │
│                 │    │                 │    │                 │
│ Vite + TS       │◄──►│ Go + Gin        │◄──►│ PostgreSQL 18   │
│ TanStack Query  │    │ JWT Auth        │    │ PostGIS         │
│ Better Auth     │    │ WebSocket       │    │ TimescaleDB     │
│ TailwindCSS     │    │ REST APIs       │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         │              ┌─────────────────┐             │
         │              │  External APIs  │             │
         │              │                 │             │
         └──────────────┤ Google Maps     │─────────────┘
                        │ QRIS Payment    │
                        │ WhatsApp API    │
                        └─────────────────┘

🚀 Quick Start

Prerequisites

Go 1.21+ - Download
Node.js 18+ - Download
PostgreSQL 18+ with PostGIS - Download
Docker & Docker Compose - Download

Installation

Clone the repository

git clone https://github.com/tobangado69/fleettracker-pro.git
cd fleettracker-pro

Set up environment variables

# Copy example environment files
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env

# Edit with your configuration
nano backend/.env
nano frontend/.env

Start with Docker Compose (Recommended)

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

Initialize Database

cd backend

# Run migrations
make migrate-up

# Seed database (creates super-admin)
make seed

# ✅ Super-Admin Credentials:
# Email: [email protected]
# Password: ChangeMe123!
# ⚠️  MUST change password on first login!

Manual Setup (Development)

# Start database
docker-compose up -d postgres redis

# Backend setup
cd backend
go mod download
make migrate-up
make seed
go run cmd/server/main.go

# Frontend setup (new terminal)
cd frontend
npm install
npm run dev

Access the Application

Frontend: http://localhost:5173
Backend API: http://localhost:8080
Swagger UI: http://localhost:8080/swagger/index.html
Health Check: http://localhost:8080/health
Database: localhost:5432 (postgres/fleettracker)

🔐 First Login & Setup

FleetTracker Pro uses an invite-only system - there is no public registration for security.

Step 1: Super-Admin Login

# Login with default super-admin credentials
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "ChangeMe123!"
  }'

# Response includes: "must_change_password": true
# Save the access_token

Step 2: Change Password (Required)

# Change password before accessing other features
curl -X PUT http://localhost:8080/api/v1/auth/change-password \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "current_password": "ChangeMe123!",
    "new_password": "YourSecurePassword123!"
  }'

# ✅ Password changed, full access granted

Step 3: Invite Users

# Create company owner (super-admin only)
curl -X POST http://localhost:8080/api/v1/users \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "role": "owner",
    "company_id": "company-uuid"
  }'

# System generates temporary password and logs it
# User receives invitation (logged to console for now)
# User must change password on first login

User Invitation Flow:

Admin creates user via POST /users (no password = auto-generated)
System generates secure temporary password
Temporary password logged to console (email service TODO)
User logs in with temporary password
User forced to change password
User gains full access after password change

📚 Documentation

📂 Documentation Structure (Updated October 10, 2025)

Documentation has been organized by technology stack:

🎯 Quick Links by Role

Backend Developers: Start with Backend Technical Guide
Frontend Developers: Start with Frontend Technical Guide
Product Managers: Read Backend PRD + Frontend PRD
UX/UI Designers: Focus on Frontend PRD
All Roles: Use Documentation Index for navigation

📋 Backend Documentation (✅ 100% Complete)

Backend PRD - API & Services requirements (80+ endpoints documented)
Backend Technical Guide - Complete Go + PostgreSQL implementation

🎨 Frontend Documentation (🚧 In Planning)

Frontend PRD - UI/UX requirements and user flows
Frontend Technical Guide - React + TypeScript architecture (12-week plan)

🔗 API & Reference

Swagger UI - Interactive API documentation
Documentation Index - Central navigation hub

📁 Project Structure

fleettracker-pro/
├── backend/               # Go backend application (✅ 100% Complete)
│   ├── cmd/server/        # Application entry point
│   ├── internal/          # Private application code
│   │   ├── auth/          # Authentication service
│   │   ├── vehicle/       # Vehicle management
│   │   ├── tracking/      # GPS tracking service
│   │   ├── driver/        # Driver management
│   │   └── common/        # Shared utilities
│   ├── pkg/               # Public library code
│   ├── migrations/        # Database migrations
│   └── docs/              # API documentation (Swagger)
├── frontend/              # React frontend application (🚧 In Planning)
│   ├── src/
│   │   ├── components/    # Reusable UI components
│   │   ├── pages/         # Page components
│   │   ├── hooks/         # Custom React hooks
│   │   ├── services/      # API service layer
│   │   ├── stores/        # State management
│   │   └── types/         # TypeScript type definitions
│   └── public/            # Static assets
├── docs/                  # Project documentation (NEW STRUCTURE)
│   ├── backend/           # Backend-specific documentation
│   │   ├── PRD.md         # Backend product requirements
│   │   └── technical-implementation-guide.md
│   ├── frontend/          # Frontend-specific documentation
│   │   ├── PRD.md         # Frontend product requirements
│   │   └── technical-implementation-guide.md
│   └── README.md          # Documentation navigation index
├── specs/                 # SDD specifications (15 features)
│   ├── active/            # Active feature briefs
│   └── BACKEND_COMPLETION_STATUS.md
├── docker-compose.yml     # Development environment
├── Dockerfile             # Production container
└── README.md              # This file

🔧 Development

Backend Development

cd backend

# Install dependencies
go mod download

# Run tests
go test ./...

# Run with hot reload (install air first)
go install github.com/cosmtrek/air@latest
air

# Generate API documentation
swag init -g cmd/server/main.go

Frontend Development

cd frontend

# Install dependencies
npm install

# Start development server
npm run dev

# Run tests
npm run test

# Build for production
npm run build

# Type checking
npm run type-check

Database Management

# Run migrations
cd backend
go run cmd/migrate/main.go up

# Create new migration
go run cmd/migrate/main.go create add_new_table

# Rollback migration
go run cmd/migrate/main.go down 1

🌏 Indonesian Market Features

Payment Integration

QRIS - Indonesian standardized QR payment
Bank Transfer - BCA, Mandiri, BNI, BRI integration
E-Wallet - GoPay, OVO, DANA, ShopeePay support

Localization

Currency - Indonesian Rupiah (IDR) with proper formatting
Language - Bahasa Indonesia with English fallback
Timezone - WIB/WITA/WIT support
Phone Numbers - Indonesian phone number validation

Compliance

Data Residency - All data stored within Indonesia
Transportation Regulations - Ministry of Transportation compliance
Labor Laws - Driver working hours tracking
Privacy Laws - Indonesian data protection compliance

📊 Performance Targets

API Response Time: < 200ms (95th percentile)
GPS Data Processing: < 30 seconds
Frontend Loading: < 3 seconds
Database Queries: Optimized with proper indexing
WebSocket Stability: > 99% uptime
System Availability: 99.9% SLA

🔐 Security

Authentication Model

Invite-Only System: No public registration - enhanced security for B2B SaaS
Super-Admin Seed: Initial administrator created via secure database seed
JWT Authentication: Stateless, scalable token-based authentication
Force Password Change: Users must change temporary password on first login
5-Tier Role Hierarchy: super-admin → owner → admin → operator → driver
Session Management: Track and revoke active sessions

Security Features

Multi-Tenant Isolation: Strict company data isolation (100% secure)
Data Encryption: AES-256 encryption at rest and in transit
Access Control: Role-based access control (RBAC) with privilege escalation prevention
Audit Logging: Complete audit trail for all actions
Input Validation: 80+ Indonesian-specific validators
Rate Limiting: API rate limiting and DDoS protection
Temporary Passwords: Crypto-secure random password generation
Cache Invalidation: Automatic cache/session invalidation on password change

🧪 Testing

# Backend tests
cd backend
go test -v ./...

# Frontend tests
cd frontend
npm run test

# Integration tests
docker-compose -f docker-compose.test.yml up --abort-on-container-exit

# E2E tests
npm run test:e2e

🚀 Deployment

Production Deployment

# Build production images
docker build -t fleettracker/backend:latest ./backend
docker build -t fleettracker/frontend:latest ./frontend

# Deploy to Indonesian cloud provider
kubectl apply -f k8s/

# Monitor deployment
kubectl get pods -l app=fleettracker

Environment Configuration

Development: Local development with Docker Compose
Staging: Staging environment for testing
Production: Indonesian cloud deployment with data residency

📈 Monitoring & Observability

Metrics: Prometheus + Grafana dashboards
Logging: Structured logging with ELK stack
Tracing: Distributed tracing with Jaeger
Health Checks: Kubernetes health and readiness probes
Alerts: Critical system alerts via WhatsApp/SMS

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Follow Go best practices and conventions
Write comprehensive tests for new features
Update documentation for API changes
Ensure Indonesian market requirements are met
Follow security best practices

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📞 Support

Documentation: docs/
Issues: GitHub Issues
Discussions: GitHub Discussions
Email: [email protected]

🏆 Success Metrics

Business Impact

25% reduction in fuel consumption within 6 months
30% improvement in delivery time accuracy
20% decrease in vehicle maintenance costs
95% user satisfaction rating
40% reduction in unauthorized vehicle usage

Technical Metrics

99.5% GPS data accuracy
99.9% system uptime
<2 second dashboard load time
<30 second real-time update latency

Built with ❤️ for Indonesian Fleet Management

FleetTracker Pro - Real-Time Visibility, Data-Driven Insights

Name		Name	Last commit message	Last commit date
Latest commit History 73 Commits
.cursor		.cursor
.sdd		.sdd
Example		Example
backend @ 1882c40		backend @ 1882c40
docs		docs
specs		specs
.gitignore		.gitignore
.gitmodules		.gitmodules
PROJECT_STATUS.md		PROJECT_STATUS.md
README.md		README.md
SETUP_SUBMODULES.md		SETUP_SUBMODULES.md
SUBMODULE_PLAN.md		SUBMODULE_PLAN.md
TODO.md		TODO.md
sdd-explanation.md		sdd-explanation.md

tobangado69/fleettracker-pro

Folders and files

Latest commit

History

Repository files navigation