# henvic/pgxtutorial architecture

> Architecture diagram of the GitHub repository henvic/pgxtutorial, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/henvic/pgxtutorial
- Repository: https://github.com/henvic/pgxtutorial

## Overview

##### Project Type & Purpose
- This is a tutorial application demonstrating how to build a backend service in Go that interacts with a PostgreSQL database.
- It includes examples of API (both HTTP and gRPC), database interactions, domain logic in the “inventory” package, and telemetry for monitoring.
- The project also includes infrastructure for CI/CD (GitHub workflows) and migration scripts to set up the PostgreSQL schema.

##### Key Components
a. API Layer(s):
- HTTP API: Represent this with the HTTP handler code located in “internal/api/http.go”.
- gRPC API: Represent this with the gRPC server code in “internal/api/grpc.go” along with the protobuf definitions in “internal/apiv1/api.proto” and generated code.
b. Database Layer:
- Migrations folder which is used to create the initial database schema.
c. Domain/Business Logic:
d. Telemetry:
- “internal/telemetry” package. This module, along with its test utility located in “internal/telemetry/telemetrytest”, is responsible for exporting metrics and traces.
e. Main Application:
- The “main.go” serves as the bootstrap of the application, tying together the HTTP and gRPC servers, database initialization, and telemetry.

##### Relationships and Interactions
- That both API endpoints invoke the Inventory domain/service, which subsequently communicates with the database layer.
- That the database layer communicates with PostgreSQL and that migration scripts are used during the setup or deployment phase.
- Interactions from various layers (particularly API and inventory) with the telemetry component for logging/tracing.

##### Architectural Patterns and Design Principles
- Separation of concerns: API concerns (network communication) are separated from the business logic (inventory services) and further separated from data access (database & postgres).
- Use of gRPC and Protobuf for versioned APIs, which implies a clear boundary between internal service communication and external integration.
- Modularity: each internal package (api, database, inventory, telemetry) is built to be independently testable, as seen by their accompanying test files.

##### Relevant Technologies and Tools
- Programming Language: Go
- Database: PostgreSQL
- API Communication: HTTP for REST endpoints and gRPC for RPC-based communication (with Protocol Buffers)
- Observability: Telemetry (with configurable exporters via environment variables)
- CI/CD: GitHub Actions (workflows are defined under .github/workflows)
- Build and Dependency Management: go.mod, go.sum

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["External Client"]:::external
    Main["Main Application"]:::service

    subgraph "API Layer"
        HTTP["HTTP API"]:::service
        GRPC["gRPC API"]:::service
        subgraph "gRPC Details"
            APIP["API Proto"]:::service
            GRPCGen["gRPC Generated Code"]:::service
        end
    end

    Inventory["Inventory Service"]:::service

    subgraph "Database Layer"
        DB["Database Connector"]:::service
        PG["PostgreSQL Database"]:::database
        DB -->|"connects_to"| PG
    end

    Migrations["Migration Scripts"]:::migration
    Telemetry["Telemetry Module"]:::service
    TelemetryTest["Telemetry Test Utility"]:::service
    CICD["CI/CD Pipeline"]:::infrastructure

    Client -->|"HTTP_Request"| HTTP
    Client -->|"gRPC_Request"| GRPC

    Main -->|"Initializes"| HTTP
    Main -->|"Initializes"| GRPC
    Main -->|"Initializes"| DB
    Main -->|"Initializes"| Telemetry
    Main -->|"Deploys"| CICD

    HTTP -->|"calls"| Inventory
    GRPC -->|"calls"| Inventory

    Inventory -->|"queries"| DB

    DB -->|"uses"| Migrations

    HTTP -->|"sendsMetrics"| Telemetry
    Inventory -->|"sendsMetrics"| Telemetry

    Telemetry -->|"hasTest"| TelemetryTest

    CICD -->|"triggers"| Migrations

    GRPC -->|"defined_by"| APIP
    GRPC -->|"implements"| GRPCGen

    classDef external fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef service fill:#9fdfbf,stroke:#333,stroke-width:2px;
    classDef database fill:#f9a,stroke:#333,stroke-width:2px;
    classDef infrastructure fill:#cbe,stroke:#333,stroke-width:2px;
    classDef migration fill:#fea,stroke:#333,stroke-width:2px;

    click HTTP "https://github.com/henvic/pgxtutorial/blob/main/internal/api/http.go"
    click GRPC "https://github.com/henvic/pgxtutorial/blob/main/internal/api/grpc.go"
    click APIP "https://github.com/henvic/pgxtutorial/blob/main/internal/apiv1/api.proto"
    click GRPCGen "https://github.com/henvic/pgxtutorial/blob/main/internal/apiv1/apipb/api.pb.go"
    click DB "https://github.com/henvic/pgxtutorial/tree/main/internal/database"
    click PG "https://github.com/henvic/pgxtutorial/tree/main/internal/postgres"
    click Migrations "https://github.com/henvic/pgxtutorial/blob/main/migrations/001_initial_schema.sql"
    click Inventory "https://github.com/henvic/pgxtutorial/tree/main/internal/inventory"
    click Telemetry "https://github.com/henvic/pgxtutorial/tree/main/internal/telemetry"
    click TelemetryTest "https://github.com/henvic/pgxtutorial/blob/main/internal/telemetry/telemetrytest/telemetrytest.go"
    click Main "https://github.com/henvic/pgxtutorial/blob/main/main.go"
    click CICD "https://github.com/henvic/pgxtutorial/tree/main/.github/workflows"
```
