How richardbertozzo/type-coffee works
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).