How kratoffq/avito-pvz-test works
Project Type and Purpose
• This is a Go-based backend microservice (“AVITO-PVZ-TEST”) for managing order pickup points (PVZs).
• It exposes both HTTP (REST + OpenAPI) and gRPC APIs, handles authentication/authorization (JWT, roles), persists data in PostgreSQL, and exports Prometheus metrics.
High-Level Architecture
• The service follows a layered/hexagonal (ports and adapters) architecture:
• Entry Points (Adapters): HTTP server, gRPC server
• Application Layer: Handlers → Use Cases / Services
• Domain Layer: Domain models, business rules
• Infrastructure Layer (Adapters): Repositories (Postgres), External libraries (auth, metrics)
• Cross-Cutting: Configuration, Logging, Metrics, Middleware
Main Components
a. API Adapters
• cmd/http/main.go → HTTP server, OpenAPI-generated request/response types
• cmd/grpc/main.go → gRPC server, Proto-generated stubs
• Handlers in internal/handler/http and internal/handler/grpc
b. Application & Business Logic
• internal/usecase/pvz → Use-case DTOs and orchestration
• internal/service/* → Service implementations per aggregate (pvz, reception, product, user)
• internal/domain/* → Core domain models & repository interfaces
c. Persistence / Infrastructure
• internal/repository/postgres → Postgres-specific implementation of repository interfaces
• internal/repository/migration → DB schema migration scripts
d. Cross-cutting Services
• pkg/auth → JWT authentication and role-based middleware
• internal/metrics & internal/middleware → Prometheus metrics collection
e. External Systems
• PostgreSQL database
• Prometheus (scrapes /metrics endpoint)
Relationships & Data Flow
• Client → HTTP/gRPC Endpoint → Handler → Use Case/Service → Repository Interface → Postgres Adapter → Database
• Metrics middleware wraps HTTP/gRPC handlers to record Prometheus metrics
• Auth middleware enforces JWT & roles before handler invocation
• Config loader reads configs, environment variables at startup
• The HTTP and gRPC servers run side by side within the same process (initialized in internal/app)
Architectural Patterns & Principles
• Hexagonal/Clean Architecture: clear separation between domain, application, and infrastructure
• Dependency Inversion: Handlers and services depend on repository interfaces, not concrete DB packages
• Single Responsibility: each package (handler, service, repository) has one clear role
• Layered Organization: cmd/ for bootstrapping, internal/ for core code, pkg/ for shared utilities