# nammayatri/location-tracking-service architecture

> Architecture diagram of the GitHub repository nammayatri/location-tracking-service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nammayatri/location-tracking-service
- Repository: https://github.com/nammayatri/location-tracking-service

## Overview

##### Project type and purpose
- This is a Rust-based backend microservice named **location-tracking-service**.
- It ingests location events (via Kafka), applies domain logic (rate limiting, stop detection, safety checks, geo-fencing), stores/transforms state (in Redis), exposes HTTP APIs (healthchecks, location queries), and emits events to downstream systems.
- It’s intended to run as a standalone service under Nix, with Kafka and Redis as its main dependencies, and integrates with an external “dynamic-driver-offer-app” for authentication/testing.

##### File structure
- Top-level crates/ directory holds the service code:
- **common/**: shared utils (geo polygon, rate limiter, heap-size guard).
- **domain/**: business logic split into internal vs. UI-facing modules for actions and APIs.
- **kafka/**: producers, types, and configuration for consuming/producing messages.
- **redis/**: key definitions and commands for state storage.
- **outbound/**: adapters to external HTTP endpoints or services.
- **middleware.rs**: request/response interceptors (e.g., logging, auth).
- **tools/**: metrics (Prometheus), error handling.
- **main.rs** & **drainer.rs**: service entrypoints (HTTP server and background jobs).
- Config roots: geo JSON files (bus depot, blacklist, route configs), Dhall config for Nix, justfile/shell scripts for dev tasks.

##### README for additional insights
- Describes Nix-based setup, Rust build commands, service dependencies (Kafka, Redis via `just services`), and a Postman collection for API flows.

##### Key elements to capture
– Service entrypoints (`main.rs`, `drainer.rs`)
– Core modules (`domain`, `common`, `kafka`, `redis`, `outbound`)
– External dependencies (Kafka, Redis, external apps)
– Dev tools & config (Nix, Dhall, geo files, Postman)

## Diagram (Mermaid)

```mermaid
flowchart TB
  subgraph "Inbound Traffic"
    Client[/"Client UI"/]:::external
    Postman["Postman Collection"]:::external
    DynamicOffer[(Dynamic-driver-offer-app)]:::external
    KafkaBroker(("Kafka Cluster")):::datastore
  end

  subgraph "Location-Tracking Service"
    direction TB
    API["HTTP API Server"]:::service
    click API "https://github.com/nammayatri/location-tracking-service/blob/main/crates/location_tracking_service/src/main.rs"
    Middleware["Middleware"]:::middleware
    click Middleware "https://github.com/nammayatri/location-tracking-service/blob/main/crates/location_tracking_service/src/middleware.rs"
    Drainer["Background Jobs / Kafka Consumer"]:::service
    click Drainer "https://github.com/nammayatri/location-tracking-service/blob/main/crates/location_tracking_service/src/drainer.rs"
    Domain["Domain Logic Layer"]:::domain
    click Domain "https://github.com/nammayatri/location-tracking-service/tree/main/crates/location_tracking_service/src/domain/"
    Common["Shared Utilities"]:::common
    click Common "https://github.com/nammayatri/location-tracking-service/tree/main/crates/location_tracking_service/src/common/"
    KafkaInt["Kafka Integration"]:::kafka
    click KafkaInt "https://github.com/nammayatri/location-tracking-service/tree/main/crates/location_tracking_service/src/kafka/"
    RedisInt["Redis Integration"]:::redis
    click RedisInt "https://github.com/nammayatri/location-tracking-service/tree/main/crates/location_tracking_service/src/redis/"
    Outbound["Outbound Adapters"]:::service
    click Outbound "https://github.com/nammayatri/location-tracking-service/tree/main/crates/location_tracking_service/src/outbound/"
    PromMetrics["Prometheus Metrics Exporter"]:::metrics
    click PromMetrics "https://github.com/nammayatri/location-tracking-service/blob/main/crates/location_tracking_service/src/tools/prometheus.rs"
    ErrorTools["Error Handling & Tools"]:::tools
    click ErrorTools "https://github.com/nammayatri/location-tracking-service/blob/main/crates/location_tracking_service/src/tools/error.rs"
  end

  subgraph "Configuration Store"
    direction TB
    GeoJSON["Geo JSON Configs"]:::config
    click GeoJSON "https://github.com/nammayatri/location-tracking-service/tree/main/geo_config/"
    BusDepot["Bus Depot & Blacklist Configs"]:::config
    click BusDepot "https://github.com/nammayatri/location-tracking-service/tree/main/bus_depot_geo_config/"
    RouteConfig["Route GeoJSON Configs"]:::config
    click RouteConfig "https://github.com/nammayatri/location-tracking-service/tree/main/route_geo_json_config/"
    Dhall["Dhall Config"]:::config
    click Dhall "https://github.com/nammayatri/location-tracking-service/blob/main/dhall-configs/dev/location_tracking_service.dhall"
  end

  subgraph "Infra"
    RedisCluster(("Redis Cluster")):::datastore
    Prometheus["Prometheus"]:::external
  end

  Client -->|"HTTP/JSON"| API
  Postman -->|"HTTP/JSON"| API
  DynamicOffer -->|"Auth/Test HTTP"| API

  API -->|internally calls| Middleware
  Middleware -->|"invokes"| Domain
  Drainer -->|"invokes"| Domain

  Domain -->|"uses"| Common
  Domain -->|"<reads/writes>"| RedisInt
  RedisInt -->|"RESP"| RedisCluster
  Domain -->|"produces"| KafkaInt
  KafkaInt -->|Kafka| KafkaBroker
  KafkaBroker -->|Kafka Consumer| Drainer

  Domain -->|"calls"| Outbound
  Prometheus -->|scrapes| PromMetrics
  API -->|loads at startup| GeoJSON
  API -->|loads at startup| BusDepot
  API -->|loads at startup| RouteConfig
  API -->|loads at startup| Dhall

  classDef external fill:#f9f,stroke:#333,stroke-width:1px
  classDef service fill:#bbf,stroke:#333,stroke-width:1px
  classDef middleware fill:#fbf,stroke:#333,stroke-width:1px
  classDef domain fill:#bfb,stroke:#333,stroke-width:1px
  classDef common fill:#fdc,stroke:#333,stroke-width:1px
  classDef kafka fill:#ffb,stroke:#333,stroke-width:1px
  classDef redis fill:#bff,stroke:#333,stroke-width:1px
  classDef metrics fill:#dfd,stroke:#333,stroke-width:1px
  classDef tools fill:#ffd,stroke:#333,stroke-width:1px
  classDef config fill:#fcf,stroke:#333,stroke-width:1px
  classDef datastore fill:#ccf,stroke:#333,stroke-width:1px
```
