# aguvilte/alp-evaluator architecture

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

- Interactive diagram: https://gitdiagram.com/aguvilte/alp-evaluator
- Repository: https://github.com/aguvilte/alp-evaluator

## Overview

##### Project type and purpose
- This is a Go‑based backend microservice named “alp‑evaluator.”
- It exposes HTTP endpoints under cmd/api (ping and prediction), implements business logic in internal/core, and interacts with external systems via repository adapters (OS commands and REST calls).

##### File structure
- Top‑level:
- cmd/api – entrypoint for the HTTP server (app.go, dependencies.go)
- cmd/main.go – optionally bootstraps other commands or invokes api
- internal/core – “hexagonal” core:
– domain/license_plate.go (entity)
– ports/{repositories.go,services.go} (interfaces)
– services/prediction_service.go (business logic)
- internal/handlers – transport layer (HTTP handlers)
– ping/handler.go
– prediction/handler.go
- internal/repositories – adapters:
– os/os.go (executes local OS commands)
– rest/rest.go (calls external REST service)

##### README
- Minimal README (“# alp‑evaluator”) – no extra architectural detail. All intelligence must come from file layout.

a. Main components
- HTTP Server (net/http or similar)
- Handlers (Ping, Prediction)
- Application Service (PredictionService)
- Domain Model (LicensePlate)
- Ports (ServicePort, RepositoryPort interfaces)
- Adapters/Repositories (OSAdapter, RESTAdapter)
- External Systems (Operating System, External License‑Plate API)

b. Relationships & interactions
1. Client → HTTP Server → Handler
2. Handler invokes PredictionService via ServicePort
3. PredictionService uses one or more RepositoryPort interfaces to fetch or process data
4. Each RepositoryPort is implemented by an adapter: OSAdapter calls local shell, RESTAdapter calls remote HTTP API
5. Results bubble back through the same path to the client

c. Architectural patterns
- Hexagonal (Ports & Adapters)
- Layered separation: Transport (handlers) → Application (services) → Domain → Infrastructure (adapters)
- Dependency Injection in cmd/api/dependencies.go

d. Key technologies/frameworks
- Go modules (go.mod/go.sum)
- net/http or a lightweight Go HTTP framework
- Standard library exec package (OS adapter)
- net/http client (REST adapter)

##### Essential details to capture
- Ports & Adapters boundaries explicitly
- Where dependency injection occurs (dependencies.go)
- Both repository implementations to emphasize pluggability

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Client["Client"]:::external

    %% Entrypoints
    subgraph "Entrypoints"
        direction TB
        HTTPServer["HTTP Server Entrypoint\n(cmd/api/app.go)"]:::entry
        CLI["CLI/Bootstrapper\n(cmd/main.go)"]:::entry
    end

    %% Dependency Injection
    DI["Dependency Injection\n(cmd/api/dependencies.go)"]:::config

    %% Transport Layer
    subgraph "Transport Layer (Handlers)" 
        direction TB
        PingHandler["Ping Handler\n(internal/handlers/ping/handler.go)"]:::transport
        PredHandler["Prediction Handler\n(internal/handlers/prediction/handler.go)"]:::transport
    end

    %% Application Layer
    subgraph "Application Layer (Service)"
        direction TB
        ServicePort["Service Port Interface\n(internal/core/ports/services.go)"]:::interface
        PredService["Prediction Service\n(internal/core/services/prediction_service.go)"]:::application
    end

    %% Domain Layer
    subgraph "Domain Layer"
        direction TB
        RepoPort["Repository Port Interface\n(internal/core/ports/repositories.go)"]:::interface
        LicensePlate["LicensePlate Entity\n(internal/core/domain/license_plate.go)"]:::domain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer (Adapters)"
        direction TB
        OSAdapter["OS Adapter\n(internal/repositories/os/os.go)"]:::infrastructure
        RESTAdapter["REST Adapter\n(internal/repositories/rest/rest.go)"]:::infrastructure
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        OS["Operating System"]:::external
        ExternalAPI["External License-Plate API"]:::external
    end

    %% Relationships
    Client -->|sends HTTP request| HTTPServer
    HTTPServer -->|injects dependencies| DI
    DI -->|wires handlers| PingHandler
    DI -->|wires handlers| PredHandler
    PingHandler -->|uses ServicePort| ServicePort
    PredHandler -->|uses ServicePort| PredService
    PredService -->|implements| ServicePort
    PredService -->|calls| RepoPort
    RepoPort -->|implemented by| OSAdapter
    RepoPort -->|implemented by| RESTAdapter
    OSAdapter -->|executes commands| OS
    RESTAdapter -->|calls API| ExternalAPI
    PredService -->|uses entity| LicensePlate

    %% Click Events
    click HTTPServer "https://github.com/aguvilte/alp-evaluator/blob/master/cmd/api/app.go"
    click CLI "https://github.com/aguvilte/alp-evaluator/blob/master/cmd/main.go"
    click DI "https://github.com/aguvilte/alp-evaluator/blob/master/cmd/api/dependencies.go"
    click PingHandler "https://github.com/aguvilte/alp-evaluator/blob/master/internal/handlers/ping/handler.go"
    click PredHandler "https://github.com/aguvilte/alp-evaluator/blob/master/internal/handlers/prediction/handler.go"
    click PredService "https://github.com/aguvilte/alp-evaluator/blob/master/internal/core/services/prediction_service.go"
    click ServicePort "https://github.com/aguvilte/alp-evaluator/blob/master/internal/core/ports/services.go"
    click RepoPort "https://github.com/aguvilte/alp-evaluator/blob/master/internal/core/ports/repositories.go"
    click LicensePlate "https://github.com/aguvilte/alp-evaluator/blob/master/internal/core/domain/license_plate.go"
    click OSAdapter "https://github.com/aguvilte/alp-evaluator/blob/master/internal/repositories/os/os.go"
    click RESTAdapter "https://github.com/aguvilte/alp-evaluator/blob/master/internal/repositories/rest/rest.go"

    %% Styles
    classDef external fill:#ccccff,stroke:#6666ff,color:#000;
    classDef entry fill:#ffdddd,stroke:#ff4444,color:#000;
    classDef config fill:#ffeebb,stroke:#eeaa44,color:#000;
    classDef transport fill:#ddeeff,stroke:#3399ff,color:#000;
    classDef application fill:#ddffdd,stroke:#44aa44,color:#000;
    classDef domain fill:#ffebcc,stroke:#ff9933,color:#000;
    classDef infrastructure fill:#eeeeee,stroke:#999999,color:#000;
    classDef interface fill:#ffeeff,stroke:#cc66cc,color:#000;
```
