# luigiazevedo/public-library architecture

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

- Interactive diagram: https://gitdiagram.com/luigiazevedo/public-library
- Repository: https://github.com/luigiazevedo/public-library

## Overview

##### Project type and purpose
- This is a Go-based backend API for a “Public Library” service, implemented with Hexagonal (Ports & Adapters) architecture.
- Its core domain manages three aggregates: User, Book, and Loan, exposing CRUD and borrow/return operations over HTTP.

##### File structure
- Top level
- cmd/main.go – application entrypoint and dependency wiring
- config/viper.go – configuration adapter (loads app.env)
- Taskfile.yml – local task runner definitions
- .github/workflows – CI for build & lint
- internal/
- domain/ – core: entity (Book, User, Loan) + usecase interactor implementations
- ports/ – interface definitions (inbound/usecase & outbound/repository)
- delivery/http/ – HTTP adapters (“controllers” or handlers using chi & zerolog)
- database/
– migrations/ – SQL scripts for Postgres schema
– repository/ – repository adapters implementing repository ports via pq
- mock/ – test doubles for ports
- docs/database.dbml – database schema DSL

##### README for additional insights
- Confirms Hexagonal (Ports & Adapters) pattern, lists dependencies (chi router, zerolog, Viper, pq, bcrypt, sqlmock, gomock).
- Emphasizes loose coupling: core business logic is independent of HTTP, DB, and config details.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Infrastructure
    subgraph "External / Infrastructure"
        direction TB
        CI_CI["CI Workflows"]:::external
        click CI_CI "https://github.com/luigiazevedo/public-library/tree/master/.github/workflows"
        Migrations["Database Migrations"]:::external
        click Migrations "https://github.com/luigiazevedo/public-library/tree/master/internal/database/migrations"
        Docs["DB Schema DSL"]:::external
        click Docs "https://github.com/luigiazevedo/public-library/blob/master/docs/database.dbml"
        Taskfile["Task Runner (Taskfile.yml)"]:::external
        Env["Env Example (app.env.example)"]:::external
    end

    CI_CI --> Config
    Env --> Config

    %% Configuration and Wiring
    Config["Config Adapter (Viper)"]:::adapter
    click Config "https://github.com/luigiazevedo/public-library/blob/master/config/viper.go"
    Main["Application Entrypoint"]:::adapter
    click Main "https://github.com/luigiazevedo/public-library/blob/master/cmd/main.go"

    Config --> Main

    %% HTTP Layer
    subgraph "HTTP Adapter Layer"
        direction TB
        BH["Book HTTP Handler"]:::adapter
        click BH "https://github.com/luigiazevedo/public-library/blob/master/internal/delivery/http/book_handler.go"
        UH["User HTTP Handler"]:::adapter
        click UH "https://github.com/luigiazevedo/public-library/blob/master/internal/delivery/http/user_handler.go"
        LH["Loan HTTP Handler"]:::adapter
        click LH "https://github.com/luigiazevedo/public-library/blob/master/internal/delivery/http/loan_handler.go"
    end

    Main --> BH
    Main --> UH
    Main --> LH

    %% Inbound Ports
    subgraph "Inbound Ports (Usecase Interfaces)"
        direction TB
        BPI["Book Usecase Interface"]:::port
        click BPI "https://github.com/luigiazevedo/public-library/blob/master/internal/ports/usecase/book_usecase.go"
        UPI["User Usecase Interface"]:::port
        click UPI "https://github.com/luigiazevedo/public-library/blob/master/internal/ports/usecase/user_usecase.go"
        LPI["Loan Usecase Interface"]:::port
        click LPI "https://github.com/luigiazevedo/public-library/blob/master/internal/ports/usecase/loan_usecase.go"
    end

    BH -->|calls| BPI
    UH -->|calls| UPI
    LH -->|calls| LPI

    %% Core Domain
    subgraph "Core Domain" 
        direction TB
        style CoreDomain fill:#bbdefb,stroke:#2196f3,stroke-width:2px
        subgraph Entities
            direction TB
            BE["Book Entity"]:::domain
            click BE "https://github.com/luigiazevedo/public-library/blob/master/internal/domain/entity/book_entity.go"
            UE["User Entity"]:::domain
            click UE "https://github.com/luigiazevedo/public-library/blob/master/internal/domain/entity/user_entity.go"
            LE["Loan Entity"]:::domain
            click LE "https://github.com/luigiazevedo/public-library/blob/master/internal/domain/entity/loan_entity.go"
        end
        subgraph "Usecase Implementations"
            direction TB
            BUI["Book Usecase Impl"]:::domain
            click BUI "https://github.com/luigiazevedo/public-library/blob/master/internal/domain/usecase/book_usecase.go"
            UUI["User Usecase Impl"]:::domain
            click UUI "https://github.com/luigiazevedo/public-library/blob/master/internal/domain/usecase/user_usecase.go"
            LUI["Loan Usecase Impl"]:::domain
            click LUI "https://github.com/luigiazevedo/public-library/blob/master/internal/domain/usecase/loan_usecase.go"
        end
    end

    BPI -->|"instantiates"| BUI
    UPI -->|"instantiates"| UUI
    LPI -->|"instantiates"| LUI

    BUI --> BE
    UUI --> UE
    LUI --> LE

    %% Outbound Ports
    subgraph "Outbound Ports (Repository Interfaces)"
        direction TB
        BRI["Book Repository Interface"]:::port
        click BRI "https://github.com/luigiazevedo/public-library/blob/master/internal/ports/repository/book_repository.go"
        URI["User Repository Interface"]:::port
        click URI "https://github.com/luigiazevedo/public-library/blob/master/internal/ports/repository/user_repository.go"
        LRI["Loan Repository Interface"]:::port
        click LRI "https://github.com/luigiazevedo/public-library/blob/master/internal/ports/repository/loan_repository.go"
    end

    BUI -->|depends on| BRI
    UUI -->|depends on| URI
    LUI -->|depends on| LRI

    %% Repository Adapters
    subgraph "Repository Adapters (Postgres)"
        direction TB
        BRA["Book Repository Adapter"]:::adapter
        click BRA "https://github.com/luigiazevedo/public-library/blob/master/internal/database/repository/book_repository.go"
        URA["User Repository Adapter"]:::adapter
        click URA "https://github.com/luigiazevedo/public-library/blob/master/internal/database/repository/user_repository.go"
        LRA["Loan Repository Adapter"]:::adapter
        click LRA "https://github.com/luigiazevedo/public-library/blob/master/internal/database/repository/loan_repository.go"
        RErr["Repository Errors"]:::adapter
        click RErr "https://github.com/luigiazevedo/public-library/blob/master/internal/database/repository/errors.go"
    end

    BRI -->|implemented by| BRA
    URI -->|implemented by| URA
    LRI -->|implemented by| LRA

    BRA --> RErr
    URA --> RErr
    LRA --> RErr

    %% Database
    DB["PostgreSQL Database"]:::database

    BRA -->|executes SQL| DB
    URA -->|executes SQL| DB
    LRA -->|executes SQL| DB

    %% Mocks for Testing
    subgraph "Mock Implementations"
        direction TB
        MBU["Mock Book Usecase"]:::mock
        click MBU "https://github.com/luigiazevedo/public-library/blob/master/internal/mock/book_usecase.go"
        MBUr["Mock Book Repository"]:::mock
        click MBUr "https://github.com/luigiazevedo/public-library/blob/master/internal/mock/book_repository.go"
        MUU["Mock User Usecase"]:::mock
        click MUU "https://github.com/luigiazevedo/public-library/blob/master/internal/mock/user_usecase.go"
        MUUr["Mock User Repository"]:::mock
        click MUUr "https://github.com/luigiazevedo/public-library/blob/master/internal/mock/user_repository.go"
        MLU["Mock Loan Usecase"]:::mock
        click MLU "https://github.com/luigiazevedo/public-library/blob/master/internal/mock/loan_usecase.go"
        MLUr["Mock Loan Repository"]:::mock
        click MLUr "https://github.com/luigiazevedo/public-library/blob/master/internal/mock/loan_repository.go"
    end

    style MBU fill:#f0f4c3,stroke:#cddc39
    style MBUr fill:#f0f4c3,stroke:#cddc39
    style MUU fill:#f0f4c3,stroke:#cddc39
    style MUUr fill:#f0f4c3,stroke:#cddc39
    style MLU fill:#f0f4c3,stroke:#cddc39
    style MLUr fill:#f0f4c3,stroke:#cddc39

    %% Legend
    subgraph "Legend"
        direction LR
        D1["Core Domain"]:::domain
        D2["Ports"]:::port
        D3["Adapters"]:::adapter
        D4["External / Infra"]:::external
        D5["Database"]:::database
    end

    classDef domain fill:#bbdefb,stroke:#2196f3,color:#0d47a1
    classDef port fill:#c8e6c9,stroke:#388e3c,color:#1b5e20
    classDef adapter fill:#ffe0b2,stroke:#f57c00,color:#e65100
    classDef external fill:#eeeeee,stroke:#9e9e9e,color:#424242
    classDef database fill:#d7ccc8,stroke:#5d4037,color:#3e2723
    classDef mock fill:#f0f4c3,stroke:#cddc39,color:#827717
```
