How rafael-piovesan/go-rocket-ride works
Project Type and Purpose
• This project is a backend API service written in Go, inspired by Stripe’s Rocket Rides demo. It implements idempotency keys in a context of Clean Architecture to ensure atomicity in API operations.
• The goal is to allow clients to safely reissue API requests (with the same idempotency key) without performing duplicate operations, especially when calling out to external services like Stripe.
File Structure
• Top-Level Directories:
• api: Contains the HTTP transport layer with handlers and middlewares (e.g., idempotency, user authentication, error handling).
• cmd: Holds the main entry point (main.go) to launch the API server.
• datastore: Implements Postgres data access using an ORM (Bun) and includes a unit-of-work (UoW) pattern.
• db: Contains database migrations and fixtures for setting up and testing the database schema.
• entity: Defines the domain entities and their related types (e.g., Ride, Audit, Idempotency Key).
• usecase: Encapsulates the business logic (application use-cases).
• pkg: Provides wrappers and utilities for config management, HTTP server setup, Postgres connections, migrations, and integrations with stripe-mock.
• mocks: Provides generated mocks for unit tests.
• This folder hierarchy follows Clean Architecture principles by separating the concerns of transport (HTTP layer), business logic, and persistence.
Main Components and Their Relationships
• API Layer:
• This is implemented in the api directory and exposed via HTTP. It contains handlers that receive requests, apply middleware (e.g., for idempotency handling, entity authentication), and forward the request processing to the underlying business logic.
• Use Case Layer:
• Found in the usecase directory, this layer represents the business logic (e.g., handling ride requests). It processes validated input from the API layer and orchestrates data operations.
• Domain/Entity Layer:
• The entity directory encapsulates vital domain models such as rides, users, audits, and idempotency keys.
• Data Persistence Layer:
• The datastore package implements the repository details using the Bun ORM along with a unit-of-work mechanism (located within datastore/uow) that ensures atomic database operations.
• The db directory manages migrations and fixtures to maintain versioned database schemas and test data.
• Utility and Infrastructure Components:
• The pkg directory offers configuration management (env var handling), Postgres connection handling, HTTP server utilities, migration helpers, and Stripe-mock integration.
• The external dependency on Stripe’s API (mocked via stripe-mock) is also an important part of the architecture.
• Commands:
• The cmd/api directory contains the “main” application which ties together the API server, configuration initialization, and the wiring of components.
Key Architectural Patterns
• Clean Architecture: Clearly decouples presentation (HTTP API) from business logic (usecase) and persistence (datastore). Domain entities are defined separately.
• Unit-of-Work: In the datastore/uow package, encapsulates the atomicity of database operations, ensuring all changes made during a transaction are committed together.
• Middleware Usage: In the API layer, various middleware components (for idempotency, origin IP, user context, etc.) are applied to govern request handling and repeatability.
• Dependency Injection & External Service Integration: Use case layer and infrastructure (pkg and datastore) appear to be connected using DI patterns, facilitating integration with external services such as Stripe via stripe-mock.