# joaofnds/pbd architecture

> Architecture diagram of the GitHub repository joaofnds/pbd, 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/pbd
- Repository: https://github.com/joaofnds/pbd

## Overview

##### Project type and purpose
- This is a single Go “service” (monolith) that exposes an HTTP API and runs background workers.
- It follows a hexagonal (ports-and-adapters) architecture: core domain modules (user, order, calendar, etc.), each with its own “module,” “service,” “repository,” “HTTP controller” and “adapter” packages.
- It orchestrates dependencies via Uber’s Fx, reads configuration via Viper, logs with Zap, collects metrics with Prometheus, traces with OpenTelemetry, and integrates with third-party auth (Casdoor/Casbin) and feature-flag services.

##### File structure
- cmd/app: the main HTTP server process
- cmd/worker: background worker process
- config/: Viper-driven configuration
- adapter/: all external interfaces—HTTP (Fiber), metrics, logging, tracing, persistence (Postgres via Gorm, Mongo, Redis), queue client/server (Asynq), message bus (Watermill), authn (Casdoor), authz (Casbin), feature flags
- domain packages (user, order, booking, calendar, customer, event, phone, kv, worker, authn, authz, etc.): each defines DTOs, services, repositories, HTTP controllers, module wiring
- test/: e2e and unit-test harnesses
- Dockerfile & docker-compose: containerization & local infra for Postgres, Redis, Mongo, Prometheus, Grafana

##### Key points from README
- Core features: DI (Fx), config (Viper), logging (Zap), metrics (Prom), tracing (OTel), health checks, feature flags, validation, HTTP (Fiber), CQRS/eventing (Watermill), background tasks (Asynq), testing (Ginkgo/Gomega), migrations (Goose), storage adapters, CI/CD / semantic versioning, distroless container

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Processes
    subgraph "API Service (cmd/app)"
        direction TB
        AppDI["Dependency Injection (Fx)"]:::core
        Config["Configuration (Viper)"]:::infra
        HTTP["HTTP Adapter (Fiber)"]:::adapter
        Health["Health-Check Adapter"]:::adapter
        Validation["Validation"]:::adapter
        AuthN_MW["AuthN Middleware"]:::adapter
        AuthZ_MW["AuthZ Middleware"]:::adapter
        FeatureFlag["Feature Flags Service"]:::adapter
        Logging["Logging (Zap)"]:::adapter
        Metrics["Metrics (Prometheus)"]:::adapter
        Tracing["Tracing (OpenTelemetry)"]:::adapter

        subgraph "Domain Core Modules"
            direction TB
            UserDomain["User Module"]:::domain
            OrderDomain["Order Module"]:::domain
            CalendarDomain["Calendar Module"]:::domain
            BookingDomain["Booking Module"]:::domain
            CustomerDomain["Customer Module"]:::domain
            EventDomain["Event Module"]:::domain
            PhoneDomain["Phone Module"]:::domain
            KVDomain["KV Module"]:::domain
            AuthNDomain["AuthN Module"]:::domain
            AuthZDomain["AuthZ Module"]:::domain
            WorkerDomain["Worker Module"]:::domain
            AddressDomain["Address Module"]:::domain
            ReviewDomain["Review Module"]:::domain
        end

        subgraph "Persistence Adapters"
            direction TB
            PostgresAdapter["Postgres Adapter"]:::adapter
            MongoAdapter["Mongo Adapter"]:::adapter
            RedisAdapter["Redis Adapter"]:::adapter
        end

        subgraph "Messaging & Queue Adapters"
            direction TB
            AsynqClient["Asynq Client"]:::adapter
            Watermill["Watermill (Pub/Sub)"]:::adapter
        end

        %% Wiring
        AppDI --> Config
        AppDI --> HTTP
        AppDI --> Health
        AppDI --> Validation
        AppDI --> AuthN_MW
        AppDI --> AuthZ_MW
        AppDI --> FeatureFlag
        AppDI --> Logging
        AppDI --> Metrics
        AppDI --> Tracing
        AppDI --> UserDomain
        AppDI --> OrderDomain
        AppDI --> CalendarDomain
        AppDI --> BookingDomain
        AppDI --> CustomerDomain
        AppDI --> EventDomain
        AppDI --> PhoneDomain
        AppDI --> KVDomain
        AppDI --> AuthNDomain
        AppDI --> AuthZDomain
        AppDI --> WorkerDomain
        AppDI --> AddressDomain
        AppDI --> ReviewDomain
        AppDI --> PostgresAdapter
        AppDI --> MongoAdapter
        AppDI --> RedisAdapter
        AppDI --> AsynqClient
        AppDI --> Watermill

        %% Clicks
        click AppDI "https://github.com/joaofnds/pbd/blob/main/cmd/app/app.go"
        click Config "https://github.com/joaofnds/pbd/blob/main/config/config.go"
        click HTTP "https://github.com/joaofnds/pbd/blob/main/adapter/http/fiber.go"
        click Health "https://github.com/joaofnds/pbd/blob/main/adapter/health/health_http/controller.go"
        click Logging "https://github.com/joaofnds/pbd/blob/main/adapter/logger/logger.go"
        click Metrics "https://github.com/joaofnds/pbd/blob/main/adapter/metrics/metrics.go"
        click Tracing "https://github.com/joaofnds/pbd/blob/main/adapter/tracing/tracing.go"
        click Validation "https://github.com/joaofnds/pbd/blob/main/adapter/validation/validation.go"
        click PostgresAdapter "https://github.com/joaofnds/pbd/blob/main/adapter/postgres/postgres.go"
        click MongoAdapter "https://github.com/joaofnds/pbd/blob/main/adapter/mongo/mongo.go"
        click RedisAdapter "https://github.com/joaofnds/pbd/blob/main/adapter/redis/redis.go"
        click AsynqClient "https://github.com/joaofnds/pbd/blob/main/adapter/queue/client.go"
        click Watermill "https://github.com/joaofnds/pbd/blob/main/adapter/watermill/event.go"
        click FeatureFlag "https://github.com/joaofnds/pbd/blob/main/adapter/featureflags/featureflags.go"
        click AuthN_MW "https://github.com/joaofnds/pbd/blob/main/authn/authn_http/middleware.go"
        click AuthZ_MW "https://github.com/joaofnds/pbd/blob/main/authz/authz_http/middleware.go"
        click UserDomain "https://github.com/joaofnds/pbd/blob/main/user/user_module/module.go"
        click OrderDomain "https://github.com/joaofnds/pbd/blob/main/order/order_module/module.go"
        click CalendarDomain "https://github.com/joaofnds/pbd/blob/main/calendar/calendar_module/module.go"
        click BookingDomain "https://github.com/joaofnds/pbd/blob/main/booking/booking_module/module.go"
        click CustomerDomain "https://github.com/joaofnds/pbd/blob/main/customer/customer_module/module.go"
        click EventDomain "https://github.com/joaofnds/pbd/blob/main/event/event_module/module.go"
        click PhoneDomain "https://github.com/joaofnds/pbd/blob/main/phone/phone_module/module.go"
        click KVDomain "https://github.com/joaofnds/pbd/blob/main/kv/kv_module/module.go"
        click AuthNDomain "https://github.com/joaofnds/pbd/blob/main/authn/authn_module/module.go"
        click AuthZDomain "https://github.com/joaofnds/pbd/blob/main/authz_http/module.go"
        click WorkerDomain "https://github.com/joaofnds/pbd/blob/main/worker/worker_module/module.go"
        click AddressDomain "https://github.com/joaofnds/pbd/blob/main/address/address_module/module.go"
        click ReviewDomain "https://github.com/joaofnds/pbd/blob/main/review/review_module/module.go"
    end

    subgraph "Worker Service (cmd/worker)"
        direction TB
        WorkerDI["Dependency Injection (Fx)"]:::core
        ConfigW["Configuration (Viper)"]:::infra
        LoggingW["Logging (Zap)"]:::adapter
        MetricsW["Metrics (Prometheus)"]:::adapter
        TracingW["Tracing (OpenTelemetry)"]:::adapter
        WorkerQueue["Asynq Server"]:::adapter
        WatermillSub["Watermill Subscriber"]:::adapter

        WorkerDI --> ConfigW
        WorkerDI --> LoggingW
        WorkerDI --> MetricsW
        WorkerDI --> TracingW
        WorkerDI --> WorkerQueue
        WorkerDI --> WatermillSub
        WorkerDI --> UserDomain
        WorkerDI --> OrderDomain
        WorkerDI --> CalendarDomain
        WorkerDI --> BookingDomain
        WorkerDI --> CustomerDomain
        WorkerDI --> EventDomain
        WorkerDI --> PhoneDomain
        WorkerDI --> KVDomain
        WorkerDI --> AuthNDomain
        WorkerDI --> AuthZDomain
        WorkerDI --> WorkerDomain
        WorkerDI --> AddressDomain
        WorkerDI --> ReviewDomain
        WorkerDI --> PostgresAdapter
        WorkerDI --> MongoAdapter
        WorkerDI --> RedisAdapter

        click WorkerDI "https://github.com/joaofnds/pbd/blob/main/cmd/worker/worker.go"
    end

    %% External Infrastructure
    subgraph Infrastructure
        direction TB
        Postgres["PostgreSQL"]:::infra
        MongoDB["MongoDB"]:::infra
        Redis["Redis"]:::infra
        Casdoor["Casdoor Auth"]:::infra
        Casbin["Casbin AuthZ"]:::infra
        FeatureFlagSvc["Go Feature Flag"]:::infra
        MessageBus["Message Bus"]:::infra
        Prometheus["Prometheus"]:::infra
        Grafana["Grafana"]:::infra
        OTelCollector["OpenTelemetry Collector"]:::infra
    end

    %% Flows - API
    Client["Client"]:::external
    Client -->|"HTTP/Fiber"| HTTP
    HTTP -->|"Validate"| Validation
    Validation -->|"Invoke Service"| UserDomain
    UserDomain -->|"SQL via Gorm"| PostgresAdapter
    UserDomain -->|"Redis Cache"| RedisAdapter
    UserDomain -->|"Emit Event"| Watermill
    HTTP -->|"Health Check"| Health
    HTTP -->|"AuthN/AuthZ"| AuthN_MW
    HTTP -->|"AuthZ"| AuthZ_MW
    HTTP -->|"FeatureFlag"| FeatureFlag
    HTTP -->|"Log/Trace/Metric"| Logging
    HTTP -->|"Log/Trace/Metric"| Tracing
    HTTP -->|"Log/Trace/Metric"| Metrics

    %% Event and Queue
    UserDomain -->|"Publish"| MessageBus
    MessageBus -->|"> Subscribe"| WatermillSub
    UserDomain -->|"Enqueue Task"| WorkerQueue
    WorkerQueue -->|"Tasks in Redis"| Redis

    %% Worker Flows
    WorkerQueue -->|"Fetch Task"| WorkerDomain
    WatermillSub -->|"Event Callback"| WorkerDomain
    WorkerDomain -->|"SQL via Gorm"| PostgresAdapter
    WorkerDomain -->|"Mongo"| MongoAdapter

    %% Infra links
    PostgresAdapter --> Postgres
    MongoAdapter --> MongoDB
    RedisAdapter --> Redis
    AsynqClient --> Redis
    WorkerQueue --> Redis
    Watermill --> MessageBus
    WatermillSub --> MessageBus
    AuthN_MW --> Casdoor
    AuthZ_MW --> Casbin
    FeatureFlag --> FeatureFlagSvc
    Metrics --> Prometheus
    Prometheus --> Grafana
    Tracing --> OTelCollector

    %% Classes
    classDef core fill:#AED6F1,stroke:#3498DB;
    classDef adapter fill:#ABEBC6,stroke:#28B463;
    classDef domain fill:#D6EAF8,stroke:#2E86C1;
    classDef infra fill:#F9E79F,stroke:#B7950B;
    classDef external fill:#F5B7B1,stroke:#C0392B;
    classDef loggingMetricsTracing stroke-dasharray: 5 5;
```
