Architecture Overview The fleet tracking service is designed according to Robert C. Martin's Clean Architecture: cmd/ └── api/ └── main.go internal/ ├── domain/ │ ├── entity/ │ ├── repository/ │ ├── service/ │ └── valueobject/ │ ├── application/ │ ├── dto/ │ ├── ports/ │ └── usecase/ │ ├── infrastructure/ │ ├── grpc/ │ ├── persistence/ │ ├── alerts/ │ └── telemetry/ │ └── presentation/ └── http/ Dependency direction: Presentation ↓ Application ↓ Domain ↑ Infrastructure --- DOMAIN LAYER Core Business Rules Fleet positions are immutable telemetry events. Shipments follow a planned route manifest. Route deviation occurs when current GPS position exceeds allowed distance threshold from the nearest route waypoint. Shipment delay occurs when ETA exceeds planned arrival time plus grace period. Alert generation is a domain concern. Persistence and communication are infrastructure concerns. --- internal/domain/entity/location.go package entity import "time" type GPSLocation struct { Latitude float64 Longitude float64 Timestamp time.Time } --- internal/domain/entity/route.go package entity type Waypoint struct { Sequence int Latitude float64 Longitude float64 } type RouteManifest struct { ShipmentID string AllowedDeviation float64 Waypoints []Waypoint } --- internal/domain/entity/shipment.go package entity import "time" type Shipment struct { ID string VehicleID string PlannedArrival time.Time Current GPSLocation } --- internal/domain/entity/alert.go package entity import "time" type AlertType string const ( AlertRouteDeviation AlertType = "ROUTE_DEVIATION" AlertShipmentDelay AlertType = "SHIPMENT_DELAY" ) type Alert struct { ID string ShipmentID string Type AlertType Message string CreatedAt time.Time } --- internal/domain/repository/shipment_repository.go package repository import ( "context" "fleet/internal/domain/entity" ) type ShipmentRepository interface { FindByVehicleID( ctx context.Context, vehicleID string, ) (*entity.Shipment, error) UpdateLocation( ctx context.Context, shipmentID string, location entity.GPSLocation, ) error } --- internal/domain/repository/manifest_repository.go package repository import ( "context" "fleet/internal/domain/entity" ) type ManifestRepository interface { GetByShipmentID( ctx context.Context, id string, ) (*entity.RouteManifest, error) } --- internal/domain/repository/alert_repository.go package repository import ( "context" "fleet/internal/domain/entity" ) type AlertRepository interface { Store( ctx context.Context, alert entity.Alert, ) error } --- internal/domain/service/route_analyzer.go package service import ( "fleet/internal/domain/entity" "math" ) type RouteAnalyzer struct{} func (r RouteAnalyzer) HasDeviation( location entity.GPSLocation, manifest entity.RouteManifest, ) bool { minDistance := math.MaxFloat64 for _, wp := range manifest.Waypoints { d := haversine( location.Latitude, location.Longitude, wp.Latitude, wp.Longitude, ) if d < minDistance { minDistance = d } } return minDistance > manifest.AllowedDeviation } func haversine( lat1, lon1, lat2, lon2 float64, ) float64 { const earthRadius = 6371.0 dLat := (lat2 - lat1) * math.Pi / 180 dLon := (lon2 - lon1) * math.Pi / 180 a := math.Sin(dLat/2)*math.Sin(dLat/2) + math.Cos(lat1*math.Pi/180)* math.Cos(lat2*math.Pi/180)* math.Sin(dLon/2)* math.Sin(dLon/2) return earthRadius * 2 * math.Atan2( math.Sqrt(a), math.Sqrt(1-a), ) } --- internal/domain/service/delay_detector.go package service import "time" type DelayDetector struct { GracePeriod time.Duration } func (d DelayDetector) IsDelayed( planned time.Time, now time.Time, ) bool { return now.After( planned.Add(d.GracePeriod), ) } --- APPLICATION LAYER --- internal/application/dto/telemetry.go package dto import "time" type IngestTelemetryRequest struct { VehicleID string Latitude float64 Longitude float64 Timestamp time.Time } type IngestTelemetryResponse struct { ShipmentID string Alerts []string } --- internal/application/ports/alert_dispatcher.go package ports import ( "context" "fleet/internal/domain/entity" ) type AlertDispatcher interface { Dispatch( ctx context.Context, alert entity.Alert, ) error } --- internal/application/usecase/ingest_telemetry.go package usecase import ( "context" "errors" "fmt" "time" "fleet/internal/application/dto" "fleet/internal/application/ports" "fleet/internal/domain/entity" "fleet/internal/domain/repository" "fleet/internal/domain/service" "github.com/google/uuid" ) type IngestTelemetry struct { ShipmentRepo repository.ShipmentRepository ManifestRepo repository.ManifestRepository AlertRepo repository.AlertRepository Dispatcher ports.AlertDispatcher RouteAnalyzer service.RouteAnalyzer DelayDetector service.DelayDetector } func (uc *IngestTelemetry) Execute( ctx context.Context, req dto.IngestTelemetryRequest, ) (*dto.IngestTelemetryResponse, error) { if req.VehicleID == "" { return nil, errors.New("vehicle id required") } shipment, err := uc.ShipmentRepo. FindByVehicleID(ctx, req.VehicleID) if err != nil { return nil, err } location := entity.GPSLocation{ Latitude: req.Latitude, Longitude: req.Longitude, Timestamp: req.Timestamp, } if err := uc.ShipmentRepo. UpdateLocation( ctx, shipment.ID, location, ); err != nil { return nil, err } manifest, err := uc.ManifestRepo. GetByShipmentID( ctx, shipment.ID, ) if err != nil { return nil, err } var alerts []string if uc.RouteAnalyzer. HasDeviation(location, *manifest) { alert := entity.Alert{ ID: uuid.NewString(), ShipmentID: shipment.ID, Type: entity.AlertRouteDeviation, Message: "route deviation detected", CreatedAt: time.Now(), } _ = uc.AlertRepo.Store(ctx, alert) _ = uc.Dispatcher.Dispatch(ctx, alert) alerts = append( alerts, string(alert.Type), ) } if uc.DelayDetector. IsDelayed( shipment.PlannedArrival, time.Now(), ) { alert := entity.Alert{ ID: uuid.NewString(), ShipmentID: shipment.ID, Type: entity.AlertShipmentDelay, Message: fmt.Sprintf( "shipment %s delayed", shipment.ID, ), CreatedAt: time.Now(), } _ = uc.AlertRepo.Store(ctx, alert) _ = uc.Dispatcher.Dispatch(ctx, alert) alerts = append( alerts, string(alert.Type), ) } return &dto.IngestTelemetryResponse{ ShipmentID: shipment.ID, Alerts: alerts, }, nil } --- INFRASTRUCTURE LAYER --- internal/infrastructure/persistence/postgres_shipment_repository.go package persistence import ( "context" "database/sql" "fleet/internal/domain/entity" ) type PostgresShipmentRepository struct { DB *sql.DB } func (r *PostgresShipmentRepository) FindByVehicleID( ctx context.Context, vehicleID string, ) (*entity.Shipment, error) { var s entity.Shipment err := r.DB.QueryRowContext( ctx, ` SELECT id, vehicle_id, planned_arrival FROM shipments WHERE vehicle_id=$1 `, vehicleID, ).Scan( &s.ID, &s.VehicleID, &s.PlannedArrival, ) return &s, err } func (r *PostgresShipmentRepository) UpdateLocation( ctx context.Context, id string, loc entity.GPSLocation, ) error { _, err := r.DB.ExecContext( ctx, ` UPDATE shipments SET latitude=$1, longitude=$2, last_seen=$3 WHERE id=$4 `, loc.Latitude, loc.Longitude, loc.Timestamp, id, ) return err } --- internal/infrastructure/alerts/grpc_dispatcher.go package alerts import ( "context" "fleet/internal/domain/entity" pb "fleet/proto" ) type GRPCAlertDispatcher struct { Client pb.AlertServiceClient } func (d *GRPCAlertDispatcher) Dispatch( ctx context.Context, alert entity.Alert, ) error { _, err := d.Client.Publish( ctx, &pb.AlertRequest{ ShipmentId: alert.ShipmentID, Type: string(alert.Type), Message: alert.Message, }, ) return err } --- PRESENTATION LAYER --- internal/presentation/http/tracking_handler.go package http import ( "net/http" "time" "fleet/internal/application/dto" "fleet/internal/application/usecase" "github.com/gin-gonic/gin" ) type TrackingHandler struct { UseCase *usecase.IngestTelemetry } func (h *TrackingHandler) Ingest( c *gin.Context, ) { var req struct { VehicleID string `json:"vehicle_id"` Latitude float64 `json:"latitude"` Longitude float64 `json:"longitude"` } if err := c.BindJSON(&req); err != nil { c.JSON( http.StatusBadRequest, gin.H{"error": err.Error()}, ) return } resp, err := h.UseCase.Execute( c.Request.Context(), dto.IngestTelemetryRequest{ VehicleID: req.VehicleID, Latitude: req.Latitude, Longitude: req.Longitude, Timestamp: time.Now(), }, ) if err != nil { c.JSON( http.StatusInternalServerError, gin.H{ "error": err.Error(), }, ) return } c.JSON( http.StatusOK, resp, ) } --- DEPENDENCY INJECTION --- cmd/api/main.go package main import ( "database/sql" "time" "fleet/internal/application/usecase" "fleet/internal/domain/service" "fleet/internal/infrastructure/alerts" "fleet/internal/infrastructure/persistence" transport "fleet/internal/presentation/http" "github.com/gin-gonic/gin" ) func main() { db, _ := sql.Open( "postgres", "dsn", ) shipmentRepo := &persistence. PostgresShipmentRepository{ DB: db, } manifestRepo := &persistence. PostgresManifestRepository{ DB: db, } alertRepo := &persistence. PostgresAlertRepository{ DB: db, } dispatcher := &alerts. GRPCAlertDispatcher{} uc := &usecase.IngestTelemetry{ ShipmentRepo: shipmentRepo, ManifestRepo: manifestRepo, AlertRepo: alertRepo, Dispatcher: dispatcher, RouteAnalyzer: service.RouteAnalyzer{}, DelayDetector: service.DelayDetector{ GracePeriod: 30 * time.Minute, }, } handler := &transport. TrackingHandler{ UseCase: uc, } router := gin.Default() router.POST( "/telemetry", handler.Ingest, ) router.Run(":8080") } --- gRPC CONTRACT --- proto/alert.proto syntax = "proto3"; package fleet; service AlertService { rpc Publish(AlertRequest) returns (AlertResponse); } message AlertRequest { string shipment_id = 1; string type = 2; string message = 3; } message AlertResponse { bool success = 1; } --- SOLID/CLEAN ARCHITECTURE COMPLIANCE Principle Implementation SRP Entities, use cases, repositories, and handlers have singular responsibilities OCP Alerting, persistence, and routing engines are extensible via interfaces LSP Infrastructure adapters substitute repository interfaces ISP Fine-grained repository and service contracts DIP Application layer depends exclusively on abstractions DRY Shared domain services encapsulate route and delay logic Framework Independence Domain layer has zero external dependencies Database Independence Repository pattern abstracts persistence Transport Independence HTTP and gRPC remain replaceable adapters Testability All use cases are mockable through ports/interfaces