# elisasre/go-common architecture

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

- Interactive diagram: https://gitdiagram.com/elisasre/go-common
- Repository: https://github.com/elisasre/go-common

## Overview

##### Project type and purpose
- This is a shared Golang utility library (not a running app), meant to be imported into Elisa SRE services.
- It provides common building blocks: authentication, HTTP helpers, logging, metrics, middleware, service modules, SQL utilities, etc.

##### File structure
- Top‐level “v2” directory houses all Go code, organized by feature area:
- auth (token management, stores, caching)
- clienv (environment config)
- httputil (HTTP request helpers)
- log (structured logging)
- metrics (counters, gauges)
- mfa (multi‐factor auth helpers)
- middleware (CSRF, rate-limit)
- netutil (TCP helpers)
- sentryutil (error reporting)
- service/module (pluggable service lifecycles: HTTP server, cron, leader election, tracing, watcher, signal handling, etc.)
- sqlutil & sqlxutil (database drivers, IAM auth)
- utils.go, must.go (misc helpers)
- There are also integrationtest and golden test harnesses, plus magefiles for build tasks.

##### Extract insights from the README
- Confirms purpose as a common Golang library for shared SRE code.

##### Sketch the main components and their relationships
a. Main Components
- Client‐side configuration: clienv
- Core utilities: utils, must
- Authentication: auth (with cache + stores) + mfa
- HTTP helpers: httputil + middleware
- Logging & Observability: log + metrics + sentryutil + service/module/tracerprovider/prom
- Service framework: service/module (HTTP server, cronrunner, siglistener, leaderelection, ticker, watcher)
- Networking: netutil
- Database: sqlutil + sqlxutil
- Integration Tests: integrationtest (external Docker Compose)
b. Relationships & Interactions
- A consuming service → imports clienv to load config → uses service/module to wire up lifecycle → registers HTTP handlers (httputil + middleware) → logs via log → reports metrics via metrics/prom → captures errors via sentryutil → relies on auth for token checks → persists data via sqlxutil/sqlutil → uses netutil for TCP operations → uses mfa for step-up auth.
- Integrationtest sits outside runtime flow but depends on service modules + Docker.
c. Architectural Patterns
- Modular, layered library: utilities at the bottom, then cross-cutting concerns (auth, HTTP, logging), then service modules on top.
- “Plug-and-play” modules: each service module implements a common interface and can be composed.
- Separation of concerns: auth stores vs cache vs token logic.
d. Key Technologies & Frameworks
- Go modules (v2)
- PostgreSQL (auth store)
- Docker Compose (integration tests)
- Mage for build automation

##### Detailed checklist
- Optionally, annotate common interfaces (e.g., “module.Module”).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Consumer Service
    subgraph "Consumer Service" 
        direction TB
        ConsumerService["Consumer Service"]:::external
    end

    %% Utilities Layer
    subgraph "Utilities" 
        direction TB
        Utils["utils.go"]:::blue
        Must["must.go"]:::blue
    end

    %% Configuration Layer
    subgraph "Configuration" 
        direction TB
        ClientEnv["clienv/env.go"]:::green
    end

    %% Authentication Layer
    subgraph "Authentication" 
        direction TB
        Auth["auth/auth.go"]:::green
        Token["auth/token.go"]:::green
        AuthCache["auth/cache/cache.go"]:::green
        AuthStoreMem["auth/store/memory/memory.go"]:::green
        AuthStorePG["auth/store/postgres/postgres.go"]:::green
    end

    %% MFA Layer
    MFA["mfa/mfa.go"]:::green

    %% HTTP Helpers Layer
    subgraph "HTTP Helpers" 
        direction TB
        HTTPUtilReq["httputil/request.go"]:::green
        HTTPUtilUtil["httputil/util.go"]:::green
    end

    %% Middleware Layer
    subgraph "Middleware" 
        direction TB
        CSRF["middleware/csrf/csrf.go"]:::green
        RateLimit["middleware/ratelimit/ratelimit.go"]:::green
    end

    %% Observability Layer
    subgraph "Observability" 
        direction TB
        Log["log/logger.go"]:::orange
        Metrics["metrics/metrics.go"]:::orange
        SentryUtil["sentryutil/sentry.go"]:::orange
    end

    %% Service Modules Layer
    subgraph "Service Modules" 
        direction TB
        CronRunner["service/module/cronrunner/runner.go"]:::purple
        HTTPServer["service/module/httpserver/server.go"]:::purple
        HTTPProm["service/module/httpserver/prom/prom.go"]:::purple
        HTTPPprof["service/module/httpserver/pprof/pprof.go"]:::purple
        LeaderElection["service/module/leaderelection/leaderelection.go"]:::purple
        ServiceSentry["service/module/sentry/sentry.go"]:::purple
        SigListener["service/module/siglistener/signal.go"]:::purple
        Ticker["service/module/ticker/ticker.go"]:::purple
        TracerProvider["service/module/tracerprovider/tracerprovider.go"]:::purple
        Watcher["service/module/watcher/watcher.go"]:::purple
    end

    %% Infrastructure Layer
    subgraph "Infrastructure" 
        direction TB
        NetUtil["netutil/tcp.go"]:::gray
        SQLUtilIAM["sqlutil/iam_auth.go"]:::gray
        SQLUtilRefresh["sqlutil/auth_refresh_driver.go"]:::gray
        SQLXUtil["sqlxutil/sqlxutil.go"]:::gray
    end

    %% Tests Layer
    subgraph "Tests" 
        direction TB
        IntegrationTest["integrationtest/compose.go"]:::external
        GoldenTest["golden/file.go"]:::external
    end

    %% Dependencies
    ConsumerService -->|imports| ClientEnv
    ConsumerService -->|uses| CronRunner
    ConsumerService -->|uses| HTTPServer
    ConsumerService -->|uses| LeaderElection

    CronRunner -->|calls| Log
    HTTPServer -->|registers handlers| HTTPUtilReq
    HTTPServer -->|uses middleware| CSRF
    HTTPServer -->|uses middleware| RateLimit
    HTTPServer -->|exposes metrics| HTTPProm
    HTTPServer -->|exposes pprof| HTTPPprof

    CronRunner -->|logs| Log
    CronRunner -->|metrics| Metrics
    CronRunner -->|errors| SentryUtil

    LeaderElection -->|logs| Log
    SigListener -->|signals| ConsumerService
    Ticker -->|ticks| ConsumerService
    Watcher -->|watches| ConsumerService

    ServiceSentry -->|hooks| SentryUtil
    TracerProvider -->|provides| Metrics

    ServiceSentry -->|errors| SentryUtil

    %% Cross-layer utils
    CronRunner -->|utils| Utils
    HTTPServer -->|utils| Utils
    CronRunner -->|must| Must
    HTTPServer -->|must| Must

    %% Auth flows
    ConsumerService -->|auth checks| Auth
    Auth -->|uses cache| AuthCache
    Auth -->|stores| AuthStoreMem
    Auth -->|stores| AuthStorePG
    Auth -->|manages| Token

    ConsumerService -->|step-up| MFA

    %% Infrastructure usage
    ConsumerService -->|tcp| NetUtil
    ConsumerService -->|db| SQLXUtil
    SQLXUtil -->|driver| SQLUtilIAM
    SQLXUtil -->|driver| SQLUtilRefresh

    %% Tests dependencies
    IntegrationTest -.->|builds| ConsumerService
    IntegrationTest -.->|docker compose| Docker
    GoldenTest -.->|verifies| Utils

    %% Click Events
    click ClientEnv "https://github.com/elisasre/go-common/blob/main/v2/clienv/env.go"
    click Utils "https://github.com/elisasre/go-common/blob/main/v2/utils.go"
    click Must "https://github.com/elisasre/go-common/blob/main/v2/must/must.go"
    click Auth "https://github.com/elisasre/go-common/blob/main/v2/auth/auth.go"
    click AuthCache "https://github.com/elisasre/go-common/blob/main/v2/auth/cache/cache.go"
    click AuthStoreMem "https://github.com/elisasre/go-common/blob/main/v2/auth/store/memory/memory.go"
    click AuthStorePG "https://github.com/elisasre/go-common/blob/main/v2/auth/store/postgres/postgres.go"
    click Token "https://github.com/elisasre/go-common/blob/main/v2/auth/token.go"
    click MFA "https://github.com/elisasre/go-common/blob/main/v2/mfa/mfa.go"
    click HTTPUtilReq "https://github.com/elisasre/go-common/blob/main/v2/httputil/request.go"
    click HTTPUtilUtil "https://github.com/elisasre/go-common/blob/main/v2/httputil/util.go"
    click CSRF "https://github.com/elisasre/go-common/blob/main/v2/middleware/csrf/csrf.go"
    click RateLimit "https://github.com/elisasre/go-common/blob/main/v2/middleware/ratelimit/ratelimit.go"
    click Log "https://github.com/elisasre/go-common/blob/main/v2/log/logger.go"
    click Metrics "https://github.com/elisasre/go-common/blob/main/v2/metrics/metrics.go"
    click SentryUtil "https://github.com/elisasre/go-common/blob/main/v2/sentryutil/sentry.go"
    click CronRunner "https://github.com/elisasre/go-common/blob/main/v2/service/module/cronrunner/runner.go"
    click HTTPServer "https://github.com/elisasre/go-common/blob/main/v2/service/module/httpserver/server.go"
    click HTTPProm "https://github.com/elisasre/go-common/blob/main/v2/service/module/httpserver/prom/prom.go"
    click HTTPPprof "https://github.com/elisasre/go-common/blob/main/v2/service/module/httpserver/pprof/pprof.go"
    click LeaderElection "https://github.com/elisasre/go-common/blob/main/v2/service/module/leaderelection/leaderelection.go"
    click ServiceSentry "https://github.com/elisasre/go-common/blob/main/v2/service/module/sentry/sentry.go"
    click SigListener "https://github.com/elisasre/go-common/blob/main/v2/service/module/siglistener/signal.go"
    click Ticker "https://github.com/elisasre/go-common/blob/main/v2/service/module/ticker/ticker.go"
    click TracerProvider "https://github.com/elisasre/go-common/blob/main/v2/service/module/tracerprovider/tracerprovider.go"
    click Watcher "https://github.com/elisasre/go-common/blob/main/v2/service/module/watcher/watcher.go"
    click NetUtil "https://github.com/elisasre/go-common/blob/main/v2/netutil/tcp.go"
    click SQLUtilIAM "https://github.com/elisasre/go-common/blob/main/v2/sqlutil/iam_auth.go"
    click SQLUtilRefresh "https://github.com/elisasre/go-common/blob/main/v2/sqlutil/auth_refresh_driver.go"
    click SQLXUtil "https://github.com/elisasre/go-common/blob/main/v2/sqlxutil/sqlxutil.go"
    click IntegrationTest "https://github.com/elisasre/go-common/blob/main/v2/integrationtest/compose.go"
    click GoldenTest "https://github.com/elisasre/go-common/blob/main/v2/golden/file.go"

    %% Styles
    classDef blue fill:#cce5ff,stroke:#005cbf,color:#005cbf
    classDef green fill:#d4edda,stroke:#155724,color:#155724
    classDef orange fill:#ffe5b4,stroke:#ff8c00,color:#ff8c00
    classDef purple fill:#e2e2f1,stroke:#6f42c1,color:#6f42c1
    classDef gray fill:#f8f9fa,stroke:#6c757d,color:#6c757d
    classDef external fill:#ffffff,stroke:#343a40,color:#343a40,stroke-dasharray: 5 5
```
