# emerson-feral/hexagonal-architecture architecture

> Architecture diagram of the GitHub repository emerson-feral/hexagonal-architecture, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/emerson-feral/hexagonal-architecture
- Repository: https://github.com/emerson-feral/hexagonal-architecture

## Overview

##### Project type and purpose
- This is a Node.js/TypeScript backend service organized according to the Hexagonal (Ports & Adapters) architecture.
- Its purpose is to handle user-related use cases (CRUD, business rules) via a clean separation between core domain logic and external adapters (HTTP, persistence).

##### File structure
- Top-level manifests: package.json, tsconfig.json, server entry point (infrastructure/server.ts).
- src/domain: domain entities (User.ts) encapsulating business data and invariants.
- src/application
- ports: interfaces (UserRepository) that abstract persistence behind a stable API
- services: business use‐case implementations (UserService) orchestrating domain logic and ports
- src/infrastructure
- controllers: HTTP adapters (UserController) translating incoming requests into calls on the application layer
- repositories: concrete adapters (InMemoryUserRepository) implementing the ports to store/fetch Users
- server.ts: bootstraps the HTTP server, wires controllers and repository implementations into the application services

##### README for additional insights
- Confirms Hexagonal architecture: separate domain, application (use cases), and infrastructure (adapters) folders.
- Emphasizes clean dependencies inward: infrastructure → application → domain.

a. Main components:
- Domain Core: User entity
- Application Services Layer: UserService
- Ports: UserRepository interface
- Adapters (Infrastructure):
- HTTP Controller (UserController)
- Persistence Adapter (InMemoryUserRepository)
- Entry Point: Server (infrastructure/server.ts)
- External actors: API clients (e.g., Postman, frontend) and Persistence Store (in this case in-memory, but could be DB)
b. Relationships and interactions:
- Clients → HTTP Controller → Application Service → Domain Entity & Port → Persistence Adapter → (back)
- The Server wires the concrete repository into the service via the port interface.
c. Architectural pattern:
- Hexagonal: concentric layers, stable interfaces (ports) at the core boundary, adapters on the outside.
d. Technologies/frameworks:
- Node.js + Express/Koa (or HTTP library) for server.ts
- TypeScript for static typing
- In-memory repository (to be swapped with a real database adapter later)

##### Detailed capture of architectural elements
- Don’t just lump “backend” together—split into Domain, Use Cases, Ports, Controllers, Repositories, Server.
- Explicitly show the inversion of control: Application services depend on the UserRepository interface (not the concrete repository).
- That swapping out InMemoryUserRepository for a SQL or NoSQL adapter is as easy as wiring a different adapter in server.ts.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Actors
    APIClient["API Client"]:::external
    PersistenceStore[(Database)]:::external

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        Server["Server (bootstrap)"]:::infra
        UserController["UserController (HTTP Adapter)"]:::infra
        InMemoryRepo["InMemoryUserRepository (Persistence Adapter)"]:::infra
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        UserService["UserService (Application Service)"]:::app
        UserRepoInt["UserRepository (Port Interface)"]:::app
    end

    %% Domain Layer
    subgraph "Domain Layer"
        direction TB
        UserEntity["User (Domain Entity)"]:::domain
    end

    %% Connections
    APIClient -->|calls API| UserController
    UserController -->|invokes| UserService
    UserService -->|uses port| UserRepoInt
    UserRepoInt -->|implemented by| InMemoryRepo
    InMemoryRepo -->|persists to| PersistenceStore
    Server -->|wires| UserController
    Server -->|wires| UserService
    Server -->|provides impl| InMemoryRepo

    %% Click Events
    click UserEntity "https://github.com/emerson-feral/hexagonal-architecture/blob/main/src/domain/User.ts"
    click UserService "https://github.com/emerson-feral/hexagonal-architecture/blob/main/src/application/services/UserService.ts"
    click UserRepoInt "https://github.com/emerson-feral/hexagonal-architecture/blob/main/src/application/ports/UserRepository.ts"
    click UserController "https://github.com/emerson-feral/hexagonal-architecture/blob/main/src/infrastructure/controllers/UserController.ts"
    click InMemoryRepo "https://github.com/emerson-feral/hexagonal-architecture/blob/main/src/infrastructure/repositories/InMemoryUserRepository.ts"
    click Server "https://github.com/emerson-feral/hexagonal-architecture/blob/main/src/infrastructure/server.ts"

    %% Styles
    classDef domain fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef app fill:#add8e6,stroke:#333,stroke-width:1px
    classDef infra fill:#90ee90,stroke:#333,stroke-width:1px
    classDef external fill:#ffa500,stroke:#333,stroke-width:1px
```
