How yael-castro/goarch works
Main Components
• Binaries: The project is built into two separate executables found under the “cmd” directory:
• users-http: Handles incoming HTTP API requests.
• users-relay: Manages reading messages and relaying them to other systems.
• Business Layer: Under “internal/app/business”, you have the core use cases, business rules, domain models, and ports that represent the central logic.
• Adapters:
• “input” adapters (in “internal/app/input”): Implement drivers that handle external signals. For users-http, these are HTTP-related adapters (handlers, routes, etc.); for command-based or relay signals, there is a different handling.
• “output” adapters (in “internal/app/output”): Implement the driven parts such as:
• Postgres adapters (database interactions).
• Kafka adapters (messaging and notifications).
• Additional decorators implementing circuit breaker and retries (enhancing reliability).
• Dependency/DI Container: Found in “internal/container”. This sets up the wiring between the various components according to the hexagonal architecture.
• Supporting / Global Code: Under “pkg”, utility libraries and API wrappers (like pkg/userapi) are used across the project.
Relationships and Interactions
• External Clients & External Systems communicate with the users-http binary via HTTP requests (as per the REST API defined by the OpenAPI spec).
• When a request is received:
• It’s routed through the “input/http” adapters, which then invoke the appropriate business use cases.
• The business layer (inside “internal/app/business”) processes the request, applying domain logic and calling out to defined ports.
• Business Logic interacts with the “output” adapters:
• For persistence: communication with the Postgres database (using SQL scripts under “scripts/sql” and code in “internal/app/output/postgres”).
• For message production: sending notifications via Kafka (handled in “internal/app/output/kafka”).
• The users-relay binary operates as a background process:
• It reads messages from a queue or data source and uses the relay use case (see “internal/app/business/relay_case.go”) to then process or forward these messages.
• The DI container ensures that these various components (input, output, business logic) are properly wired and instantiated.
Architectural Patterns and Design Principles
• Hexagonal Architecture (Ports and Adapters): The project is segmented into “business” (core use cases), “input” (driving adapters), and “output” (driven adapters). This separation makes it easy to plug in or switch external interfaces.
• Micro-Binary Approach: The decision to compile two separate binaries (one for handling HTTP and another for relaying messages) illustrates the “compile only what is required” idea.
• Resilience and Scalability Patterns: The presence of a circuit breaker (in the output/decorator) and patterns for horizontal scaling and graceful shutdown are part of the design.