# furkaanasik/courier-tracking-system architecture

> Architecture diagram of the GitHub repository furkaanasik/courier-tracking-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/furkaanasik/courier-tracking-system
- Repository: https://github.com/furkaanasik/courier-tracking-system

## Overview

Courier Tracking System accepts courier GPS updates, persists them, then asynchronously calculates travel distance and detects nearby-store entries with a re-entry cooldown. Its query APIs expose distance, location history, and store-entry logs; store data is loaded into Redis geospatial indexing. Event and query wiring is based on the README and sampled code; listener and startup-loader internals were not sampled, so uncertain implementation links are omitted.

Main entry points: [`src/main/java/com/furkanasikdev/courier/tracking/service/CourierService.java`](https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/service/CourierService.java) (Courier Service), [`src/main/java/com/furkanasikdev/courier/tracking/controller/CourierController.java`](https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/controller/CourierController.java) (Courier API), [`src/main/java/com/furkanasikdev/courier/tracking/service/TrackingService.java`](https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/service/TrackingService.java) (Tracking Service), [`src/main/java/com/furkanasikdev/courier/tracking/event/location/LocationReceivedEvent.java`](https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/event/location/LocationReceivedEvent.java) (Location Event)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and Queries"]
  node_courier_controller["Courier API"]
  node_store_controller["Store API"]
  node_courier_service["Courier Service"]
  node_store_service["Store Service<br/>[StoreService.java]"]
end

subgraph group_tracking["Location Processing"]
  node_tracking_service["Tracking Service"]
  node_location_event["Location Event"]
  node_distance_listener["Distance Listener"]
  node_distance_strategy["Distance Strategies"]
end

subgraph group_stores["Store Proximity"]
  node_proximity_listener["Proximity Listener"]
  node_store_proximity["Proximity Service"]
  node_store_entry_event["Entry Event"]
  node_store_entry_listener["Entry Listener"]
  node_store_loader["Store Loader"]
  node_store_data["Store Dataset<br/>[stores.json]"]
end

subgraph group_persistence["Persistence and Indexing"]
  node_location_repo["Location Repository"]
  node_courier_repo["Courier Repository"]
  node_entry_repo["Entry Repository"]
  node_postgres[("PostgreSQL")]
  node_redis[("Redis")]
end

node_client(("API Client"))

node_client -->|"submits locations"| node_courier_controller
node_client -->|"requests entries"| node_store_controller
node_courier_controller -->|"processes locations"| node_tracking_service
node_courier_controller -->|"queries courier"| node_courier_service
node_courier_controller -->|"queries entries"| node_store_service
node_store_controller -->|"queries entries"| node_store_service
node_tracking_service -->|"creates courier"| node_courier_service
node_tracking_service -->|"saves location"| node_location_repo
node_tracking_service -->|"publishes event"| node_location_event
node_location_event -->|"dispatches"| node_distance_listener
node_location_event -->|"dispatches"| node_proximity_listener
node_distance_listener -->|"calculates distance"| node_distance_strategy
node_distance_listener -->|"adds distance"| node_courier_service
node_proximity_listener -->|"checks nearby stores"| node_store_proximity
node_store_proximity -->|"searches and checks cooldown"| node_redis
node_proximity_listener -->|"publishes entry"| node_store_entry_event
node_store_entry_event -->|"dispatches"| node_store_entry_listener
node_store_entry_listener -->|"saves entry"| node_entry_repo
node_courier_service -->|"reads and saves courier"| node_courier_repo
node_courier_service -->|"reads history"| node_location_repo
node_store_service -->|"reads entries"| node_entry_repo
node_location_repo -->|"persists locations"| node_postgres
node_courier_repo -->|"persists couriers"| node_postgres
node_entry_repo -->|"persists entries"| node_postgres
node_store_loader -->|"reads stores"| node_store_data
node_store_loader -->|"indexes stores"| node_redis

click node_courier_controller "https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/controller/CourierController.java"
click node_store_controller "https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/controller/StoreController.java"
click node_tracking_service "https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/service/TrackingService.java"
click node_location_event "https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/event/location/LocationReceivedEvent.java"
click node_distance_listener "https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/event/location/listener/LocationDistanceListener.java"
click node_proximity_listener "https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/event/location/listener/LocationProximityListener.java"
click node_distance_strategy "https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/calculation/distance/DistanceCalculationStrategy.java"
click node_courier_service "https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/service/CourierService.java"
click node_store_proximity "https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/service/StoreProximityService.java"
click node_store_entry_event "https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/event/store/StoreEntryEvent.java"
click node_store_entry_listener "https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/event/store/listener/StoreEntryListener.java"
click node_store_service "https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/service/StoreService.java"
click node_store_loader "https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/service/StoreLoaderService.java"
click node_store_data "https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/resources/stores.json"
click node_location_repo "https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/repository/CourierLocationRepository.java"
click node_courier_repo "https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/repository/CourierRepository.java"
click node_entry_repo "https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/repository/StoreEntryRepository.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_courier_controller,node_store_controller,node_courier_service,node_store_service,node_client toneBlue
class node_tracking_service,node_location_event,node_distance_listener,node_distance_strategy toneAmber
class node_proximity_listener,node_store_proximity,node_store_entry_event,node_store_entry_listener,node_store_loader,node_store_data toneMint
class node_location_repo,node_courier_repo,node_entry_repo,node_postgres,node_redis toneRose
```

## Components

### API and Queries

- [Courier API](https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/controller/CourierController.java): `src/main/java/com/furkanasikdev/courier/tracking/controller/CourierController.java`
- [Store API](https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/controller/StoreController.java): `src/main/java/com/furkanasikdev/courier/tracking/controller/StoreController.java`
- [Courier Service](https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/service/CourierService.java): `src/main/java/com/furkanasikdev/courier/tracking/service/CourierService.java`
- [Store Service](https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/service/StoreService.java): `src/main/java/com/furkanasikdev/courier/tracking/service/StoreService.java`

### Location Processing

- [Tracking Service](https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/service/TrackingService.java): `src/main/java/com/furkanasikdev/courier/tracking/service/TrackingService.java`
- [Location Event](https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/event/location/LocationReceivedEvent.java): `src/main/java/com/furkanasikdev/courier/tracking/event/location/LocationReceivedEvent.java`
- [Distance Listener](https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/event/location/listener/LocationDistanceListener.java): `src/main/java/com/furkanasikdev/courier/tracking/event/location/listener/LocationDistanceListener.java`
- [Distance Strategies](https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/calculation/distance/DistanceCalculationStrategy.java): `src/main/java/com/furkanasikdev/courier/tracking/calculation/distance/DistanceCalculationStrategy.java`

### Store Proximity

- [Proximity Listener](https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/event/location/listener/LocationProximityListener.java): `src/main/java/com/furkanasikdev/courier/tracking/event/location/listener/LocationProximityListener.java`
- [Proximity Service](https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/service/StoreProximityService.java): `src/main/java/com/furkanasikdev/courier/tracking/service/StoreProximityService.java`
- [Entry Event](https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/event/store/StoreEntryEvent.java): `src/main/java/com/furkanasikdev/courier/tracking/event/store/StoreEntryEvent.java`
- [Entry Listener](https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/event/store/listener/StoreEntryListener.java): `src/main/java/com/furkanasikdev/courier/tracking/event/store/listener/StoreEntryListener.java`
- [Store Loader](https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/service/StoreLoaderService.java): `src/main/java/com/furkanasikdev/courier/tracking/service/StoreLoaderService.java`
- [Store Dataset](https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/resources/stores.json): `src/main/resources/stores.json`

### Persistence and Indexing

- [Location Repository](https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/repository/CourierLocationRepository.java): `src/main/java/com/furkanasikdev/courier/tracking/repository/CourierLocationRepository.java`
- [Courier Repository](https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/repository/CourierRepository.java): `src/main/java/com/furkanasikdev/courier/tracking/repository/CourierRepository.java`
- [Entry Repository](https://github.com/furkaanasik/courier-tracking-system/blob/master/src/main/java/com/furkanasikdev/courier/tracking/repository/StoreEntryRepository.java): `src/main/java/com/furkanasikdev/courier/tracking/repository/StoreEntryRepository.java`
- **PostgreSQL**
- **Redis**

### Other components

- **API Client**

## Connections

- API Client → Courier API: submits locations
- API Client → Store API: requests entries
- Courier API → Tracking Service: processes locations
- Courier API → Courier Service: queries courier
- Courier API → Store Service: queries entries
- Store API → Store Service: queries entries
- Tracking Service → Courier Service: creates courier
- Tracking Service → Location Repository: saves location
- Tracking Service → Location Event: publishes event
- Location Event → Distance Listener: dispatches
- Location Event → Proximity Listener: dispatches
- Distance Listener → Distance Strategies: calculates distance
- Distance Listener → Courier Service: adds distance
- Proximity Listener → Proximity Service: checks nearby stores
- Proximity Service → Redis: searches and checks cooldown
- Proximity Listener → Entry Event: publishes entry
- Entry Event → Entry Listener: dispatches
- Entry Listener → Entry Repository: saves entry
- Courier Service → Courier Repository: reads and saves courier
- Courier Service → Location Repository: reads history
- Store Service → Entry Repository: reads entries
- Location Repository → PostgreSQL: persists locations
- Courier Repository → PostgreSQL: persists couriers
- Entry Repository → PostgreSQL: persists entries
- Store Loader → Store Dataset: reads stores
- Store Loader → Redis: indexes stores