# yael-castro/goarch architecture

> Architecture diagram of the GitHub repository yael-castro/goarch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yael-castro/goarch
- Repository: https://github.com/yael-castro/goarch

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    EC["External Clients"]:::external
    MS["Message Source"]:::external

    %% Services Subgraph
    subgraph "Services"
        UHTTP["users-http Service"]:::service
        URELAY["users-relay Service"]:::service
    end

    %% Adapters Subgraph
    subgraph "Adapters"
        HTTPAD["HTTP Input Adapter"]:::adapter
        CMDAD["Command/Relay Input Adapter"]:::adapter
        DECAD["Output Decorators (Circuit Breaker & Retries)"]:::adapter
        DBAD["Database Adapter (Postgres)"]:::adapter
        KAFKAAD["Messaging Adapter (Kafka)"]:::adapter
    end

    %% Core Subgraph
    subgraph "Core"
        BIZ["Business Logic"]:::business
        DI["DI Container"]:::di
    end

    %% Supporting Subgraph
    subgraph "Supporting"
        UTIL["Utility Libraries"]:::support
    end

    %% Connections
    EC -->|"calls"| UHTTP
    UHTTP -->|"routes to"| HTTPAD
    MS -->|"feeds"| CMDAD
    URELAY -->|"triggers"| CMDAD
    HTTPAD -->|"invokes"| BIZ
    CMDAD -->|"invokes"| BIZ
    BIZ -->|"delegates"| DECAD
    DECAD -->|"persists via"| DBAD
    DECAD -->|"notifies via"| KAFKAAD

    %% DI Container wiring
    DI -->|"configures"| HTTPAD
    DI -->|"configures"| CMDAD
    DI -->|"wires"| BIZ
    DI -->|"wires"| DECAD

    %% Supporting libraries influence
    UTIL -->|"assists"| BIZ
    UTIL -->|"assists"| DBAD

    %% Click Events
    click UHTTP "https://github.com/yael-castro/goarch/blob/master/cmd/users-http/main.go"
    click URELAY "https://github.com/yael-castro/goarch/blob/master/cmd/users-relay/main.go"
    click BIZ "https://github.com/yael-castro/goarch/tree/master/internal/app/business"
    click HTTPAD "https://github.com/yael-castro/goarch/tree/master/internal/app/input/http"
    click CMDAD "https://github.com/yael-castro/goarch/blob/master/internal/app/input/command/relay.go"
    click DBAD "https://github.com/yael-castro/goarch/tree/master/internal/app/output/postgres"
    click KAFKAAD "https://github.com/yael-castro/goarch/tree/master/internal/app/output/kafka"
    click DECAD "https://github.com/yael-castro/goarch/tree/master/internal/app/output/decorator"
    click DI "https://github.com/yael-castro/goarch/tree/master/internal/container"
    click UTIL "https://github.com/yael-castro/goarch/tree/master/pkg"

    %% Styles
    classDef service fill:#FFF4C2,stroke:#D58512,stroke-width:2px;
    classDef adapter fill:#C6E2FF,stroke:#1A8CFF,stroke-width:2px;
    classDef business fill:#D0F0C0,stroke:#228B22,stroke-width:2px;
    classDef di fill:#F8D7DA,stroke:#C82333,stroke-width:2px;
    classDef external fill:#FFEeba,stroke:#856404,stroke-width:2px;
    classDef support fill:#E6CCFF,stroke:#9933FF,stroke-width:2px;
```
