# saveliy12/microservices2 architecture

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

- Interactive diagram: https://gitdiagram.com/saveliy12/microservices2
- Repository: https://github.com/saveliy12/microservices2

## Overview

#### Purpose and topology
This Go workspace implements an order-processing microservice system: **inventory**, **order**, and **payment** services. Each service is independently buildable/containerized, while `shared` owns inter-service API contracts and generated bindings. Deployment is organized as service-specific Docker Compose stacks.

#### Service entry points
Each service starts from its own Go command and Docker image:
- Inventory: `inventory/cmd/main.go`, `inventory/Dockerfile`
- Order: `order/cmd/main.go`, `order/Dockerfile`
- Payment: `payment/cmd/main.go`, `payment/Dockerfile`

The root `go.work` ties the service and shared modules into one local workspace. Compose definitions reside in `deploy/compose/core/docker-compose.yml` and per-service directories.

#### Contract boundary and transport
`shared` is the API-contract module. Inventory and payment expose protobuf/gRPC contracts defined under `shared/proto/inventory/v1/inventory.proto` and `shared/proto/payment/v1/payment.proto`, with checked-in generated clients/server bindings in `shared/pkg/proto/...`.

Order exposes an OpenAPI-described HTTP API: `shared/api/order/v1/order.openapi.yaml`, with generated server/client/router code in `shared/pkg/openapi/order/v1/`. Its API handlers are implemented in `order/internal/api/order/v1/`.

#### Inventory service
Inventory follows a layered request path: gRPC/API adapter → service → repository → Mongo-oriented database adapter. API operations are implemented in `inventory/internal/api/inventory/v1/get.go` and `inventory/internal/api/inventory/v1/list.go`; business operations live in `inventory/internal/service/part/`; persistence is in `inventory/internal/repository/part/`.

The database boundary is abstracted by collection interfaces in `inventory/internal/client/db/collection.go`, with Mongo implementation under `inventory/internal/client/db/mongo/`. Repository seeding is part of the inventory persistence component (`inventory/internal/repository/part/seed.go`).

#### Order orchestration and persistence
Order is the workflow-owning service. Its actions cover create, retrieve, pay, and cancel through `order/internal/api/order/v1/`, with orchestration and state transitions in `order/internal/service/order/`.

Order persists orders through repository abstractions and a PostgreSQL client: `order/internal/repository/order/`, `order/internal/client/db/pg/client.go`. Schema initialization is managed through `order/internal/migrator/migrator.go` and `order/migrations/20260805000001_init_orders.sql`.

#### Cross-service order flow
Order creation/payment logic calls inventory and payment through explicit outbound client adapters: `order/internal/clients/inventory/inventory.go` and `order/internal/clients/payment/payment.go`. These adapters isolate generated RPC/client protocol details from the order service layer.

The expected primary flow is: HTTP order request → API action handler → order service → PostgreSQL repository; payment-related actions additionally invoke inventory/payment clients before updating order state. Cancellation, payment, and creation are separate service commands, enabling their own validation and external-call sequencing.

#### Payment service
Payment is a focused gRPC service with API-to-service layering: `payment/internal/api/payment/v1/pay.go` delegates to `payment/internal/service/payment/pay.go`. It has no repository or database implementation in this tree, so payment processing is currently modeled as service-layer behavior rather than durable local persistence.

#### Runtime and infrastructure
Services run as Go binaries in Docker. Inventory’s persistence integration is MongoDB-oriented; Order’s is PostgreSQL-oriented. The order service is the only service with explicit synchronous dependencies on the other two. Service topology and backing dependencies are provisioned through `deploy/compose/inventory/docker-compose.yml`, `deploy/compose/order/docker-compose.yml`, and `deploy/compose/payment/docker-compose.yml`.

Main entry points: [`inventory/internal/api/inventory/v1/get.go`](https://github.com/saveliy12/microservices2/blob/main/inventory/internal/api/inventory/v1/get.go) (Inventory gRPC API), [`payment/internal/api/payment/v1/pay.go`](https://github.com/saveliy12/microservices2/blob/main/payment/internal/api/payment/v1/pay.go) (Payment gRPC API), [`deploy/compose/core/docker-compose.yml`](https://github.com/saveliy12/microservices2/blob/main/deploy/compose/core/docker-compose.yml) (Service Compose stacks), [`inventory/cmd/main.go`](https://github.com/saveliy12/microservices2/blob/main/inventory/cmd/main.go) (Inventory binary)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shared["Shared contracts"]
  node_inventory_contract["Inventory protobuf<br/>gRPC contract<br/>[inventory.proto]"]
  node_payment_contract["Payment protobuf<br/>gRPC contract<br/>[payment.proto]"]
  node_order_contract["Order OpenAPI<br/>HTTP contract<br/>[order.openapi.yaml]"]
end

subgraph group_inventory["Inventory service"]
  node_inventory_cmd["Inventory binary<br/>Go command<br/>[main.go]"]
  node_inventory_api["Inventory gRPC API<br/>API adapter<br/>[get.go]"]
  node_inventory_service["Part service<br/>business service"]
  node_inventory_repository["Part repository"]
  node_inventory_db[("Mongo DB adapter<br/>database client<br/>[collection.go]")]
end

subgraph group_order["Order service"]
  node_order_cmd["Order binary<br/>Go command<br/>[main.go]"]
  node_order_api["Order HTTP API<br/>OpenAPI handlers"]
  node_order_service["Order service<br/>workflow service"]
  node_order_repository["Order repository"]
  node_order_pg[("PostgreSQL client<br/>database client<br/>[client.go]")]
  node_order_migrator["Order schema migrator<br/>migration runner<br/>[migrator.go]"]
  node_inventory_client["Inventory client<br/>outbound adapter<br/>[inventory.go]"]
  node_payment_client["Payment client<br/>outbound adapter<br/>[payment.go]"]
end

subgraph group_payment["Payment service"]
  node_payment_cmd["Payment binary<br/>Go command<br/>[main.go]"]
  node_payment_api["Payment gRPC API<br/>API adapter<br/>[pay.go]"]
  node_payment_service["Payment service<br/>business service<br/>[pay.go]"]
end

subgraph group_runtime["Deployment"]
  node_compose{{"Service Compose stacks<br/>deployment topology<br/>[docker-compose.yml]"}}
end

node_inventory_cmd -->|"serves"| node_inventory_api
node_inventory_api -->|"delegates"| node_inventory_service
node_inventory_service -->|"uses"| node_inventory_repository
node_inventory_repository -->|"persists via"| node_inventory_db
node_inventory_api -->|"implements"| node_inventory_contract
node_order_cmd -->|"serves"| node_order_api
node_order_api -->|"delegates"| node_order_service
node_order_api -->|"implements"| node_order_contract
node_order_service -->|"persists orders"| node_order_repository
node_order_repository -->|"uses"| node_order_pg
node_order_migrator -->|"initializes schema"| node_order_pg
node_order_service -->|"reserves/checks inventory"| node_inventory_client
node_inventory_client -->|"gRPC"| node_inventory_api
node_order_service -->|"processes payment"| node_payment_client
node_payment_client -->|"gRPC"| node_payment_api
node_payment_cmd -->|"serves"| node_payment_api
node_payment_api -->|"delegates"| node_payment_service
node_payment_api -->|"implements"| node_payment_contract
node_compose -.->|"runs"| node_inventory_cmd
node_compose -.->|"runs"| node_order_cmd
node_compose -.->|"runs"| node_payment_cmd

click node_inventory_cmd "https://github.com/saveliy12/microservices2/blob/main/inventory/cmd/main.go"
click node_inventory_api "https://github.com/saveliy12/microservices2/blob/main/inventory/internal/api/inventory/v1/get.go"
click node_inventory_db "https://github.com/saveliy12/microservices2/blob/main/inventory/internal/client/db/collection.go"
click node_order_cmd "https://github.com/saveliy12/microservices2/blob/main/order/cmd/main.go"
click node_order_pg "https://github.com/saveliy12/microservices2/blob/main/order/internal/client/db/pg/client.go"
click node_order_migrator "https://github.com/saveliy12/microservices2/blob/main/order/internal/migrator/migrator.go"
click node_inventory_client "https://github.com/saveliy12/microservices2/blob/main/order/internal/clients/inventory/inventory.go"
click node_payment_client "https://github.com/saveliy12/microservices2/blob/main/order/internal/clients/payment/payment.go"
click node_payment_cmd "https://github.com/saveliy12/microservices2/blob/main/payment/cmd/main.go"
click node_payment_api "https://github.com/saveliy12/microservices2/blob/main/payment/internal/api/payment/v1/pay.go"
click node_payment_service "https://github.com/saveliy12/microservices2/blob/main/payment/internal/service/payment/pay.go"
click node_inventory_contract "https://github.com/saveliy12/microservices2/blob/main/shared/proto/inventory/v1/inventory.proto"
click node_payment_contract "https://github.com/saveliy12/microservices2/blob/main/shared/proto/payment/v1/payment.proto"
click node_order_contract "https://github.com/saveliy12/microservices2/blob/main/shared/api/order/v1/order.openapi.yaml"
click node_compose "https://github.com/saveliy12/microservices2/blob/main/deploy/compose/core/docker-compose.yml"

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_inventory_contract,node_payment_contract,node_order_contract toneBlue
class node_inventory_cmd,node_inventory_api,node_inventory_service,node_inventory_repository,node_inventory_db toneAmber
class node_order_cmd,node_order_api,node_order_service,node_order_repository,node_order_pg,node_order_migrator,node_inventory_client,node_payment_client toneMint
class node_payment_cmd,node_payment_api,node_payment_service toneRose
class node_compose toneIndigo
```

## Components

### Shared contracts

Versioned API definitions and generated bindings.

- [Inventory protobuf](https://github.com/saveliy12/microservices2/blob/main/shared/proto/inventory/v1/inventory.proto): gRPC contract · Generated bindings are owned by shared. · `shared/proto/inventory/v1/inventory.proto`
- [Payment protobuf](https://github.com/saveliy12/microservices2/blob/main/shared/proto/payment/v1/payment.proto): gRPC contract · Generated bindings are owned by shared. · `shared/proto/payment/v1/payment.proto`
- [Order OpenAPI](https://github.com/saveliy12/microservices2/blob/main/shared/api/order/v1/order.openapi.yaml): HTTP contract · Generated server, client, and router bindings are owned by shared. · `shared/api/order/v1/order.openapi.yaml`

### Inventory service

- [Inventory binary](https://github.com/saveliy12/microservices2/blob/main/inventory/cmd/main.go): Go command · `inventory/cmd/main.go`
- [Inventory gRPC API](https://github.com/saveliy12/microservices2/blob/main/inventory/internal/api/inventory/v1/get.go): API adapter · `inventory/internal/api/inventory/v1/get.go`
- **Part service**: business service
- **Part repository**: repository · Includes inventory seed data.
- [Mongo DB adapter](https://github.com/saveliy12/microservices2/blob/main/inventory/internal/client/db/collection.go): database client · Collection interfaces isolate the Mongo implementation. · `inventory/internal/client/db/collection.go`

### Order service

Owns order workflow and state transitions.

- [Order binary](https://github.com/saveliy12/microservices2/blob/main/order/cmd/main.go): Go command · `order/cmd/main.go`
- **Order HTTP API**: OpenAPI handlers
- **Order service**: workflow service · Handles create, retrieve, pay, and cancel commands.
- **Order repository**: repository
- [PostgreSQL client](https://github.com/saveliy12/microservices2/blob/main/order/internal/client/db/pg/client.go): database client · `order/internal/client/db/pg/client.go`
- [Order schema migrator](https://github.com/saveliy12/microservices2/blob/main/order/internal/migrator/migrator.go): migration runner · `order/internal/migrator/migrator.go`
- [Inventory client](https://github.com/saveliy12/microservices2/blob/main/order/internal/clients/inventory/inventory.go): outbound adapter · `order/internal/clients/inventory/inventory.go`
- [Payment client](https://github.com/saveliy12/microservices2/blob/main/order/internal/clients/payment/payment.go): outbound adapter · `order/internal/clients/payment/payment.go`

### Payment service

- [Payment binary](https://github.com/saveliy12/microservices2/blob/main/payment/cmd/main.go): Go command · `payment/cmd/main.go`
- [Payment gRPC API](https://github.com/saveliy12/microservices2/blob/main/payment/internal/api/payment/v1/pay.go): API adapter · `payment/internal/api/payment/v1/pay.go`
- [Payment service](https://github.com/saveliy12/microservices2/blob/main/payment/internal/service/payment/pay.go): business service · Payment processing has no local durable persistence. · `payment/internal/service/payment/pay.go`

### Deployment

- [Service Compose stacks](https://github.com/saveliy12/microservices2/blob/main/deploy/compose/core/docker-compose.yml): deployment topology · Provisions services and backing dependencies. · `deploy/compose/core/docker-compose.yml`

## Connections

- Inventory binary → Inventory gRPC API: serves
- Inventory gRPC API → Part service: delegates
- Part service → Part repository: uses
- Part repository → Mongo DB adapter: persists via
- Inventory gRPC API → Inventory protobuf: implements
- Order binary → Order HTTP API: serves
- Order HTTP API → Order service: delegates
- Order HTTP API → Order OpenAPI: implements
- Order service → Order repository: persists orders
- Order repository → PostgreSQL client: uses
- Order schema migrator → PostgreSQL client: initializes schema
- Order service → Inventory client: reserves/checks inventory
- Inventory client → Inventory gRPC API: gRPC
- Order service → Payment client: processes payment
- Payment client → Payment gRPC API: gRPC
- Payment binary → Payment gRPC API: serves
- Payment gRPC API → Payment service: delegates
- Payment gRPC API → Payment protobuf: implements
- Service Compose stacks → Inventory binary: runs
- Service Compose stacks → Order binary: runs
- Service Compose stacks → Payment binary: runs