# joaofnds/go-template architecture

> Architecture diagram of the GitHub repository joaofnds/go-template, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joaofnds/go-template
- Repository: https://github.com/joaofnds/go-template

## Overview

##### Project type and purpose
- This is a Go-based backend service (“monolith” with clear modular boundaries) exposing HTTP APIs, running background workers, managing migrations, and integrating a variety of infrastructure and third-party services.
- It uses Uber’s Fx for dependency injection, Viper for config, Zap for logging, Prometheus for metrics, OpenTelemetry for tracing, Fiber for HTTP, Asynq for background tasks, Watermill for events, and supports multiple storage backends (Postgres via GORM, MongoDB, Redis), plus external authn/authz providers (Casdoor, Casbin), feature flags, etc.

##### File structure
- Top-level entry points:
- cmd/app – HTTP server
- cmd/worker – Asynq worker
- cmd/migrate – database migrations
- “adapter/” – implementations for external systems (HTTP, logger, metrics, tracing, queue, storages, authn/authz, feature flags, validation, etc.)
- Feature modules at root: authn/, authz/, kv/, user/, each with “_http” controllers, “_module” wiring, service, providers, queues, etc.
- “internal/” – shared utilities: context, clock, ID generator, events, helpers
- config/, etc/ – configuration files and default manifests
- test/ – end-to-end and harness code

##### README for additional insights
- Confirms tech stack and architectural patterns (hexagonal: domain modules + adapters)
- Lists integrations: DI, config, logging, metrics, tracing, health checks, feature flags, validation, authn/authz, HTTP, CQRS via Watermill, background tasks via Asynq, migrations via Goose

##### Detail
- Adapter and module is represented or collapsed under its category
- Do not shy away from showing multiple storages—Postgres, Mongo, Redis—and how each module chooses its store
- Where feature flags, validation, authn/authz intercept the request flow

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% DI Container
    FX["Fx DI Container"]:::fx

    %% API Layer
    subgraph "API Layer"
        HTTP["Fiber HTTP Server"]:::api
        Config["Configuration (Viper)"]:::config
        Logger["Logging (Zap)"]:::logger
        Metrics["Metrics (Prometheus)"]:::metrics
        Tracing["Tracing (OpenTelemetry)"]:::tracing
        Health["Health Checks"]:::health
        FeatureFlags["Feature Flags"]:::feature
    end

    %% Application Layer
    subgraph "Application Layer"
        Modules["Domain Modules"]:::module
        subgraph "Authn Module"
            AuthnModule["Authentication Module"]:::module
        end
        subgraph "Authz Module"
            AuthzModule["Authorization Module"]:::module
        end
        subgraph "KV Module"
            KVModule["KV Module"]:::module
        end
        subgraph "User Module"
            UserModule["User Module"]:::module
        end
        Watermill["Event Bus (Watermill)"]:::bus
        AsynqClient["Asynq Client"]:::queue
        AsynqWorker["Background Worker"]:::queue
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        Postgres["Postgres DB (GORM)"]:::db
        Mongo["MongoDB"]:::db
        Redis["Redis Storage"]:::db
        Casdoor["Casdoor (Authn Provider)"]:::external
        Casbin["Casbin (Authz Engine)"]:::external
    end

    %% Migration CLI
    Migrate["Migration CLI"]:::cli
    Goose["Goose Migrations"]:::migrations

    %% Flows
    FX --> HTTP
    FX --> AsynqWorker
    HTTP --> Config
    HTTP --> Logger
    HTTP --> Metrics
    HTTP --> Tracing
    HTTP --> Health
    HTTP --> FeatureFlags
    HTTP --> AuthnModule
    HTTP --> AuthzModule
    HTTP --> KVModule
    HTTP --> UserModule

    AuthnModule --> Postgres
    AuthzModule --> Casbin
    KVModule --> Redis
    UserModule --> Mongo
    UserModule --> Postgres

    AuthnModule -->|"publishes events"| Watermill
    UserModule -->|"publishes events"| Watermill
    Watermill --> AsynqClient
    AsynqClient --> AsynqWorker
    AsynqWorker --> AuthnModule
    AsynqWorker --> UserModule

    HTTP -->|"sync"| Postgres
    HTTP -->|"sync"| Mongo

    Migrate --> Postgres
    Migrate --> Goose

    %% Click Events
    click HTTP "https://github.com/joaofnds/go-template/blob/main/cmd/app/app.go"
    click HTTP "https://github.com/joaofnds/go-template/blob/main/adapter/http/fiber.go"
    click AsynqWorker "https://github.com/joaofnds/go-template/blob/main/cmd/worker/worker.go"
    click AsynqWorker "https://github.com/joaofnds/go-template/blob/main/adapter/queue/server.go"
    click AsynqClient "https://github.com/joaofnds/go-template/blob/main/adapter/queue/client.go"
    click Migrate "https://github.com/joaofnds/go-template/blob/main/cmd/migrate/migrate.go"
    click Goose "https://github.com/joaofnds/go-template/tree/main/cmd/migrate/migrations/"
    click Config "https://github.com/joaofnds/go-template/blob/main/config/config.go"
    click Config "https://github.com/joaofnds/go-template/blob/main/config/config.yaml"
    click Logger "https://github.com/joaofnds/go-template/blob/main/adapter/logger/logger.go"
    click Logger "https://github.com/joaofnds/go-template/blob/main/adapter/logger/config.go"
    click Metrics "https://github.com/joaofnds/go-template/blob/main/adapter/metrics/metrics.go"
    click Metrics "https://github.com/joaofnds/go-template/blob/main/adapter/metrics/config.go"
    click Tracing "https://github.com/joaofnds/go-template/blob/main/adapter/tracing/tracing.go"
    click Tracing "https://github.com/joaofnds/go-template/blob/main/adapter/tracing/config.go"
    click Health "https://github.com/joaofnds/go-template/blob/main/adapter/health/check.go"
    click Health "https://github.com/joaofnds/go-template/blob/main/adapter/health/health_http/controller.go"
    click Health "https://github.com/joaofnds/go-template/blob/main/adapter/health/health_module/module.go"
    click Watermill "https://github.com/joaofnds/go-template/blob/main/adapter/watermill/module.go"
    click Watermill "https://github.com/joaofnds/go-template/blob/main/adapter/watermill/command.go"
    click Watermill "https://github.com/joaofnds/go-template/blob/main/adapter/watermill/event.go"
    click Casdoor "https://github.com/joaofnds/go-template/blob/main/adapter/casdoor/module.go"
    click Casdoor "https://github.com/joaofnds/go-template/blob/main/adapter/casdoor/token_provider.go"
    click Casdoor "https://github.com/joaofnds/go-template/blob/main/adapter/casdoor/user_provider.go"
    click Casbin "https://github.com/joaofnds/go-template/blob/main/adapter/casbin/module.go"
    click Casbin "https://github.com/joaofnds/go-template/blob/main/adapter/casbin/permission_manager.go"
    click Casbin "https://github.com/joaofnds/go-template/blob/main/adapter/casbin/role_manager.go"
    click FeatureFlags "https://github.com/joaofnds/go-template/blob/main/adapter/featureflags/featureflags.go"
    click FeatureFlags "https://github.com/joaofnds/go-template/blob/main/adapter/featureflags/http.go"
    click Postgres "https://github.com/joaofnds/go-template/blob/main/adapter/postgres/postgres.go"
    click Postgres "https://github.com/joaofnds/go-template/blob/main/adapter/postgres/config.go"
    click Mongo "https://github.com/joaofnds/go-template/blob/main/adapter/mongo/mongo.go"
    click Mongo "https://github.com/joaofnds/go-template/blob/main/adapter/mongo/config.go"
    click Redis "https://github.com/joaofnds/go-template/blob/main/adapter/redis/redis.go"
    click Redis "https://github.com/joaofnds/go-template/blob/main/kv/kv_adapter/redis_store.go"
    click AuthnModule "https://github.com/joaofnds/go-template/blob/main/authn/authn_module/module.go"
    click AuthnModule "https://github.com/joaofnds/go-template/blob/main/authn/authn_http/controller.go"
    click AuthzModule "https://github.com/joaofnds/go-template/blob/main/authz/authz_http/module.go"
    click AuthzModule "https://github.com/joaofnds/go-template/blob/main/authz/authz.go"
    click KVModule "https://github.com/joaofnds/go-template/blob/main/kv/kv_module/module.go"
    click KVModule "https://github.com/joaofnds/go-template/blob/main/kv/kv_http/controller.go"
    click UserModule "https://github.com/joaofnds/go-template/blob/main/user/user_module/module.go"
    click UserModule "https://github.com/joaofnds/go-template/blob/main/user/user_http/controller.go"
    click UserModule "https://github.com/joaofnds/go-template/blob/main/user/user_queue/greeter_queue.go"

    %% Styles
    classDef fx fill:#f9f,stroke:#333,stroke-width:2px
    classDef api fill:#bbf,stroke:#333,stroke-width:1px
    classDef config fill:#eef,stroke:#333,stroke-width:1px
    classDef logger fill:#fee,stroke:#333,stroke-width:1px
    classDef metrics fill:#efe,stroke:#333,stroke-width:1px
    classDef tracing fill:#ffe,stroke:#333,stroke-width:1px
    classDef health fill:#ffd,stroke:#333,stroke-width:1px
    classDef feature fill:#ddf,stroke:#333,stroke-width:1px
    classDef module fill:#fcf,stroke:#333,stroke-width:1px
    classDef bus fill:#cff,stroke:#333,stroke-width:1px
    classDef queue fill:#fcc,stroke:#333,stroke-width:1px
    classDef db fill:#ccc,stroke:#333,stroke-width:1px
    classDef external fill:#cfc,stroke:#333,stroke-width:1px
    classDef cli fill:#ddd,stroke:#333,stroke-width:1px
    classDef migrations fill:#bbb,stroke:#333,stroke-width:1px
```
