# dhontecillas/hfw architecture

> Architecture diagram of the GitHub repository dhontecillas/hfw, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dhontecillas/hfw
- Repository: https://github.com/dhontecillas/hfw

## Overview

##### Main Components

a) Core Framework Components:
- Web Server Layer (Gin-Gonic)
- Authentication System
- Configuration Management
- Database Integrations (PostgreSQL & Redis)
- Observability Stack
- Mailer System
- Internationalization (i18n)
- Notification System

b) External Services:
- PostgreSQL Database
- Redis Cache
- Email Services (SendGrid, Mailtrap, etc.)
- Observability Services (Prometheus, Grafana, Tempo)

**┌─ Application Layer ─────────────────────────────────────┐**
- Web Apps / API Clients                                  │
- ┘
- ↓
**┌─ Framework Layer ──────────────────────────────────────┐**
- ┌─ Web Layer ─┐  ┌─ Auth Layer ┐  ┌─ API Layer ─┐     │
- Gin-Gonic   │  │ Users       │  │ Token API   │     │
- Sessions    │  │ CSRF        │  │ REST APIs   │     │
- ┘  └─────────────┘  └────────────┘      │

- ┌─ Core Services ────────────────────────────────────┐│
- Config │ Mailer │ i18n │ Notifications │ Bundler  ││
- ┘│
- ┘
- ↓
**┌─ Observability Layer ────────────────────────────────┐**
- ┌─────────┐  ┌──────────┐  ┌────────┐  ┌─────────┐  │
- Metrics │  │ Logging  │  │ Traces │  │ Sentry  │  │
- ┘  └──────────┘  └────────┘  └─────────┘  │
- ┘
- ↓
**┌─ Storage Layer ───────────────────────────────────────┐**
- PostgreSQL (Primary Storage)   Redis (Cache/Sessions) │
- ┘

##### Important Details

a) Component Interactions:
- How the web layer interfaces with auth and API layers
- Data flow between storage systems and services
- Demonstrate how observability cuts across all layers

b) Key Features:
- ULID/UUID handling for IDs
- Email notification flow
- Session management
- Configuration management
- Internationalization support

##### Specific Implementation Notes

- Relationship between `pkg/ginfw` and the web server layer
- How `pkg/obs` connects to various observability tools
- Demonstrate the mailer system's multiple implementations
- How the bundler package fits into the deployment process

##### External Service Integration

- Email providers (SendGrid, Mailtrap, etc.)
- Observability tools (Prometheus, Grafana)
- Database systems (PostgreSQL, Redis)

##### Notes for Implementation

- Version compatibility information
- Configuration requirements
- Security boundaries

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles
    classDef app fill:#f9f,stroke:#333,stroke-width:2px
    classDef framework fill:#bbf,stroke:#333,stroke-width:2px
    classDef storage fill:#ddd,stroke:#333,stroke-width:2px
    classDef external fill:#9d9,stroke:#333,stroke-width:2px
    classDef security fill:#fb8,stroke:#333,stroke-width:2px
    classDef observability fill:#c9f,stroke:#333,stroke-width:2px
    classDef core fill:#adf,stroke:#333,stroke-width:2px

    %% Application Layer
    subgraph AppLayer["Application Layer"]
        WebApps["Web Applications"]:::app
        APIClients["API Clients"]:::app
    end

    %% Framework Layer
    subgraph FrameworkLayer["Framework Layer"]
        %% Web Layer
        subgraph WebLayer["Web Layer"]
            GinWeb["Gin-Gonic Server"]
            Sessions["Session Management"]
            WAPI["Web API Layer"]
            WTokenAPI["Token API Interface"]
            WUsers["User Interface"]
        end

        %% Auth Layer
        subgraph AuthLayer["Auth Layer"]
            Auth["Authentication"]
            CSRF["CSRF Protection"]
            Users["User Management"]
        end

        %% Core Services
        subgraph CoreServices["Core Services"]
            Config["Configuration"]
            Mailer["Mailer System"]
            I18n["Internationalization"]
            Notifications["Notifications"]
            TokenAPI["Token API"]
            ExtDeps["External Dependencies"]
        end
    end

    %% Observability Layer
    subgraph ObsLayer["Observability Layer"]
        Metrics["Metrics"]
        Logging["Logging"]
        Traces["Tracing"]
        Sentry["Sentry"]
    end

    %% Storage Layer
    subgraph StorageLayer["Storage Layer"]
        PostgreSQL["PostgreSQL DB"]:::storage
        Redis["Redis Cache"]:::storage
    end

    %% Relationships
    AppLayer --> WebLayer
    WebLayer --> AuthLayer
    WebLayer --> CoreServices
    AuthLayer --> CoreServices
    CoreServices --> StorageLayer
    FrameworkLayer --> ObsLayer
    ObsLayer --> StorageLayer

    %% Click Events
    click GinWeb "https://github.com/dhontecillas/hfw/tree/main/pkg/ginfw"
    click Auth "https://github.com/dhontecillas/hfw/tree/main/pkg/ginfw/auth"
    click Config "https://github.com/dhontecillas/hfw/tree/main/pkg/config"
    click PostgreSQL "https://github.com/dhontecillas/hfw/blob/main/pkg/db/db.go"
    click Redis "https://github.com/dhontecillas/hfw/blob/main/pkg/db/redis.go"
    click Metrics "https://github.com/dhontecillas/hfw/tree/main/pkg/obs/metrics"
    click Logging "https://github.com/dhontecillas/hfw/tree/main/pkg/obs/logs"
    click Traces "https://github.com/dhontecillas/hfw/tree/main/pkg/obs/traces"
    click Mailer "https://github.com/dhontecillas/hfw/tree/main/pkg/mailer"
    click I18n "https://github.com/dhontecillas/hfw/tree/main/pkg/i18n"
    click Notifications "https://github.com/dhontecillas/hfw/tree/main/pkg/notifications"
    click TokenAPI "https://github.com/dhontecillas/hfw/tree/main/pkg/tokenapi"
    click Users "https://github.com/dhontecillas/hfw/tree/main/pkg/usecases/users"
    click Sessions "https://github.com/dhontecillas/hfw/tree/main/pkg/ginfw/web/session"
    click WAPI "https://github.com/dhontecillas/hfw/tree/main/pkg/ginfw/web/wapi"
    click WTokenAPI "https://github.com/dhontecillas/hfw/tree/main/pkg/ginfw/web/wtokenapi"
    click WUsers "https://github.com/dhontecillas/hfw/tree/main/pkg/ginfw/web/wusers"
    click ExtDeps "https://github.com/dhontecillas/hfw/tree/main/pkg/extdeps"

    %% Legend
    subgraph Legend["Legend"]
        L1["Application Component"]:::app
        L2["Framework Component"]:::framework
        L3["Storage System"]:::storage
        L4["External Service"]:::external
        L5["Security Component"]:::security
        L6["Observability Component"]:::observability
        L7["Core Service"]:::core
    end

    %% Style Applications
    class WebApps,APIClients app
    class GinWeb,Sessions,WAPI,WTokenAPI,WUsers framework
    class Auth,CSRF,Users security
    class Config,Mailer,I18n,Notifications,TokenAPI,ExtDeps core
    class Metrics,Logging,Traces,Sentry observability
    class PostgreSQL,Redis storage
```
