# dyoshyy/curlarc-service architecture

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

- Interactive diagram: https://gitdiagram.com/dyoshyy/curlarc-service
- Repository: https://github.com/dyoshyy/curlarc-service

## Overview

##### Project Type & Purpose
- This is a RESTful API service written in Go which forms part of the CurlARC application. It uses the Echo web framework for handling HTTP requests, GORM as an ORM to interact with a PostgreSQL database, and Atlas for managing database migrations.
- The README confirms that it is designed to launch an API and its accompanying database via Docker Compose.
- The overall purpose is to expose REST endpoints for managing entities such as records, teams, and users, with supporting features like JWT authentication and logging middleware.

##### Analyzing the File Structure
- Top-level files indicate containerization and deployment (Dockerfile, docker-compose.yml, fly.toml).
- The “internal” directory is organized into several subfolders:
- domain: Contains core domain entities (e.g., user, team, record) and the repository interfaces that enforce boundaries between the business logic and data storage.
- handler: Houses request/response handling and routing logic. Each domain appears to have its separate handler (recordHandler, teamHandler, userHandler).
- usecase: Encapsulates business logic and orchestrates interactions between the handler and repository layers.
- infra: Implements the actual data-access logic using GORM for interfacing with PostgreSQL.
- injector: Likely handles dependency injection to wire up the application components (e.g., initializing the database connection and repository instances).
- middleware: Contains JWT authentication and logging middleware, ensuring security and observability.
- utils: Provides common utility functions such as environment variable handling and JWT utilities.
- Additional directories like “migrations” and “mock” further reinforce the design approaches for database schema management and for testing/stubbing out external dependencies.

a. Main Components to Include:
- Clients: Representing external consumers (like web, mobile or any service) that send HTTP requests.
- REST API (Echo Server):
– Routing component (internal/handler/router.go) that directs incoming HTTP requests.
– Specific Handlers for records, teams, and users.
- Middleware: JWT authentication and request logging that intercepts HTTP requests.
- Business Logic / Usecases: Located in internal/usecase, handling core domain logic.
- Repositories: Abstraction layers defined in internal/domain/repository for data persistence.
- Infrastructure (GORM): The internal/infra package that implements the actual database interactions.
- Database: A PostgreSQL instance that stores application data.
- Dependency Injection: The injector layer (internal/injector) that ties together the handlers, use cases, and repositories.
- Migrations: The migrations directory contains SQL scripts for database schema evolution.

b. Relationships & Interactions:
- Clients → API (HTTP requests flow into the Echo router).
- API (Router) → Middleware: Requests are first intercepted by middleware components (e.g., JWT check, logging).
- Middleware → Handlers: Upon successful middleware processing, the request is forwarded to the appropriate handler (e.g., recordHandler, teamHandler).
- Handlers → Usecases: Handlers delegate business logic to the usecase layer.
- Usecases → Repositories: Usecases invoke repository methods to perform data operations.
- Repositories → Infra: Repository implementations use GORM (via infra package) to execute SQL queries on PostgreSQL.
- Injector: Orchestrates the dependency wiring ensuring that handlers get correctly instantiated with usecases, repository, and infra dependencies.

c. Architectural Patterns & Design Principles:
- Layered Architecture: The clear separation into presentation (handler), application (usecase), domain (entities, repository interfaces), and infrastructure (gormModels, sqlHandler) reinforces maintainability.
- Dependency Injection: The injector package ensures components are loosely coupled, making testing easier (further evidenced by the existence of a “mock” directory).
- RESTful Service Architecture: Emphasizes resolving HTTP requests with proper routing, middleware stack for cross-cutting concerns, and well-defined resources (users, teams, records).

d. Technologies, Frameworks, & Libraries:
- Go programming language.
- Echo for HTTP routing and middleware.
- GORM for ORM-based interactions with PostgreSQL.
- Atlas for managing migrations.
- Docker & Docker Compose for containerizing both the API and the database.
- JWT for secure authentication.

##### Elements
- Each component should be clearly labeled:
– Separate components for Middleware (JWT, Logging).
– Business Logic / Usecases.
– Repositories and Data Access (GORM/Infra).
– The PostgreSQL database.
– Include the Dependency Injector as a configuration/initialization layer.
– From Client → Middleware → Handler → Usecase → Repository → Infra → Database.
– Rectangles for physical components (database, containers).
– Ovals for business logic.
– Diamonds for decision points (e.g., middleware validations).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Client["Client (External)"]:::client
    end

    %% API Layer
    subgraph "API Layer"
        API["REST API (Echo Server)"]:::api
        Router["Router"]:::api
        subgraph "Middlewares"
            JWT["JWT Middleware"]:::middleware
            Log["Logging Middleware"]:::middleware
        end
        subgraph "Handlers"
            RecordH["Record Handler"]:::handler
            TeamH["Team Handler"]:::handler
            UserH["User Handler"]:::handler
        end
    end

    %% Business Layer
    subgraph "Business Layer"
        Usecase["Business Logic/Usecases"]:::usecase
    end

    %% Domain Layer
    subgraph "Domain Layer"
        Domain["Domain Entities"]:::domain
        Repo["Repository Interfaces"]:::domain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        Infra["Data Access (GORM)"]:::infra
    end

    %% Data Storage
    subgraph "Data Storage"
        DB["PostgreSQL Database"]:::db
    end

    %% Dependency Injection and Migrations
    Injection["Dependency Injection"]:::injector
    Migrations["Migrations"]:::migrations

    %% Connections
    Client -->|"HTTP_Request"| API
    API -->|"Routes"| Router
    Router -->|"Passes"| JWT
    Router -->|"Passes"| Log

    JWT -->|"Authenticates"| RecordH
    JWT -->|"Authenticates"| TeamH
    JWT -->|"Authenticates"| UserH

    Log -->|"Logs"| RecordH
    Log -->|"Logs"| TeamH
    Log -->|"Logs"| UserH

    RecordH -->|"Delegates"| Usecase
    TeamH -->|"Delegates"| Usecase
    UserH -->|"Delegates"| Usecase

    Usecase -->|"Calls"| Repo
    Repo -->|"Uses"| Infra
    Infra -->|"Queries"| DB

    Injection -->|"Wires"| API
    Injection -->|"Wires"| Usecase
    Injection -->|"Wires"| Repo
    Injection -->|"Wires"| Infra

    Migrations -->|"Manages"| DB

    %% Click Events
    click API "https://github.com/dyoshyy/curlarc-service/blob/develop/main.go"
    click Router "https://github.com/dyoshyy/curlarc-service/blob/develop/internal/handler/router.go"
    click RecordH "https://github.com/dyoshyy/curlarc-service/blob/develop/internal/handler/recordHandler.go"
    click TeamH "https://github.com/dyoshyy/curlarc-service/blob/develop/internal/handler/teamHandler.go"
    click UserH "https://github.com/dyoshyy/curlarc-service/blob/develop/internal/handler/userHandler.go"
    click Domain "https://github.com/dyoshyy/curlarc-service/tree/develop/internal/domain/entity"
    click Repo "https://github.com/dyoshyy/curlarc-service/tree/develop/internal/domain/repository"
    click Usecase "https://github.com/dyoshyy/curlarc-service/tree/develop/internal/usecase"
    click JWT "https://github.com/dyoshyy/curlarc-service/blob/develop/internal/middleware/jwt.go"
    click Log "https://github.com/dyoshyy/curlarc-service/blob/develop/internal/middleware/logBody.go"
    click Infra "https://github.com/dyoshyy/curlarc-service/tree/develop/internal/infra"
    click Injection "https://github.com/dyoshyy/curlarc-service/tree/develop/internal/injector"
    click Migrations "https://github.com/dyoshyy/curlarc-service/tree/develop/migrations"

    %% Styles
    classDef client fill:#FFEBEE,stroke:#C62828,stroke-width:2px;
    classDef api fill:#E3F2FD,stroke:#1565C0,stroke-width:2px;
    classDef middleware fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px;
    classDef handler fill:#FFF3E0,stroke:#EF6C00,stroke-width:2px;
    classDef usecase fill:#F3E5F5,stroke:#8E24AA,stroke-width:2px;
    classDef domain fill:#E0F7FA,stroke:#00838F,stroke-width:2px;
    classDef infra fill:#F1F8E9,stroke:#558B2F,stroke-width:2px;
    classDef db fill:#ECEFF1,stroke:#37474F,stroke-width:2px;
    classDef injector fill:#FFFDE7,stroke:#F9A825,stroke-width:2px;
    classDef migrations fill:#ECEFF1,stroke:#546E7A,stroke-width:2px;
```
