# kenzweb/payment-microservices-system architecture

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

- Interactive diagram: https://gitdiagram.com/kenzweb/payment-microservices-system
- Repository: https://github.com/kenzweb/payment-microservices-system

## Overview

This is a Go microservices system for authentication, inventory-backed order creation, and asynchronous payment and notification processing. The principal workflow starts with a client calling the HTTP gateway: login requests reach the auth service, while order requests are forwarded to the order service, which coordinates inventory and persists orders. Order events are published through a transactional outbox for payment and notification consumers; payment processing can publish status events. The README documents these broader capabilities, while sampled source chiefly confirms service wiring and gateway authentication. Paths for unsampled subsystems use existing directories.

Main entry points: [`services/gateway/cmd/main.go`](https://github.com/kenzweb/payment-microservices-system/blob/main/services/gateway/cmd/main.go) (HTTP gateway), [`services/order/internal/service/order.go`](https://github.com/kenzweb/payment-microservices-system/blob/main/services/order/internal/service/order.go) (Order service), [`services/order/internal/repository/postgres.go`](https://github.com/kenzweb/payment-microservices-system/blob/main/services/order/internal/repository/postgres.go) (Order repository), [`services/payment/internal/worker/payment.go`](https://github.com/kenzweb/payment-microservices-system/blob/main/services/payment/internal/worker/payment.go) (Payment worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["API edge"]
  node_gateway["HTTP gateway<br/>[main.go]"]
  node_auth_handler["Auth handler<br/>[auth.go]"]
  node_order_handler["Order handler<br/>[order.go]"]
  node_auth_client["Auth gRPC client<br/>[auth.go]"]
  node_order_client["Order gRPC client<br/>[order.go]"]
end

subgraph group_core["Order services"]
  node_auth_service["Auth service<br/>[grpc.go]"]
  node_jwt["JWT service<br/>[jwt.go]"]
  node_order_service["Order service<br/>[order.go]"]
  node_order_grpc["Order gRPC handler<br/>[grpc.go]"]
  node_inventory_client["Inventory gRPC client<br/>[inventory.go]"]
  node_inventory_handler["Inventory handler<br/>[grpc.go]"]
  node_order_repo["Order repository<br/>[postgres.go]"]
  node_inventory_repo["Inventory repository<br/>[postgres.go]"]
end

subgraph group_async["Event processing"]
  node_outbox_relay["Outbox relay<br/>[relay.go]"]
  node_payment_worker["Payment worker<br/>[payment.go]"]
  node_payment_repo["Payment repository<br/>[postgres.go]"]
  node_notification_worker["Notification worker<br/>[notification.go]"]
end

subgraph group_infra["Shared infrastructure"]
  node_kafka["Kafka bus"]
  node_kafka_producer["Kafka producer<br/>[producer.go]"]
  node_kafka_consumer["Kafka consumer<br/>[consumer.go]"]
  node_postgres[("PostgreSQL")]
  node_redis[("Redis")]
end

node_client(("Client"))

node_client -->|"HTTP requests"| node_gateway
node_gateway -->|"routes login"| node_auth_handler
node_gateway -->|"routes orders"| node_order_handler
node_auth_handler -->|"requests token"| node_auth_client
node_auth_client -->|"gRPC"| node_auth_service
node_auth_service -->|"generates token"| node_jwt
node_order_handler -->|"forwards order"| node_order_client
node_order_client -->|"gRPC"| node_order_grpc
node_order_grpc -->|"handles request"| node_order_service
node_order_service -->|"checks inventory"| node_inventory_client
node_inventory_client -->|"gRPC"| node_inventory_handler
node_inventory_handler -->|"accesses stock"| node_inventory_repo
node_order_service -->|"stores order"| node_order_repo
node_order_repo -->|"reads and writes"| node_postgres
node_inventory_repo -->|"reads and writes"| node_postgres
node_order_repo -->|"outbox records"| node_outbox_relay
node_outbox_relay -->|"publishes events"| node_kafka_producer
node_kafka_producer -->|"produces"| node_kafka
node_kafka -->|"dispatches events"| node_kafka_consumer
node_kafka_consumer -->|"order events"| node_payment_worker
node_payment_worker -->|"processes payment"| node_payment_repo
node_payment_repo -->|"reads and writes"| node_postgres
node_payment_repo -.->|"idempotency state"| node_redis
node_payment_worker -->|"publishes status"| node_kafka_producer
node_kafka_consumer -->|"order and payment events"| node_notification_worker

click node_gateway "https://github.com/kenzweb/payment-microservices-system/blob/main/services/gateway/cmd/main.go"
click node_auth_handler "https://github.com/kenzweb/payment-microservices-system/blob/main/services/gateway/internal/handler/auth.go"
click node_order_handler "https://github.com/kenzweb/payment-microservices-system/blob/main/services/gateway/internal/handler/order.go"
click node_auth_client "https://github.com/kenzweb/payment-microservices-system/blob/main/services/gateway/internal/client/auth.go"
click node_order_client "https://github.com/kenzweb/payment-microservices-system/blob/main/services/gateway/internal/client/order.go"
click node_auth_service "https://github.com/kenzweb/payment-microservices-system/blob/main/services/auth/internal/handler/grpc.go"
click node_jwt "https://github.com/kenzweb/payment-microservices-system/blob/main/services/auth/internal/service/jwt.go"
click node_order_service "https://github.com/kenzweb/payment-microservices-system/blob/main/services/order/internal/service/order.go"
click node_order_grpc "https://github.com/kenzweb/payment-microservices-system/blob/main/services/order/internal/handler/grpc.go"
click node_inventory_client "https://github.com/kenzweb/payment-microservices-system/blob/main/services/order/internal/client/inventory.go"
click node_inventory_handler "https://github.com/kenzweb/payment-microservices-system/blob/main/services/inventory/internal/handler/grpc.go"
click node_order_repo "https://github.com/kenzweb/payment-microservices-system/blob/main/services/order/internal/repository/postgres.go"
click node_inventory_repo "https://github.com/kenzweb/payment-microservices-system/blob/main/services/inventory/internal/repository/postgres.go"
click node_outbox_relay "https://github.com/kenzweb/payment-microservices-system/blob/main/services/order/internal/worker/relay.go"
click node_payment_worker "https://github.com/kenzweb/payment-microservices-system/blob/main/services/payment/internal/worker/payment.go"
click node_payment_repo "https://github.com/kenzweb/payment-microservices-system/blob/main/services/payment/internal/repository/postgres.go"
click node_notification_worker "https://github.com/kenzweb/payment-microservices-system/blob/main/services/notification/internal/worker/notification.go"
click node_kafka_producer "https://github.com/kenzweb/payment-microservices-system/blob/main/pkg/kafka/producer.go"
click node_kafka_consumer "https://github.com/kenzweb/payment-microservices-system/blob/main/pkg/kafka/consumer.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_gateway,node_auth_handler,node_order_handler,node_auth_client,node_order_client,node_client toneBlue
class node_auth_service,node_jwt,node_order_service,node_order_grpc,node_inventory_client,node_inventory_handler,node_order_repo,node_inventory_repo toneAmber
class node_outbox_relay,node_payment_worker,node_payment_repo,node_notification_worker toneMint
class node_kafka,node_kafka_producer,node_kafka_consumer,node_postgres,node_redis toneRose
```

## Components

### API edge

- [HTTP gateway](https://github.com/kenzweb/payment-microservices-system/blob/main/services/gateway/cmd/main.go): `services/gateway/cmd/main.go`
- [Auth handler](https://github.com/kenzweb/payment-microservices-system/blob/main/services/gateway/internal/handler/auth.go): `services/gateway/internal/handler/auth.go`
- [Order handler](https://github.com/kenzweb/payment-microservices-system/blob/main/services/gateway/internal/handler/order.go): `services/gateway/internal/handler/order.go`
- [Auth gRPC client](https://github.com/kenzweb/payment-microservices-system/blob/main/services/gateway/internal/client/auth.go): `services/gateway/internal/client/auth.go`
- [Order gRPC client](https://github.com/kenzweb/payment-microservices-system/blob/main/services/gateway/internal/client/order.go): `services/gateway/internal/client/order.go`

### Order services

- [Auth service](https://github.com/kenzweb/payment-microservices-system/blob/main/services/auth/internal/handler/grpc.go): `services/auth/internal/handler/grpc.go`
- [JWT service](https://github.com/kenzweb/payment-microservices-system/blob/main/services/auth/internal/service/jwt.go): `services/auth/internal/service/jwt.go`
- [Order service](https://github.com/kenzweb/payment-microservices-system/blob/main/services/order/internal/service/order.go): `services/order/internal/service/order.go`
- [Order gRPC handler](https://github.com/kenzweb/payment-microservices-system/blob/main/services/order/internal/handler/grpc.go): `services/order/internal/handler/grpc.go`
- [Inventory gRPC client](https://github.com/kenzweb/payment-microservices-system/blob/main/services/order/internal/client/inventory.go): `services/order/internal/client/inventory.go`
- [Inventory handler](https://github.com/kenzweb/payment-microservices-system/blob/main/services/inventory/internal/handler/grpc.go): `services/inventory/internal/handler/grpc.go`
- [Order repository](https://github.com/kenzweb/payment-microservices-system/blob/main/services/order/internal/repository/postgres.go): `services/order/internal/repository/postgres.go`
- [Inventory repository](https://github.com/kenzweb/payment-microservices-system/blob/main/services/inventory/internal/repository/postgres.go): `services/inventory/internal/repository/postgres.go`

### Event processing

- [Outbox relay](https://github.com/kenzweb/payment-microservices-system/blob/main/services/order/internal/worker/relay.go): `services/order/internal/worker/relay.go`
- [Payment worker](https://github.com/kenzweb/payment-microservices-system/blob/main/services/payment/internal/worker/payment.go): `services/payment/internal/worker/payment.go`
- [Payment repository](https://github.com/kenzweb/payment-microservices-system/blob/main/services/payment/internal/repository/postgres.go): `services/payment/internal/repository/postgres.go`
- [Notification worker](https://github.com/kenzweb/payment-microservices-system/blob/main/services/notification/internal/worker/notification.go): `services/notification/internal/worker/notification.go`

### Shared infrastructure

- **Kafka bus**
- [Kafka producer](https://github.com/kenzweb/payment-microservices-system/blob/main/pkg/kafka/producer.go): `pkg/kafka/producer.go`
- [Kafka consumer](https://github.com/kenzweb/payment-microservices-system/blob/main/pkg/kafka/consumer.go): `pkg/kafka/consumer.go`
- **PostgreSQL**
- **Redis**

### Other components

- **Client**

## Connections

- Client → HTTP gateway: HTTP requests
- HTTP gateway → Auth handler: routes login
- HTTP gateway → Order handler: routes orders
- Auth handler → Auth gRPC client: requests token
- Auth gRPC client → Auth service: gRPC
- Auth service → JWT service: generates token
- Order handler → Order gRPC client: forwards order
- Order gRPC client → Order gRPC handler: gRPC
- Order gRPC handler → Order service: handles request
- Order service → Inventory gRPC client: checks inventory
- Inventory gRPC client → Inventory handler: gRPC
- Inventory handler → Inventory repository: accesses stock
- Order service → Order repository: stores order
- Order repository → PostgreSQL: reads and writes
- Inventory repository → PostgreSQL: reads and writes
- Order repository → Outbox relay: outbox records
- Outbox relay → Kafka producer: publishes events
- Kafka producer → Kafka bus: produces
- Kafka bus → Kafka consumer: dispatches events
- Kafka consumer → Payment worker: order events
- Payment worker → Payment repository: processes payment
- Payment repository → PostgreSQL: reads and writes
- Payment repository → Redis: idempotency state
- Payment worker → Kafka producer: publishes status
- Kafka consumer → Notification worker: order and payment events