# kratoffq/avito-pvz-test architecture

> Architecture diagram of the GitHub repository kratoffq/avito-pvz-test, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kratoffq/avito-pvz-test
- Repository: https://github.com/kratoffq/avito-pvz-test

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Cross-Cutting Layer
    subgraph "Cross-Cutting Services"
        direction TB
        ConfigLoader["Configuration Loader"]:::cross
        AuthMW["Auth Middleware (JWT, Roles)"]:::cross
        MetricsMW["Metrics Middleware"]:::cross
    end

    %% Application Bootstrap
    Bootstrap["Application Bootstrap"]:::cross

    %% Adapters Layer
    subgraph "API Adapters" 
        direction TB
        subgraph "HTTP Server (REST/OpenAPI)" 
            direction TB
            HTTPServer["HTTP Server"]:::adapters
            HTTPHandler["HTTP Handlers"]:::adapters
        end
        subgraph "gRPC Server"
            direction TB
            GRPCServer["gRPC Server"]:::adapters
            GRPCHandler["gRPC Handlers"]:::adapters
        end
    end

    %% Application & Domain
    subgraph "Application & Domain"
        direction TB
        UseCase["Use Case Layer"]:::app
        ServiceLayer["Service Implementations"]:::app
        DomainLayer["Domain Models & Interfaces"]:::app
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        direction TB
        RepoInterface["Repository Interfaces"]:::infra
        PostgresAdapter["Postgres Adapter"]:::infra
        Migrations["DB Migration Scripts"]:::infra
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        DB["PostgreSQL Database"]:::external
        Prometheus["Prometheus"]:::external
    end

    %% Flow Definitions
    ConfigLoader -->|loads config| Bootstrap
    Bootstrap -->|wires| AuthMW
    Bootstrap -->|wires| MetricsMW
    Bootstrap -->|starts| HTTPServer
    Bootstrap -->|starts| GRPCServer

    HTTPServer -->|uses| AuthMW
    HTTPServer -->|wraps with| MetricsMW
    HTTPServer -->|routes to| HTTPHandler
    GRPCServer -->|uses| AuthMW
    GRPCServer -->|wraps with| MetricsMW
    GRPCServer -->|routes to| GRPCHandler

    HTTPHandler -->|calls| UseCase
    GRPCHandler -->|calls| UseCase

    UseCase -->|orchestrates| ServiceLayer
    ServiceLayer -->|depends on| DomainLayer
    DomainLayer -->|defines| RepoInterface
    ServiceLayer -->|calls| RepoInterface

    RepoInterface -->|implemented by| PostgresAdapter
    PostgresAdapter -->|executes| Migrations
    PostgresAdapter -->|reads/writes| DB

    Prometheus -->|scrapes /metrics| MetricsMW

    %% Click Events for component mapping
    click HTTPServer "https://github.com/kratoffq/avito-pvz-test/blob/main/cmd/http/main.go"
    click HTTPServer "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/app/http.go"
    click HTTPHandler "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/handler/http/server.go"
    click GRPCServer "https://github.com/kratoffq/avito-pvz-test/blob/main/cmd/grpc/main.go"
    click GRPCServer "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/app/grpc.go"
    click GRPCHandler "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/handler/grpc/pvz.go"
    click HTTPHandler "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/handler/http/handlers.go"
    click HTTPHandler "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/handler/http/pvz_handler.go"
    click HTTPHandler "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/handler/http/product_handler.go"
    click HTTPHandler "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/handler/http/reception_handler.go"
    click HTTPHandler "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/handler/http/user_handler.go"
    click AuthMW "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/handler/http/middleware/auth.go"
    click AuthMW "https://github.com/kratoffq/avito-pvz-test/blob/main/pkg/auth/auth.go"
    click AuthMW "https://github.com/kratoffq/avito-pvz-test/blob/main/pkg/auth/middleware.go"
    click UseCase "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/usecase/pvz/dto.go"
    click UseCase "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/usecase/pvz/service.go"
    click ServiceLayer "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/service/pvz/service.go"
    click ServiceLayer "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/service/product/service.go"
    click ServiceLayer "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/service/reception/service.go"
    click ServiceLayer "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/service/user/service.go"
    click DomainLayer "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/domain/pvz/model.go"
    click DomainLayer "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/domain/pvz/repository.go"
    click DomainLayer "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/domain/product/model.go"
    click DomainLayer "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/domain/product/repository.go"
    click DomainLayer "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/domain/reception/model.go"
    click DomainLayer "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/domain/reception/repository.go"
    click DomainLayer "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/domain/user/model.go"
    click DomainLayer "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/domain/user/repository.go"
    click PostgresAdapter "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/repository/postgres/postgres.go"
    click PostgresAdapter "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/repository/postgres/db.go"
    click PostgresAdapter "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/repository/postgres/pvz.go"
    click PostgresAdapter "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/repository/postgres/product.go"
    click PostgresAdapter "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/repository/postgres/reception.go"
    click PostgresAdapter "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/repository/postgres/user.go"
    click PostgresAdapter "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/repository/postgres/audit.go"
    click PostgresAdapter "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/repository/postgres/cache.go"
    click PostgresAdapter "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/repository/postgres/transaction.go"
    click PostgresAdapter "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/repository/postgres/queries/*.go"
    click Migrations "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/repository/migration/000001_init.up.sql"
    click Migrations "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/repository/migration/000001_init.down.sql"
    click Migrations "https://github.com/kratoffq/avito-pvz-test/blob/main/deployments/migrations/schema.sql"
    click MetricsMW "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/metrics/metrics.go"
    click MetricsMW "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/middleware/metrics.go"
    click MetricsMW "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/app/metrics.go"
    click ConfigLoader "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/app/config.go"
    click ConfigLoader "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/config/config.go"
    click ConfigLoader "https://github.com/kratoffq/avito-pvz-test/blob/main/configs/config.yaml"
    click Bootstrap "https://github.com/kratoffq/avito-pvz-test/blob/main/internal/app/app.go"
    click HTTPServer "https://github.com/kratoffq/avito-pvz-test/blob/main/api/openapi/types.gen.go"
    click HTTPServer "https://github.com/kratoffq/avito-pvz-test/blob/main/api/openapi/openapi.yaml"
    click HTTPServer "https://github.com/kratoffq/avito-pvz-test/blob/main/api/openapi/swagger.yaml"
    click GRPCHandler "https://github.com/kratoffq/avito-pvz-test/blob/main/api/proto/pvz.proto"
    click GRPCHandler "https://github.com/kratoffq/avito-pvz-test/blob/main/api/proto/pvz.pb.go"
    click GRPCHandler "https://github.com/kratoffq/avito-pvz-test/blob/main/api/proto/pvz_grpc.pb.go"

    %% Styles
    classDef adapters fill:#cce,stroke:#333,stroke-width:1px
    classDef app fill:#cfc,stroke:#333,stroke-width:1px
    classDef infra fill:#fcc,stroke:#333,stroke-width:1px
    classDef external fill:#ddd,stroke:#333,stroke-width:1px
    classDef cross fill:#eee,stroke:#333,stroke-width:1px
```
