# jairogloz/go-l architecture

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

- Interactive diagram: https://gitdiagram.com/jairogloz/go-l
- Repository: https://github.com/jairogloz/go-l

## Overview

##### Project Type & Purpose
- GO-L is a RESTful API backend built in Go, focused on managing soccer tournaments, leagues, and related sports data.
- The README emphasizes that it uses the Gin framework for HTTP handling and employs Hexagonal Architecture, ensuring separation between core business logic and external dependencies. This design makes it ideal to illustrate layers such as API, domain, services, and repositories.

##### Analyzing the File Structure
- The "cmd/api" directory contains the API’s entry point (main.go) and subdirectories like "core" and "handlers" that separate core domain logic from HTTP-specific request handling.
- The "pkg" folder is segmented into "domain," "ports," "repositories," and "services", which are key pillars in a Hexagonal Architecture:
- The "domain" package carries core business entities (e.g., league.go, player.go).
- The "services" package handles use-case implementations for leagues, players, tournaments, and teams.
- The "repositories" (particularly under "mongo") indicate integration with a MongoDB back-end for persistence.
- The "ports" package likely defines interfaces that abstract data access or external integrations.
- Additional directories like "mocks" provide test doubles to mock interfaces during testing, underlining thorough testing practices and clean separation of concerns.

- Major components:
- API Layer (cmd/api): Contains the HTTP server built with the Gin framework.
- Core Business Logic (core from cmd/api and pkg/domain): Represents domain models (player, league, tournament) and custom error handling.
- Service Layer (pkg/services): Implements business rules, orchestrates domain logic, and processes use cases.
- Repository Layer (pkg/repositories/mongo): Handles data storage and retrieval from the MongoDB database.
- Ports (pkg/ports): Abstract interfaces to decouple the business logic from external systems.
- Relationships:
- The API Layer receives HTTP requests (displayed as an entry point) which are then routed to appropriate handlers.
- Handlers call the Service Layer to process the request.
- The Service Layer interacts with the Repository Layer via defined Ports (interfaces) to perform CRUD operations.
- Core Domain definitions provide data contracts passed among these layers.
- Optionally, include the external MongoDB as the actual data store.

##### Important Architectural Patterns and Technologies
- Hexagonal (Ports and Adapters) Architecture: Clearly show an inner core (domain and services) surrounded by adapters (HTTP, persistence).
- RESTful API design using the Gin framework, represented as the communication interface.
- Testing and Mocks: Although not the focus of the runtime system, a note for possible internal testing components using mock implementations.
- You may also hint at build and deployment aspects with references to Docker Compose (docker-compose.yaml) which suggests containerized deployment and CI/CD (via .github/workflows).

##### What
– HTTP Request → API Handler → Service → Repository → MongoDB
- Annotations for architectural patterns (Hexagonal Architecture), using labels like “Ports & Adapters” between the service and repository layers.
- External dependencies (like MongoDB) as distinct external nodes.

- A layered structure: API/Handlers → Services → Repositories → External Database.
- Clearly marked boundaries following the principles of Hexagonal Architecture.
- Detailed annotations on flow direction, component interactions, and underlying technologies (Go, Gin, MongoDB).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "API Layer"
        A["API Entry (cmd/api/main.go)"]:::api
        B["API Handlers (cmd/api/handlers)"]:::api
    end

    subgraph "Application Layer"
        C["Service Layer (pkg/services)"]:::service
    end

    subgraph "Domain Layer"
        D["Core Business Logic (cmd/api/core)"]:::domain
        E["Domain Models (pkg/domain)"]:::domain
    end

    subgraph "Infrastructure Layer"
        F["Ports (pkg/ports)"]:::ports
        G["Mongo Repository (pkg/repositories/mongo)"]:::repository
    end

    H["MongoDB"]:::external

    %% Relationships
    A -->|"starts"| B
    B -->|"routes_to"| C
    C -->|"processes"| D
    D -->|"references"| E
    C -->|"uses"| F
    F -->|"connects_to"| G
    G -->|"persists_to"| H

    %% Click Events
    click A "https://github.com/jairogloz/go-l/blob/develop/cmd/api/main.go"
    click B "https://github.com/jairogloz/go-l/tree/develop/cmd/api/handlers"
    click D "https://github.com/jairogloz/go-l/tree/develop/cmd/api/core"
    click E "https://github.com/jairogloz/go-l/tree/develop/pkg/domain"
    click C "https://github.com/jairogloz/go-l/tree/develop/pkg/services"
    click F "https://github.com/jairogloz/go-l/tree/develop/pkg/ports"
    click G "https://github.com/jairogloz/go-l/tree/develop/pkg/repositories/mongo"

    %% Styles
    classDef api fill:#FFCCCC,stroke:#CC0000,stroke-width:2px;
    classDef service fill:#D5F5E3,stroke:#229954,stroke-width:2px;
    classDef domain fill:#D6EAF8,stroke:#3498DB,stroke-width:2px;
    classDef ports fill:#FDEBD0,stroke:#F39C12,stroke-width:2px;
    classDef repository fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef external fill:#D5DBDB,stroke:#566573,stroke-width:2px;
```
