# timurgondin/service-courier architecture

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

- Interactive diagram: https://gitdiagram.com/timurgondin/service-courier
- Repository: https://github.com/timurgondin/service-courier

## Overview

Courier Service manages courier records and delivery assignments through HTTP, while background workers poll the external order service and release expired assignments. A separate Kafka worker processes order-status changes. The main service wires handlers, business services, PostgreSQL repositories, and the gRPC gateway; the README documents these layer relationships and the product capabilities. Some subsystem internals were not sampled, so their links are included only where documented.

Main entry points: [`cmd/service/main.go`](https://github.com/timurgondin/service-courier/blob/main/cmd/service/main.go) (HTTP service), [`internal/service/delivery/assign.go`](https://github.com/timurgondin/service-courier/blob/main/internal/service/delivery/assign.go) (Delivery operations), [`internal/service/courier/courier.go`](https://github.com/timurgondin/service-courier/blob/main/internal/service/courier/courier.go) (Courier use cases), [`cmd/worker/main.go`](https://github.com/timurgondin/service-courier/blob/main/cmd/worker/main.go) (Kafka worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Service entrypoints"]
  node_service_main["HTTP service<br/>[main.go]"]
  node_worker_main["Kafka worker<br/>[main.go]"]
end

subgraph group_api["HTTP and events"]
  node_courier_http["Courier API<br/>[courier.go]"]
  node_delivery_http["Delivery API<br/>[delivery.go]"]
  node_order_event_handler["Order event handler<br/>[handler.go]"]
  node_common_http["Health endpoints<br/>[ping.go]"]
end

subgraph group_domain["Business domain"]
  node_courier_service["Courier use cases<br/>[courier.go]"]
  node_delivery_service["Delivery operations<br/>[assign.go]"]
  node_order_changed["Order status use case<br/>[changed.go]"]
  node_release_worker["Expiry worker<br/>[worker.go]"]
  node_order_worker["Order polling worker<br/>[order_worker.go]"]
  node_courier_model["Courier model<br/>[courier.go]"]
  node_delivery_model["Delivery model<br/>[delivery.go]"]
end

subgraph group_infra["Persistence and integrations"]
  node_courier_repo["Courier repository<br/>[courier.go]"]
  node_delivery_repo["Delivery repository<br/>[delivery.go]"]
  node_order_gateway["Order gRPC gateway<br/>[client.go]"]
  node_metrics["HTTP metrics<br/>[metrics.go]"]
  node_rate_limit["Rate limiting<br/>[middleware.go]"]
end

node_http_user(("HTTP client"))
node_kafka["Kafka"]
node_orders["Order Service"]
node_postgres[("PostgreSQL")]
node_prometheus["Prometheus"]

node_http_user -->|"sends HTTP"| node_service_main
node_service_main -->|"routes requests"| node_courier_http
node_service_main -->|"routes requests"| node_delivery_http
node_service_main -->|"routes health"| node_common_http
node_service_main -->|"constructs"| node_courier_service
node_service_main -->|"constructs"| node_delivery_service
node_service_main -->|"constructs"| node_courier_repo
node_service_main -->|"constructs"| node_delivery_repo
node_service_main -->|"constructs client"| node_order_gateway
node_service_main -->|"starts"| node_release_worker
node_service_main -->|"starts"| node_order_worker
node_service_main -->|"installs middleware"| node_rate_limit
node_service_main -->|"installs middleware"| node_metrics
node_courier_http -->|"invokes"| node_courier_service
node_delivery_http -->|"invokes"| node_delivery_service
node_courier_service -->|"uses repository"| node_courier_repo
node_delivery_service -->|"uses repository"| node_delivery_repo
node_courier_repo -->|"queries"| node_postgres
node_delivery_repo -->|"queries"| node_postgres
node_courier_service -.->|"uses model"| node_courier_model
node_delivery_service -.->|"uses model"| node_delivery_model
node_order_worker -->|"polls orders"| node_order_gateway
node_order_worker -->|"assigns couriers"| node_delivery_service
node_order_gateway -->|"calls gRPC"| node_orders
node_release_worker -->|"releases expired"| node_delivery_service
node_kafka -->|"delivers events"| node_worker_main
node_worker_main -->|"registers consumer"| node_order_event_handler
node_order_event_handler -->|"processes status"| node_order_changed
node_order_changed -.->|"updates delivery"| node_delivery_service
node_worker_main -->|"constructs"| node_delivery_service
node_prometheus -->|"scrapes metrics"| node_service_main

click node_service_main "https://github.com/timurgondin/service-courier/blob/main/cmd/service/main.go"
click node_worker_main "https://github.com/timurgondin/service-courier/blob/main/cmd/worker/main.go"
click node_courier_http "https://github.com/timurgondin/service-courier/blob/main/internal/handler/courier/courier.go"
click node_delivery_http "https://github.com/timurgondin/service-courier/blob/main/internal/handler/delivery/delivery.go"
click node_order_event_handler "https://github.com/timurgondin/service-courier/blob/main/internal/handler/queues/order/changed/handler.go"
click node_common_http "https://github.com/timurgondin/service-courier/blob/main/internal/handler/common/ping.go"
click node_courier_service "https://github.com/timurgondin/service-courier/blob/main/internal/service/courier/courier.go"
click node_delivery_service "https://github.com/timurgondin/service-courier/blob/main/internal/service/delivery/assign.go"
click node_order_changed "https://github.com/timurgondin/service-courier/blob/main/internal/service/order/changed/changed.go"
click node_release_worker "https://github.com/timurgondin/service-courier/blob/main/internal/service/delivery/worker.go"
click node_order_worker "https://github.com/timurgondin/service-courier/blob/main/internal/service/delivery/order_worker.go"
click node_courier_model "https://github.com/timurgondin/service-courier/blob/main/internal/model/courier/courier.go"
click node_delivery_model "https://github.com/timurgondin/service-courier/blob/main/internal/model/delivery/delivery.go"
click node_courier_repo "https://github.com/timurgondin/service-courier/blob/main/internal/repository/courier/courier.go"
click node_delivery_repo "https://github.com/timurgondin/service-courier/blob/main/internal/repository/delivery/delivery.go"
click node_order_gateway "https://github.com/timurgondin/service-courier/blob/main/internal/gateway/order/client.go"
click node_metrics "https://github.com/timurgondin/service-courier/blob/main/internal/metrics/metrics.go"
click node_rate_limit "https://github.com/timurgondin/service-courier/blob/main/internal/middleware/middleware.go"

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_service_main,node_worker_main,node_http_user toneBlue
class node_courier_http,node_delivery_http,node_order_event_handler,node_common_http,node_postgres toneAmber
class node_courier_service,node_delivery_service,node_order_changed,node_release_worker,node_order_worker,node_courier_model,node_delivery_model toneMint
class node_courier_repo,node_delivery_repo,node_order_gateway,node_metrics,node_rate_limit toneRose
class node_kafka,node_orders,node_prometheus toneIndigo
```

## Components

### Service entrypoints

- [HTTP service](https://github.com/timurgondin/service-courier/blob/main/cmd/service/main.go): `cmd/service/main.go`
- [Kafka worker](https://github.com/timurgondin/service-courier/blob/main/cmd/worker/main.go): `cmd/worker/main.go`

### HTTP and events

- [Courier API](https://github.com/timurgondin/service-courier/blob/main/internal/handler/courier/courier.go): `internal/handler/courier/courier.go`
- [Delivery API](https://github.com/timurgondin/service-courier/blob/main/internal/handler/delivery/delivery.go): `internal/handler/delivery/delivery.go`
- [Order event handler](https://github.com/timurgondin/service-courier/blob/main/internal/handler/queues/order/changed/handler.go): `internal/handler/queues/order/changed/handler.go`
- [Health endpoints](https://github.com/timurgondin/service-courier/blob/main/internal/handler/common/ping.go): `internal/handler/common/ping.go`

### Business domain

- [Courier use cases](https://github.com/timurgondin/service-courier/blob/main/internal/service/courier/courier.go): `internal/service/courier/courier.go`
- [Delivery operations](https://github.com/timurgondin/service-courier/blob/main/internal/service/delivery/assign.go): `internal/service/delivery/assign.go`
- [Order status use case](https://github.com/timurgondin/service-courier/blob/main/internal/service/order/changed/changed.go): `internal/service/order/changed/changed.go`
- [Expiry worker](https://github.com/timurgondin/service-courier/blob/main/internal/service/delivery/worker.go): `internal/service/delivery/worker.go`
- [Order polling worker](https://github.com/timurgondin/service-courier/blob/main/internal/service/delivery/order_worker.go): `internal/service/delivery/order_worker.go`
- [Courier model](https://github.com/timurgondin/service-courier/blob/main/internal/model/courier/courier.go): `internal/model/courier/courier.go`
- [Delivery model](https://github.com/timurgondin/service-courier/blob/main/internal/model/delivery/delivery.go): `internal/model/delivery/delivery.go`

### Persistence and integrations

- [Courier repository](https://github.com/timurgondin/service-courier/blob/main/internal/repository/courier/courier.go): `internal/repository/courier/courier.go`
- [Delivery repository](https://github.com/timurgondin/service-courier/blob/main/internal/repository/delivery/delivery.go): `internal/repository/delivery/delivery.go`
- [Order gRPC gateway](https://github.com/timurgondin/service-courier/blob/main/internal/gateway/order/client.go): `internal/gateway/order/client.go`
- [HTTP metrics](https://github.com/timurgondin/service-courier/blob/main/internal/metrics/metrics.go): `internal/metrics/metrics.go`
- [Rate limiting](https://github.com/timurgondin/service-courier/blob/main/internal/middleware/middleware.go): `internal/middleware/middleware.go`

### Other components

- **HTTP client**
- **Kafka**
- **Order Service**
- **PostgreSQL**
- **Prometheus**

## Connections

- HTTP client → HTTP service: sends HTTP
- HTTP service → Courier API: routes requests (evidence: `cmd/service/main.go`)
- HTTP service → Delivery API: routes requests (evidence: `cmd/service/main.go`)
- HTTP service → Health endpoints: routes health (evidence: `cmd/service/main.go`)
- HTTP service → Courier use cases: constructs (evidence: `cmd/service/main.go`)
- HTTP service → Delivery operations: constructs (evidence: `cmd/service/main.go`)
- HTTP service → Courier repository: constructs (evidence: `cmd/service/main.go`)
- HTTP service → Delivery repository: constructs (evidence: `cmd/service/main.go`)
- HTTP service → Order gRPC gateway: constructs client (evidence: `cmd/service/main.go`)
- HTTP service → Expiry worker: starts (evidence: `cmd/service/main.go`)
- HTTP service → Order polling worker: starts (evidence: `cmd/service/main.go`)
- HTTP service → Rate limiting: installs middleware (evidence: `cmd/service/main.go`)
- HTTP service → HTTP metrics: installs middleware (evidence: `cmd/service/main.go`)
- Courier API → Courier use cases: invokes
- Delivery API → Delivery operations: invokes
- Courier use cases → Courier repository: uses repository
- Delivery operations → Delivery repository: uses repository
- Courier repository → PostgreSQL: queries (evidence: `internal/repository/courier/courier.go`)
- Delivery repository → PostgreSQL: queries
- Courier use cases → Courier model: uses model
- Delivery operations → Delivery model: uses model
- Order polling worker → Order gRPC gateway: polls orders (evidence: `internal/service/delivery/order_worker.go`)
- Order polling worker → Delivery operations: assigns couriers (evidence: `internal/service/delivery/order_worker.go`)
- Order gRPC gateway → Order Service: calls gRPC
- Expiry worker → Delivery operations: releases expired (evidence: `internal/service/delivery/worker.go`)
- Kafka → Kafka worker: delivers events (evidence: `cmd/worker/main.go`)
- Kafka worker → Order event handler: registers consumer (evidence: `cmd/worker/main.go`)
- Order event handler → Order status use case: processes status
- Order status use case → Delivery operations: updates delivery
- Kafka worker → Delivery operations: constructs (evidence: `cmd/worker/main.go`)
- Prometheus → HTTP service: scrapes metrics
