# richardbertozzo/type-coffee architecture

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

- Interactive diagram: https://gitdiagram.com/richardbertozzo/type-coffee
- Repository: https://github.com/richardbertozzo/type-coffee

## Overview

##### Project Overview and Main Components
- Project Purpose – “The Best Type of Coffee” is a Go application that, based on user input characteristics, provides information about the best type of coffee. The application integrates two primary data sources: a database (populated via an ETL process using a CSV dataset) and the external Google Gemini API.
- Major entrypoints are clearly divided into three primary command applications:
- ETL: Loads and transforms coffee dataset data into the Postgres database.
- API: Serves the coffee selection information to users via either HTTP REST or gRPC.
- CLI: Provides a command-line interface to interact with the system.

##### Architectural Layers and Components
a. Data Ingestion and ETL:
- ETL Module (cmd/etl) that reads the CSV data from the data folder, processes it, and populates the database.
- Underlying database configuration and schema details are maintained in the configs/db directory.

b. Backend/API Service:
- API Server (cmd/api) which can operate as either:
- HTTP REST API (with full OpenAPI/Swagger specification in api/openapi.yaml)
- gRPC server (with the protobuf definitions in api/coffee.proto)
- Business logic and use cases are defined in the coffee directory, with separation into:
- coffee/usecase for domain logic (e.g., bestcoffee selection)
- coffee/provider for interactions with the database and external services
- coffee/handler for both HTTP and gRPC handling.

c. CLI Application:
- CLI Module (cmd/cli) that provides a command-line interface to invoke coffee requests using both Gemini API and database results.

d. External Integrations:
- Google Gemini API: Integration point used to process user feedback and produce coffee recommendations.
- Database (Postgres): As the secondary data source with configurations in infra/database and provider packages handling SQL interactions.

e. Infrastructure and Configuration:
- Environment configuration (.env.example and internal/config)
- Continuous Integration and Deployment workflows (.github/workflows)
- Dockerfile for containerized deployment.
- Makefile for local development tasks (e.g., launching postgres with “make pg-up” and run commands).

##### Defining Relationships and Data Flow
- A Web/API Client invoking the API (HTTP or gRPC)
- A User running the CLI tool
- Both interfaces internally route requests to the “Coffee Usecase” logic, which draws data:
- From the local Database (Populated via the ETL process)
- From the External Google Gemini API (via the provider layer)
- ETL → Database (data ingestion process)
- User Input → CLI / API → Business Logic → (Database and Gemini API) → Response → Back to CLI / API Client

##### Highlighting Architectural Patterns and Design Principles
- Separation of Concerns:
- The code base clearly separates ETL, API handling (both in HTTP and gRPC variants), and CLI, following the Single Responsibility Principle.
- Layered Architecture:
- Presentation (HTTP/gRPC handlers and CLI) → Domain/Usecase (coffee/usecase) → Data Access / Integration (coffee/provider and infra/database).
- Extensibility:
- The structure incentivizes further extension (for example, adding new processing pipelines or API endpoints) without tightly coupling layers.
- Configuration Driven:
- The use of environment variables (with .env) and configuration directories (internal/config, configs/) emphasizes externalized configuration.

##### Relevant Technologies and Libraries
- Go for backend server implementation.
- gRPC (with protobuf-generated code in coffee/api)
- HTTP routing and middleware (using standard or community libraries in Go)
- Database access with Postgres (see configs and infra/database)
- External API integration with Google Gemini API.
- Code generation tools (referenced by openapi_server.gen.go and openapi_types.gen.go)
- Docker for deployment (Dockerfile provided).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Interface Layer
    subgraph "Interface Layer"
        UI["User"]:::ui
        WA["Web/API Client"]:::ui
        CLI_Interface["CLI Interface"]:::ui
    end

    %% Application Layer
    subgraph "Application Layer"
        APIServer["API Server"]:::app
        REST["HTTP REST API Spec"]:::app
        GRPC["gRPC API Spec"]:::app
        HTTPHandler["HTTP Handler"]:::app
        GRPCHandler["gRPC Handler"]:::app
        CLIApp["CLI Application"]:::app
    end

    %% Business Logic Layer
    subgraph "Business Logic"
        Usecase["Coffee Usecase"]:::business
    end

    %% Provider Layer
    subgraph "Provider Layer"
        DBProvider["Database Provider"]:::provider
        GeminiProvider["Gemini API Provider"]:::provider
    end

    %% Persistence Layer
    subgraph "Persistence"
        ETL["ETL Process"]:::persistence
        CSV["CSV Dataset"]:::persistence
        DBConfig["DB Configuration"]:::persistence
        PostDB["Postgres Database"]:::persistence
    end

    %% External Services
    subgraph "External Services"
        EXT["Google Gemini API"]:::external
    end

    %% Connections from Interface Layer to Application Layer
    UI --> WA
    UI --> CLI_Interface
    WA --> APIServer
    APIServer --> REST
    APIServer --> GRPC
    REST --> HTTPHandler
    GRPC --> GRPCHandler
    CLI_Interface --> CLIApp

    %% Connections to Business Logic
    HTTPHandler --> Usecase
    GRPCHandler --> Usecase
    CLIApp --> Usecase

    %% Business Logic calling Provider Layer
    Usecase -->|"db_access"| DBProvider
    Usecase -->|"external_call"| GeminiProvider

    %% Provider Layer to Persistence and External Services
    DBProvider -->|"queries"| PostDB
    GeminiProvider -->|"calls"| EXT

    %% ETL and Database Setup
    ETL -->|"reads"| CSV
    ETL -->|"populates"| PostDB
    DBConfig -->|"configures"| PostDB

    %% Click Events
    click ETL "https://github.com/richardbertozzo/type-coffee/blob/master/cmd/etl/main.go"
    click CSV "https://github.com/richardbertozzo/type-coffee/blob/master/data/coffee_data.csv"
    click DBConfig "https://github.com/richardbertozzo/type-coffee/tree/master/configs/db"
    click PostDB "https://github.com/richardbertozzo/type-coffee/blob/master/infra/database/postgres.go"
    click APIServer "https://github.com/richardbertozzo/type-coffee/blob/master/cmd/api/main.go"
    click REST "https://github.com/richardbertozzo/type-coffee/blob/master/api/openapi.yaml"
    click GRPC "https://github.com/richardbertozzo/type-coffee/blob/master/api/coffee.proto"
    click Usecase "https://github.com/richardbertozzo/type-coffee/blob/master/coffee/usecase/bestcoffee.go"
    click HTTPHandler "https://github.com/richardbertozzo/type-coffee/blob/master/coffee/handler/http_handler.go"
    click GRPCHandler "https://github.com/richardbertozzo/type-coffee/blob/master/coffee/handler/grpc_handler.go"
    click DBProvider "https://github.com/richardbertozzo/type-coffee/tree/master/coffee/provider"
    click GeminiProvider "https://github.com/richardbertozzo/type-coffee/blob/master/coffee/provider/gemini.go"
    click CLIApp "https://github.com/richardbertozzo/type-coffee/blob/master/cmd/cli/main.go"

    %% Styles
    classDef ui fill:#F9E79F,stroke:#D4AC0D,stroke-width:2px;
    classDef app fill:#AED6F1,stroke:#3498DB,stroke-width:2px;
    classDef business fill:#D5F5E3,stroke:#28B463,stroke-width:2px;
    classDef provider fill:#F5CBA7,stroke:#E67E22,stroke-width:2px;
    classDef persistence fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef external fill:#FADBD8,stroke:#E74C3C,stroke-width:2px;
```
