Architecture

Overview

Mini-Vending is a Go gRPC microservice monorepo. Each service is a standalone Go module following Clean Architecture.

Repository layout

go-services/
├── <service>/          # Domain services (accounts, vendings, ...)
├── packages/           # Shared Go packages
├── proto/              # Protobuf source files
├── gen/                # Auto-generated Go code from protos
├── googleapis/         # Google API protos (git submodule)
├── docs/               # This documentation portal
└── .github/            # CI/CD workflows

Clean Architecture layers

Every service follows the same internal structure:

graph TD
    A[endpoints/grpc] -->|calls| B[domain/use_cases]
    B -->|depends on| C[domain/interfaces]
    D[infrastructure/repositories] -->|implements| C
    E[infrastructure/external] -->|implements| C
    F[transport/grpc_server] -->|wires| A
    F -->|wires| D
    F -->|wires| E

Layer	Path	Responsibility
Transport	internal/transport/grpc_server/	Server bootstrap, interceptor chain
Endpoints	internal/endpoints/grpc/	Map gRPC requests to use case calls
Domain	internal/domain/use_cases/	Business logic
Domain interfaces	internal/domain/interfaces/	Contracts between layers
Infrastructure	internal/infrastructure/repositories/	Database implementations
External	internal/infrastructure/external/	Clients for other services

Dependency rule: outer layers depend on inner layers, never the reverse. Domain must not import infrastructure or transport.

Module structure

No root go.mod. Each service and package has its own module, linked by:

1. go.work at the repo root
2. replace directives in each service's go.mod

Tech stack

Concern	Tool
Language	Go 1.24
Transport	gRPC + google.api.http REST annotations
Protobuf	protoc + protoc-gen-go / protoc-gen-go-grpc
Database	PostgreSQL (sqlx + pgx)
Migrations	golang-migrate
Auth	JWT via gRPC interceptor
Permissions	Role-based gRPC interceptor
Logging	Logrus JSON structured logger
Linting	golangci-lint
Containers	Docker, docker-compose
CI/CD	GitHub Actions → GHCR → VPS