# samverrall/hex-structure architecture

> Architecture diagram of the GitHub repository samverrall/hex-structure, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/samverrall/hex-structure
- Repository: https://github.com/samverrall/hex-structure

## Overview

##### Project type and purpose
- This is a Golang HTTP service structured around a hexagonal (ports & adapters) architecture.
- Its primary responsibility is handling user‐related operations (e.g., account creation) via a web interface and persisting data in Postgres.

##### File structure
- Top‐level “cmd/web”: entrypoint (main.go) that starts the web server.
- internal/adapters/primary/web: HTTP layer (routes, server, handlers, view templates).
- internal/adapters/secondary/postgres: Postgres implementation of the persistence port.
- internal/ports: definitions of the interfaces (e.g., UserRepository, UserService) that decouple core logic from adapters.
- internal/core:
- domain/user: entities and value objects (User, Name)
- services/users: application/business logic (CreateApplication)
- services/errors: shared error types

##### README
- States “hexagonal architectured Golang service”

##### Essential elements to capture
- Call out the “cmd/web” as the application launcher pointing into the Web Adapter
- Template rendering in the Web Adapter (views/layouts, pages, partials)
- How internal/ports defines the interface boundary

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Entrypoint
    subgraph "Application Entrypoint"
        Entrypoint["cmd/web/main.go"]:::entry
    end

    %% Primary Adapter: Web
    subgraph "Web Adapter (Primary)" 
        direction TB
        Server["server.go"]:::primary
        Routes["routes.go"]:::primary
        Options["options.go"]:::primary
        Handler["createaccount.go"]:::primary
        subgraph "Views/Templates"
            Layouts["main.html"]:::primary
            Pages["index.html"]:::primary
            Partials["login.html"]:::primary
        end
    end

    %% Ports
    subgraph "Ports (Interfaces)"
        boundary((UserPort)):::port
    end

    %% Core
    subgraph "Application Core"
        direction TB
        subgraph "Domain Model"
            UserEntity["user.go"]:::core
            NameVO["name.go"]:::core
        end
        subgraph "Domain Services"
            CreateApp["createapplication.go"]:::core
            UsersSvc["users.go"]:::core
        end
        Errors["errors.go"]:::core
    end

    %% Secondary Adapter: Persistence
    subgraph "Persistence Adapter (Secondary)"
        PostgresAdapter["user.go"]:::secondary
    end

    %% External Database
    PostgresDB["Postgres DB"]:::db

    %% Connections
    Entrypoint -->|"starts"| Server
    Server -->|"uses"| Routes
    Server -->|"load options"| Options
    Routes -->|"route to"| Handler
    Handler -->|"CreateUser()"| boundary
    boundary -->|"calls CreateUser()"| CreateApp
    CreateApp -->|"uses UserRepository"| PostgresAdapter
    PostgresAdapter -->|"Exec SQL"| PostgresDB
    PostgresDB -->|"Result"| PostgresAdapter
    PostgresAdapter -->|"returns User"| CreateApp
    CreateApp -->|"response"| Handler
    Handler -->|"render"| Layouts
    Handler -->|"render"| Pages
    Handler -->|"render"| Partials

    %% Click Events
    click Entrypoint "https://github.com/samverrall/hex-structure/blob/main/cmd/web/main.go"
    click Server "https://github.com/samverrall/hex-structure/blob/main/internal/adapters/primary/web/server.go"
    click Routes "https://github.com/samverrall/hex-structure/blob/main/internal/adapters/primary/web/routes.go"
    click Options "https://github.com/samverrall/hex-structure/blob/main/internal/adapters/primary/web/options.go"
    click Handler "https://github.com/samverrall/hex-structure/blob/main/internal/adapters/primary/web/users/createaccount.go"
    click Layouts "https://github.com/samverrall/hex-structure/blob/main/internal/adapters/primary/web/views/layouts/main.html"
    click Pages "https://github.com/samverrall/hex-structure/blob/main/internal/adapters/primary/web/views/pages/index.html"
    click Partials "https://github.com/samverrall/hex-structure/blob/main/internal/adapters/primary/web/views/partials/login.html"
    click boundary "https://github.com/samverrall/hex-structure/blob/main/internal/ports/user.go"
    click UserEntity "https://github.com/samverrall/hex-structure/blob/main/internal/core/domain/user/user.go"
    click NameVO "https://github.com/samverrall/hex-structure/blob/main/internal/core/domain/user/name.go"
    click CreateApp "https://github.com/samverrall/hex-structure/blob/main/internal/core/services/users/createapplication.go"
    click UsersSvc "https://github.com/samverrall/hex-structure/blob/main/internal/core/services/users/users.go"
    click Errors "https://github.com/samverrall/hex-structure/blob/main/internal/core/services/errors.go"
    click PostgresAdapter "https://github.com/samverrall/hex-structure/blob/main/internal/adapters/secondary/postgres/user.go"

    %% Styles
    classDef entry fill:#f9f,stroke:#333,stroke-width:1px
    classDef primary fill:#cce5ff,stroke:#004085,stroke-width:1px
    classDef port fill:#fff3cd,stroke:#856404,stroke-width:1px,stroke-dasharray: 5 5
    classDef core fill:#d4edda,stroke:#155724,stroke-width:1px
    classDef secondary fill:#ffe5b4,stroke:#ff8c00,stroke-width:1px
    classDef db fill:#e2e3e5,stroke:#6c757d,stroke-width:1px,stroke-dasharray: 2 2
```
