How dyoshyy/curlarc-service works
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).