# bagashiz/go-pos architecture

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

- Interactive diagram: https://gitdiagram.com/bagashiz/go-pos
- Repository: https://github.com/bagashiz/go-pos

## Overview

##### Project type and purpose
- This is a backend-only RESTful Point-of-Sale (POS) service written in Go.
- It follows Hexagonal (Ports & Adapters) architecture.
- It uses Gin for HTTP, PostgreSQL (via pgx & Squirrel) as primary persistence, Redis (go-redis) for caching, and Paseto for auth tokens.
- Swagger docs are exposed via gin-swagger.

##### File structure
- cmd/http/main.go – program entrypoint; spins up Gin router, mounts middleware, handlers, Swagger.
- internal/adapter – all adapters:
- handler/http – inbound HTTP controllers, router, middleware, validation, response formatting.
- auth/paseto – token creation/verification.
- storage/postgres – migrations & repository implementations.
- storage/redis – caching adapter.
- config, logger – loading config, structured logging.
- internal/core – the hexagonal core:
- domain – entities and value objects (User, Order, Product, etc.).
- port – interfaces (AuthPort, UserPort, ProductPort, CachePort…).
- service – business logic implementing use cases, wired to ports.
- util – helper functions (password hashing, caching utilities).
- docs – Swagger JSON/YAML for API docs.
- Dockerfile, docker-compose.yml – containerization.
- Taskfile.yml – orchestration (build, run migrations, start).

##### README
- Confirms REST API, hexagonal architecture, technology stack.
- Points to API docs at /docs/index.html and DB schema at schema.dbml / docs/swagger.*
- Describes dev flow: .env, docker-compose, Taskfile.

a. Main Components
- Client (Web UI, Postman, Mobile) – generates HTTP requests.
- API Layer (Gin) – request router, middleware (auth, logging, validation).
- Handler Layer – HTTP handlers for User, Product, Category, Order, Payment.
- Service Layer – core business logic (auth, user management, product catalog, orders, payments).
- Domain Model – core entities & value objects.
- Ports (Interfaces) – abstract outbound calls (UserPort, PaymentPort, CachePort, AuthPort…).
- Adapters:
- Postgres Adapter – repository implementations, migrations.
- Redis Adapter – cache implementation.
- Paseto Adapter – token service.
- Config & Logger – environment config loader, structured logging.
- External Systems: PostgreSQL DB, Redis Cache.
- API Docs (Swagger UI).

b. Relationships & Interactions
- Client → HTTP Middleware (Auth, Logging) → Handler → Service → Domain & Ports → Adapter → External Systems.
- Service layer calls Ports (interfaces). Ports are implemented by Adapters.
- Config/Logger used by both HTTP and Adapters.
- Migrations applied to Postgres at startup or via Taskfile.

c. Architectural Patterns & Principles
- Hexagonal Architecture: clear separation of core (domain & service) from frameworks & infrastructure.
- Dependency Inversion: core depends only on interfaces.
- Single Responsibility: handlers orchestrate HTTP; services host business rules; adapters handle I/O.
- Layered flow: HTTP → Handler → Service → Persistence/Cache.

d. Key Technologies
- Gin (HTTP).
- Squirrel + pgx (Postgres).
- go-redis (Redis).
- Paseto (token auth).
- Swaggo/Gin-Swagger (API docs).
- Taskfile for tasks; Docker/Docker-Compose for containers.

##### Essential Elements to Capture
- Separation of concerns: HTTP vs. business logic vs. persistence.
- Core hexagon: domain types at center, ports on its edges.
- Adapter wrappers fulfilling those ports.
- Cross-cutting: config loader, logger.
- API documentation endpoint as a side note.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Inbound Adapters
    subgraph "Inbound Adapters" 
        direction TB
        API["API Layer (Gin Router & Middleware)"]:::inbound
        click API "https://github.com/bagashiz/go-pos/blob/main/cmd/http/main.go"
        Router["HTTP Router"]:::inbound
        click Router "https://github.com/bagashiz/go-pos/blob/main/internal/adapter/handler/http/router.go"
        Middleware["HTTP Middleware"]:::inbound
        click Middleware "https://github.com/bagashiz/go-pos/blob/main/internal/adapter/handler/http/middleware.go"
        subgraph "HTTP Handlers"
            direction TB
            AuthH["Auth Handler"]:::inbound
            click AuthH "https://github.com/bagashiz/go-pos/blob/main/internal/adapter/handler/http/auth.go"
            UserH["User Handler"]:::inbound
            click UserH "https://github.com/bagashiz/go-pos/blob/main/internal/adapter/handler/http/user.go"
            CategoryH["Category Handler"]:::inbound
            click CategoryH "https://github.com/bagashiz/go-pos/blob/main/internal/adapter/handler/http/category.go"
            ProductH["Product Handler"]:::inbound
            click ProductH "https://github.com/bagashiz/go-pos/blob/main/internal/adapter/handler/http/product.go"
            OrderH["Order Handler"]:::inbound
            click OrderH "https://github.com/bagashiz/go-pos/blob/main/internal/adapter/handler/http/order.go"
            PaymentH["Payment Handler"]:::inbound
            click PaymentH "https://github.com/bagashiz/go-pos/blob/main/internal/adapter/handler/http/payment.go"
            HelperH["Handler Helpers"]:::inbound
            click HelperH "https://github.com/bagashiz/go-pos/blob/main/internal/adapter/handler/http/helper.go"
            ValidatorH["Request Validator"]:::inbound
            click ValidatorH "https://github.com/bagashiz/go-pos/blob/main/internal/adapter/handler/http/validator.go"
            ResponseH["Response Formatter"]:::inbound
            click ResponseH "https://github.com/bagashiz/go-pos/blob/main/internal/adapter/handler/http/response.go"
        end
    end

    %% Core Hexagon
    subgraph "Core (Hexagon)" 
        direction TB
        subgraph "Domain Model"
            direction TB
            DomainUser["User Entity"]:::core
            click DomainUser "https://github.com/bagashiz/go-pos/blob/main/internal/core/domain/user.go"
            DomainToken["TokenPayload VO"]:::core
            click DomainToken "https://github.com/bagashiz/go-pos/blob/main/internal/core/domain/tokenPayload.go"
            DomainCategory["Category Entity"]:::core
            click DomainCategory "https://github.com/bagashiz/go-pos/blob/main/internal/core/domain/category.go"
            DomainProduct["Product Entity"]:::core
            click DomainProduct "https://github.com/bagashiz/go-pos/blob/main/internal/core/domain/product.go"
            DomainOrder["Order Entity"]:::core
            click DomainOrder "https://github.com/bagashiz/go-pos/blob/main/internal/core/domain/order.go"
            DomainOrderProd["OrderProduct VO"]:::core
            click DomainOrderProd "https://github.com/bagashiz/go-pos/blob/main/internal/core/domain/orderProduct.go"
            DomainPayment["Payment Entity"]:::core
            click DomainPayment "https://github.com/bagashiz/go-pos/blob/main/internal/core/domain/payment.go"
            DomainError["Domain Errors"]:::core
            click DomainError "https://github.com/bagashiz/go-pos/blob/main/internal/core/domain/error.go"
        end
        subgraph "Service Layer"
            direction TB
            ServiceAuth["Auth Service"]:::core
            click ServiceAuth "https://github.com/bagashiz/go-pos/blob/main/internal/core/service/auth.go"
            ServiceUser["User Service"]:::core
            click ServiceUser "https://github.com/bagashiz/go-pos/blob/main/internal/core/service/user.go"
            ServiceCategory["Category Service"]:::core
            click ServiceCategory "https://github.com/bagashiz/go-pos/blob/main/internal/core/service/category.go"
            ServiceProduct["Product Service"]:::core
            click ServiceProduct "https://github.com/bagashiz/go-pos/blob/main/internal/core/service/product.go"
            ServiceOrder["Order Service"]:::core
            click ServiceOrder "https://github.com/bagashiz/go-pos/blob/main/internal/core/service/order.go"
            ServicePayment["Payment Service"]:::core
            click ServicePayment "https://github.com/bagashiz/go-pos/blob/main/internal/core/service/payment.go"
        end
        subgraph "Ports (Interfaces)"
            direction TB
            PortAuth["AuthPort"]:::core
            click PortAuth "https://github.com/bagashiz/go-pos/blob/main/internal/core/port/auth.go"
            PortUser["UserPort"]:::core
            click PortUser "https://github.com/bagashiz/go-pos/blob/main/internal/core/port/user.go"
            PortCategory["CategoryPort"]:::core
            click PortCategory "https://github.com/bagashiz/go-pos/blob/main/internal/core/port/category.go"
            PortProduct["ProductPort"]:::core
            click PortProduct "https://github.com/bagashiz/go-pos/blob/main/internal/core/port/product.go"
            PortOrder["OrderPort"]:::core
            click PortOrder "https://github.com/bagashiz/go-pos/blob/main/internal/core/port/order.go"
            PortPayment["PaymentPort"]:::core
            click PortPayment "https://github.com/bagashiz/go-pos/blob/main/internal/core/port/payment.go"
            PortCache["CachePort"]:::core
            click PortCache "https://github.com/bagashiz/go-pos/blob/main/internal/core/port/cache.go"
            PortMock["Mock Ports"]:::core
            click PortMock "https://github.com/bagashiz/go-pos/tree/main/internal/core/port/mock/"
        end
    end

    %% Outbound Adapters
    subgraph "Outbound Adapters"
        direction TB
        subgraph "Postgres Adapter"
            direction TB
            PGDB["Postgres DB Adapter"]:::outbound
            click PGDB "https://github.com/bagashiz/go-pos/blob/main/internal/adapter/storage/postgres/db.go"
            Migrations["Migrations"]:::outbound
            click Migrations "https://github.com/bagashiz/go-pos/tree/main/internal/adapter/storage/postgres/migrations/"
            RepoUser["User Repo"]:::outbound
            click RepoUser "https://github.com/bagashiz/go-pos/blob/main/internal/adapter/storage/postgres/repository/user.go"
            RepoCategory["Category Repo"]:::outbound
            click RepoCategory "https://github.com/bagashiz/go-pos/blob/main/internal/adapter/storage/postgres/repository/category.go"
            RepoProduct["Product Repo"]:::outbound
            click RepoProduct "https://github.com/bagashiz/go-pos/blob/main/internal/adapter/storage/postgres/repository/product.go"
            RepoOrder["Order Repo"]:::outbound
            click RepoOrder "https://github.com/bagashiz/go-pos/blob/main/internal/adapter/storage/postgres/repository/order.go"
            RepoPayment["Payment Repo"]:::outbound
            click RepoPayment "https://github.com/bagashiz/go-pos/blob/main/internal/adapter/storage/postgres/repository/payment.go"
            RepoHelper["Repo Helper"]:::outbound
            click RepoHelper "https://github.com/bagashiz/go-pos/blob/main/internal/adapter/storage/postgres/repository/helper.go"
        end
        RedisAdapter["Redis Cache Adapter"]:::outbound
        click RedisAdapter "https://github.com/bagashiz/go-pos/blob/main/internal/adapter/storage/redis/redis.go"
        PasetoAdapter["Paseto Auth Adapter"]:::outbound
        click PasetoAdapter "https://github.com/bagashiz/go-pos/blob/main/internal/adapter/auth/paseto/paseto.go"
        ConfigLoader["Config Loader"]:::outbound
        click ConfigLoader "https://github.com/bagashiz/go-pos/blob/main/internal/adapter/config/config.go"
        Logger["Structured Logger"]:::outbound
        click Logger "https://github.com/bagashiz/go-pos/blob/main/internal/adapter/logger/slog.go"
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        PostgresDB["PostgreSQL Database"]:::external
        RedisCache["Redis Cache"]:::external
        APIDocs["Swagger Docs"]:::external
        click APIDocs "https://github.com/bagashiz/go-pos/blob/main/docs/swagger.json"
    end

    %% Client
    Client["Client (Web/UI/Postman/Mobile)"]:::external

    %% Flows
    Client -->|HTTP Request| API
    API --> Router
    API --> Middleware
    Router --> AuthH
    Router --> UserH
    Router --> CategoryH
    Router --> ProductH
    Router --> OrderH
    Router --> PaymentH
    AuthH --> ServiceAuth
    UserH --> ServiceUser
    CategoryH --> ServiceCategory
    ProductH --> ServiceProduct
    OrderH --> ServiceOrder
    PaymentH --> ServicePayment
    ServiceAuth -->|uses| PortAuth
    ServiceUser -->|uses| PortUser
    ServiceCategory -->|uses| PortCategory
    ServiceProduct -->|uses| PortProduct
    ServiceOrder -->|uses| PortOrder
    ServicePayment -->|uses| PortPayment
    ServiceAuth -->|caches| PortCache
    PortAuth --> PasetoAdapter
    PortCache --> RedisAdapter
    PortUser --> RepoUser
    PortCategory --> RepoCategory
    PortProduct --> RepoProduct
    PortOrder --> RepoOrder
    PortPayment --> RepoPayment
    RepoUser --> PostgresDB
    RepoCategory --> PostgresDB
    RepoProduct --> PostgresDB
    RepoOrder --> PostgresDB
    RepoPayment --> PostgresDB
    ConfigLoader --> API
    ConfigLoader --> PGDB
    Logger --> API
    Logger --> PGDB

    %% Styles
    classDef inbound fill:#D0E8FF,stroke:#0B5394,color:#0B5394;
    classDef core fill:#FFF2CC,stroke:#7F6000,color:#7F6000;
    classDef outbound fill:#DFF2D8,stroke:#6A9955,color:#6A9955;
    classDef external fill:#E1E1E1,stroke:#888888,color:#555555;
```
