v0.5.0 — Tracking, Real-Time Push, and Alerts Foundation

v0.5.0 — Tracking, Real-Time Push, and Alerts Foundation

This release covers everything since v0.4.0, including an unplanned but
critical security hardening pass — see below.

---

⚠️ Security Hardening (previously unreleased)

The API had no authentication at all until this point. Every endpoint
was publicly readable and writable, and customer-scoped routes had no
ownership check — any authenticated (or entirely unauthenticated) caller
could read or modify any customer's data, including live vehicle location.

Fixed:

• Firebase JWT bearer authentication, validated against Google's own
  signing keys — no custom login/token-issuing endpoint
• Deny-by-default authorization policy: every endpoint now requires a
  valid token unless explicitly marked [AllowAnonymous]
• Customer.FirebaseUid links Firebase accounts to customer records
• [OwnsCustomer] filter for {customerId} routes; service-layer
  ownership checks for vehicle/telemetry routes keyed by a resource ID
  rather than a customer ID
• Staff-only role restriction on list ("get all") endpoints
• Non-owned resources return 404, not 403 — avoids confirming a
  resource's existence to a caller who doesn't own it
• Production exception handler no longer leaks raw database error
  details in its response

If you're consuming this API from any client, every request now
requires a valid Firebase Bearer token — this is a breaking change from
prior versions.

---

GPS Tracking History

• GET /api/gpstracking/trips — computes trip and stop reports for a
  vehicle over a date range
• Each trip includes start/end point and time, duration, real route
  distance (sum of point-to-point movement, not straight-line
  displacement), and max/avg speed
• Each stop includes location and full duration (5+ continuous
  minutes stationary)
• GPS-jitter filtering: a "trip" additionally requires 100m+ of genuine
  displacement, so drift while parked isn't misread as a trip

Real-Time Location Push

Replaces fixed-interval polling with live push, typically under 2
seconds from database write to client receipt:

• A Postgres trigger fires pg_notify on every CurrentLocations write
• A background listener service holds a persistent, session-pooled
  connection and relays notifications to a SignalR hub
• Clients join a per-vehicle SignalR group; joining enforces the same
  ownership rule as REST endpoints

Infrastructure note: the listener requires Supabase's session
pooler (port 5432), not the transaction pooler (port 6543) used
elsewhere — LISTEN/NOTIFY needs a stable, persistent connection that
transaction-mode pooling can't provide.

Alerts & Notifications (Foundation)

• GET /api/alerts — caller's own alert history, ownership-scoped
• PATCH /api/alerts/{alertId}/read — mark as read
• POST /api/alerts/register-token — register/refresh an FCM device token
• Not yet included: push delivery and the trigger logic that detects
  alert-worthy conditions (ignition change, overspeed, power-cut, low
  battery, device offline, geofence). The data model supports these alert
  types; nothing yet creates an Alert row automatically.

---

Upgrade notes

• No manual data migration needed for existing records — all new tables
  (Alerts, CustomerFcmTokens) are additive.
• Any client integration must be updated to send a Firebase Bearer token
  on every request, per the security hardening above.

What's next (v0.6.0)

• Alerts push delivery (FCM) + trigger detection for state-change alerts
• Device offline detection (periodic check)
• Geofencing (new schema, fence management, boundary-crossing detection)

Full changelog: see [README.md](./README.md#release-history)

ShaloTrack API v0.4.0

ShaloTrack API v0.4.0 – Telemetry Foundation Release

Release Date: 2026-07-06

🚀 Overview

This release marks the transition from a business management API to a real-time GPS tracking platform. It introduces the first telemetry-focused APIs, allowing clients to retrieve live GPS information from devices connected through the ShaloTrack Gateway, alongside significant architectural improvements to support high-performance read queries.

---

✨ New Features

📍 Current Location API

New query-oriented architecture built around projections rather than full entity retrieval.

Implemented:

• Projection-based queries
• Read-only repository pattern
• Live vehicle locations
• Vehicle lookup
• Device lookup

Endpoints:

• GET /api/currentlocations
• GET /api/currentlocations/vehicle/{vehicleId}
• GET /api/currentlocations/device/{deviceId}

📡 Device Status API

Implemented:

• Online Status
• Battery Level
• GPS Signal
• Ignition Status
• Movement Status
• Power Status

Endpoints:

• GET /api/devicestatus
• GET /api/devicestatus/device/{deviceId}
• GET /api/devicestatus/vehicle/{vehicleId}

---

🏗 Architecture Improvements

This is the biggest part of this release: the introduction of the Query Repository Pattern for telemetry data.

Before: every repository returned full entities.

Now: telemetry modules follow a dedicated read pipeline:

Projection → DTO → Repository → Service

Expression Mapping

Introduced Expression<Func<TEntity, DTO>> for query projections.

Benefits:

• No duplicated mappings
• Better EF Core SQL generation
• Faster queries
• Easier maintenance

Read vs. Write Separation

Business Modules	Telemetry Modules
Repository → UnitOfWork → Service	Repository → Projection → Service

---

Summary of Existing Modules (for context)

Authentication

• JWT Authentication
• Login API
• Authorization foundation

Customer Management

• Create / Update / Retrieve Customers
• Soft Delete
• Duplicate validation

Vehicle Management

• Vehicle CRUD
• Customer-Vehicle relationship
• Duplicate Vehicle Number validation
• Chassis / Engine validation

GPS Device Management

• Register GPS Device
• IMEI / SIM validation
• Activation Status, Firmware, Installation Details, Warranty Tracking

Device Assignment

• Assign / Unassign Device
• Assignment History
• Active Assignment Validation
• Transaction Support
• Business Rule Enforcement

---

⏭ Next Release (v0.5.0)

• GPS Tracking API
• Device Events API
• Raw Packet API
• Filtering
• Pagination
• Production Hardening

---

Git Tag

git add .
git commit -m "feat(api): implement Current Location and Device Status telemetry APIs"
git push origin main
git tag -a v0.4.0 -m "ShaloTrack API v0.4.0 - Telemetry Foundation Release"
git push origin v0.4.0

---

GitHub Release

Tag: v0.4.0

Title: ShaloTrack API v0.4.0 - Telemetry Foundation Release

Description:

## 🚀 Highlights
This release marks a major milestone in the ShaloTrack API by introducing the first telemetry-focused modules alongside significant architectural improvements.
✨ New Features

📍 Current Location API
📡 Device Status API
Projection-based query architecture
Expression-based DTO mapping
Read-only telemetry repositories

✅ Completed Modules

Authentication
Customer Management
Vehicle Management
GPS Device Management
Device Assignment
Current Location
Device Status

🏗 Architecture

Repository Pattern
Unit of Work
Query Repository Pattern
Projection Mapping
Dependency Injection
Layered Architecture

⏭ Coming Next

GPS Tracking
Device Events
Raw Packets
Filtering & Pagination
Production Hardening

ShaloTrack API v0.3.0

ShaloTrack API v0.3.0 – Device Assignment Module

Release Date: 2026-07-06

🚀 Overview

This release introduces the Device Assignment module, completing the core fleet management functionality of the ShaloTrack backend.

The API now supports assigning GPS devices to vehicles while enforcing business rules that prevent duplicate active assignments and preserve assignment history.

---

✨ New Features

Device Assignment Module

Implemented business-oriented assignment management.

Supported operations:

• Assign GPS Device to Vehicle
• Unassign GPS Device
• Retrieve Assignment History
• Retrieve Assignment Details

---

Business Rules

Implemented:

• One active GPS device per vehicle
• One active vehicle per GPS device
• Historical assignment preservation
• Soft unassignment using assignment status
• Automatic assignment timestamps
• Transaction-based assignment operations

---

Architecture Improvements

• Added DeviceAssignment Repository
• Added DeviceAssignment Service
• Added DeviceAssignment Controller
• Added DeviceAssignment DTOs
• Integrated DeviceAssignment into Unit of Work
• Explicit Entity Framework relationships
• Business-oriented endpoints replacing traditional CRUD

---

Completed Modules

• Authentication
• Customer Management
• Vehicle Management
• GPS Device Management
• Device Assignment

---

Upcoming

Version 0.4.0

• Current Location API
• Device Status API
• GPS Tracking History API
• Device Events API
• Raw Packet API

---

Git Tag

git add .
git commit -m "feat(api): implement Device Assignment module"
git push origin main
git tag -a v0.3.0 -m "ShaloTrack API v0.3.0 - Device Assignment"
git push origin v0.3.0

ShaloTrack API v0.2.0

ShaloTrack API v0.2.0 – GPS Device Management

Release Date: 2026-07-05

🚀 Release Overview

This release introduces the GPS Device Management module and continues the development of the ShaloTrack Fleet Management API.

The API now supports complete CRUD operations for Customers, Vehicles, and GPS Devices while maintaining a layered architecture using the Repository, Service, and Unit of Work patterns.

---

✨ New Features

GPS Device Management

Added complete GPS Device CRUD functionality.

Supported operations:

• Create GPS Device
• Retrieve all GPS Devices
• Retrieve GPS Device by ID
• Update GPS Device
• Delete GPS Device

---

Device Information

Each GPS Device stores:

• IMEI Number
• SIM Number
• Device Model
• Protocol Type
• Network Provider
• Firmware Version
• Activation Status
• Warranty Expiry Date
• Installation Date

---

Business Rules

Implemented:

• Unique IMEI validation
• Unique SIM validation
• Immutable IMEI after creation
• Automatic timestamps
• Device activation status support

---

Architecture Improvements

Implemented:

• GPS Device Repository
• GPS Device Service
• GPS Device Controller
• Repository registration
• Service registration
• Unit of Work integration

---

Existing Modules

Completed:

• Authentication
• Customer Management
• Vehicle Management
• GPS Device Management

---

Technology

• ASP.NET Core Web API
• Entity Framework Core
• PostgreSQL
• Repository Pattern
• Unit of Work Pattern
• Dependency Injection

---

Upcoming

Version 0.3.0

• Device Assignment Module
• Driver Module
• Current Location API
• Tracking History API

---

Git Tag

git add .
git commit -m "feat(api): implement GPS Device Management module"
git push origin main
git tag -a v0.2.0 -m "ShaloTrack API v0.2.0 - GPS Device Management"
git push origin v0.2.0

ShaloTrack API v0.1.0

Endpoint Reference

Author: Suwen Jayathunga — Lead Architect, ShaloTrack Lanka

All endpoints return an ApiResponse<T> envelope. The HTTP status code matches ApiResponse.StatusCode.

Swagger UI is available at /swagger in the Development environment.

---

Customer Module — /api/customers

GET /api/customers

Retrieve all customers, ordered alphabetically by full name.

Request: No body, no parameters.

Response 200 OK:

{
  "success": true,
  "statusCode": 200,
  "message": "Customers retrieved successfully.",
  "data": [
    {
      "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "fullName": "Amal Perera",
      "email": "amal@example.com",
      "phoneNumber": "+94771234567",
      "nicNumber": "199012345678",
      "address": "123 Galle Road, Colombo 3",
      "profileImage": null,
      "accountStatus": 0,
      "vehicleCount": 2
    }
  ],
  "errors": null,
  "timestamp": "2025-01-10T14:23:05Z"
}

Notes:

• Uses AsNoTracking() — read-only, no change tracking overhead
• vehicleCount is always 0 for this endpoint — GetAllAsync() does not include the Vehicles navigation property. Only GetByIdAsync uses .Include(c => c.Vehicles)
• Returns an empty list (not 404) if no customers exist

---

GET /api/customers/{customerId}

Retrieve a single customer by UUID, including their associated vehicles.

Path parameter: customerId — GUID

Response 200 OK:

{
  "success": true,
  "statusCode": 200,
  "message": "Customer retrieved successfully.",
  "data": {
    "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "fullName": "Amal Perera",
    "email": "amal@example.com",
    "phoneNumber": "+94771234567",
    "nicNumber": "199012345678",
    "address": "123 Galle Road, Colombo 3",
    "profileImage": null,
    "accountStatus": 0,
    "vehicleCount": 2
  },
  "errors": null,
  "timestamp": "2025-01-10T14:23:05Z"
}

Response 404 Not Found:

{
  "success": false,
  "statusCode": 404,
  "message": "Customer not found.",
  "data": null,
  "errors": ["No customer exists with ID '3fa85f64-5717-4562-b3fc-2c963f66afa6'."],
  "timestamp": "2025-01-10T14:23:05Z"
}

---

POST /api/customers

Create a new customer. The customer is created with AccountStatus = Active.

Request body (CreateCustomerDto):

{
  "fullName": "Amal Perera",
  "email": "amal@example.com",
  "phoneNumber": "+94771234567",
  "nicNumber": "199012345678",
  "address": "123 Galle Road, Colombo 3"
}

Field validation:

Field	Required	Max length	Format
fullName	✅	150	—
email	✅	150	Valid email address
phoneNumber	✅	20	Valid phone number
nicNumber	✅	20	—
address	❌	300	—

---

Planned Endpoints (Not Yet Implemented)

These route prefixes are defined in the existing README architecture but have no controllers yet:

/api/auth          Authentication (login, logout, refresh token)
/api/vehicles      Vehicle management
/api/devices       GPS device management
/api/tracking      Current location, tracking history, route playback
/api/trips         Trip analysis
/api/alerts        Alert history
/api/subscriptions Subscription management
/api/admin         Administrative operations
/api/dealers       Dealer operations