# iamdushu/harbor-health-server architecture

> Architecture diagram of the GitHub repository iamdushu/harbor-health-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/iamdushu/harbor-health-server
- Repository: https://github.com/iamdushu/harbor-health-server

## Overview

##### Project type and purpose
- This is a backend API server for the Harbor Health platform, implemented in Go and exposed over HTTP via the Gin framework. It handles authentication, business logic, persistence (PostgreSQL via SQLC), and integrations with external services (Twilio, Brevo, Stream).

##### File structure
- cmd/harbor → entry point (main.go)
- api/ → HTTP handlers, routes, middleware
- internal/db/ → SQL migrations and SQLC‑generated code (data access layer)
- internal/token/ → JWT/PASETO token creation and validation (auth layer)
- internal/util/ → configuration, email/OTP/phone utilities, third‑party wrappers
- Dockerfile, Makefile, .env.example → deployment and local environment setup

##### README insights
- Tech stack: Go, Gin, PostgreSQL, SQLC, Viper, Docker, golang‑migrate
- Auth: PASETO access/refresh token system
- Integrations: Twilio (SMS), Brevo (email), Stream (real‑time video)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients Layer
    subgraph "Clients"
        Clients["Web/Mobile Clients"]:::client
    end

    %% Entry Point
    Main["Main Entry Point\n(cmd/harbor/main.go)"]:::infra
    click Main "https://github.com/iamdushu/harbor-health-server/blob/main/cmd/harbor/main.go"

    %% API Layer
    subgraph "API Gateway & HTTP Handlers"
        direction TB
        ApiServer["API Gateway\n(api/server.go)"]:::api
        click ApiServer "https://github.com/iamdushu/harbor-health-server/blob/main/api/server.go"
        Middleware["Middleware\n(api/middleware.go)"]:::api
        click Middleware "https://github.com/iamdushu/harbor-health-server/blob/main/api/middleware.go"
        AuthRegister["auth_register\n(api/auth_register.go)"]:::api
        click AuthRegister "https://github.com/iamdushu/harbor-health-server/blob/main/api/auth_register.go"
        AuthVerify["auth_verify\n(api/auth_verify.go)"]:::api
        click AuthVerify "https://github.com/iamdushu/harbor-health-server/blob/main/api/auth_verify.go"
        HealthHandler["health\n(api/health.go)"]:::api
        click HealthHandler "https://github.com/iamdushu/harbor-health-server/blob/main/api/health.go"
        LocationHandler["location\n(api/location.go)"]:::api
        click LocationHandler "https://github.com/iamdushu/harbor-health-server/blob/main/api/location.go"
        MemberHandler["member\n(api/member.go)"]:::api
        click MemberHandler "https://github.com/iamdushu/harbor-health-server/blob/main/api/member.go"
        ProviderHandler["provider\n(api/provider.go)"]:::api
        click ProviderHandler "https://github.com/iamdushu/harbor-health-server/blob/main/api/provider.go"
        TokenHandler["token\n(api/token.go)"]:::api
        click TokenHandler "https://github.com/iamdushu/harbor-health-server/blob/main/api/token.go"
        UserHandler["user\n(api/user.go)"]:::api
        click UserHandler "https://github.com/iamdushu/harbor-health-server/blob/main/api/user.go"
        VisitHandler["visit\n(api/visit.go)"]:::api
        click VisitHandler "https://github.com/iamdushu/harbor-health-server/blob/main/api/visit.go"
    end

    %% Business Logic Layers
    subgraph "Authentication Service" 
        direction TB
        PASETOMaker["PASETO Maker\n(internal/token/paseto_maker.go)"]:::logic
        click PASETOMaker "https://github.com/iamdushu/harbor-health-server/blob/main/internal/token/paseto_maker.go"
        Maker["maker.go\n(internal/token/maker.go)"]:::logic
        click Maker "https://github.com/iamdushu/harbor-health-server/blob/main/internal/token/maker.go"
        JWTUnsigned["jwt_unsigned.go\n(internal/token/jwt_unsigned.go)"]:::logic
        click JWTUnsigned "https://github.com/iamdushu/harbor-health-server/blob/main/internal/token/jwt_unsigned.go"
        Payload["payload.go\n(internal/token/payload.go)"]:::logic
        click Payload "https://github.com/iamdushu/harbor-health-server/blob/main/internal/token/payload.go"
    end

    subgraph "Utility Layer" 
        direction TB
        Config["config.go\n(internal/util/config.go)"]:::infra
        click Config "https://github.com/iamdushu/harbor-health-server/blob/main/internal/util/config.go"
        Constants["constants.go\n(internal/util/constants.go)"]:::logic
        click Constants "https://github.com/iamdushu/harbor-health-server/blob/main/internal/util/constants.go"
        OTP["generate_otp.go\n(internal/util/generate_otp.go)"]:::logic
        click OTP "https://github.com/iamdushu/harbor-health-server/blob/main/internal/util/generate_otp.go"
        Hash["hash_this.go\n(internal/util/hash_this.go)"]:::logic
        click Hash "https://github.com/iamdushu/harbor-health-server/blob/main/internal/util/hash_this.go"
        EmailNorm["email_normalizer.go\n(internal/util/email_normalizer.go)"]:::logic
        click EmailNorm "https://github.com/iamdushu/harbor-health-server/blob/main/internal/util/email_normalizer.go"
        PhoneVerify["phone_verify.go\n(internal/util/phone_verify.go)"]:::logic
        click PhoneVerify "https://github.com/iamdushu/harbor-health-server/blob/main/internal/util/phone_verify.go"
        BrevoWrapper["brevo.go\n(internal/util/brevo.go)"]:::logic
        click BrevoWrapper "https://github.com/iamdushu/harbor-health-server/blob/main/internal/util/brevo.go"
    end

    %% Data Access Layer
    subgraph "Data Access Layer (SQLC)"
        direction TB
        Store["store.go\n(internal/db/sqlc/store.go)"]:::db
        click Store "https://github.com/iamdushu/harbor-health-server/blob/main/internal/db/sqlc/store.go"
        Querier["querier.go\n(internal/db/sqlc/querier.go)"]:::db
        click Querier "https://github.com/iamdushu/harbor-health-server/blob/main/internal/db/sqlc/querier.go"
        Models["models.go\n(internal/db/sqlc/models.go)"]:::db
        click Models "https://github.com/iamdushu/harbor-health-server/blob/main/internal/db/sqlc/models.go"
        TxCreateMember["tx_create_member.go\n(internal/db/sqlc/tx_create_member.go)"]:::db
        click TxCreateMember "https://github.com/iamdushu/harbor-health-server/blob/main/internal/db/sqlc/tx_create_member.go"
        TxCreateVisit["tx_create_visit.go\n(internal/db/sqlc/tx_create_visit.go)"]:::db
        click TxCreateVisit "https://github.com/iamdushu/harbor-health-server/blob/main/internal/db/sqlc/tx_create_visit.go"
        TxManifestToken["tx_manifest_token.go\n(internal/db/sqlc/tx_manifest_token.go)"]:::db
        click TxManifestToken "https://github.com/iamdushu/harbor-health-server/blob/main/internal/db/sqlc/tx_manifest_token.go"
        TxUpdateVerify["tx_update_verify_attempt.go\n(internal/db/sqlc/tx_update_verify_attempt.go)"]:::db
        click TxUpdateVerify "https://github.com/iamdushu/harbor-health-server/blob/main/internal/db/sqlc/tx_update_verify_attempt.go"
    end

    %% Migrations & Database
    subgraph "Database & Migrations"
        direction TB
        Migrations["Migrations\n(internal/db/migration/)"]:::infra
        click Migrations "https://github.com/iamdushu/harbor-health-server/tree/main/internal/db/migration/"
        Postgres["PostgreSQL Database"]:::db
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Twilio["Twilio SMS API"]:::ext
        Brevo["Brevo Email API"]:::ext
        Stream["Stream Video API"]:::ext
    end

    %% Deployment & Config Files
    subgraph "Deployment & Config"
        direction TB
        Dockerfile["Dockerfile"]:::infra
        Makefile["Makefile"]:::infra
        EnvExample[".env.example"]:::infra
        SQLCConfig["sqlc.yaml"]:::infra
        GoMod["go.mod / go.sum"]:::infra
        Readme["README.md"]:::infra
    end

    %% Connections
    Clients -->|"HTTP request"| ApiServer
    Main --> ApiServer
    Main --> Store
    Main --> PASETOMaker

    ApiServer --> Middleware
    Middleware --> AuthRegister
    Middleware --> AuthVerify
    Middleware --> HealthHandler
    Middleware --> LocationHandler
    Middleware --> MemberHandler
    Middleware --> ProviderHandler
    Middleware --> TokenHandler
    Middleware --> UserHandler
    Middleware --> VisitHandler

    AuthRegister --> PASETOMaker
    AuthVerify --> PASETOMaker
    TokenHandler --> PASETOMaker

    AuthRegister --> Store
    LocationHandler --> Store
    MemberHandler --> Store
    ProviderHandler --> Store
    UserHandler --> Store
    VisitHandler --> Store
    HealthHandler --> QueryHealth["health.sql.go"]:::db
    click QueryHealth "https://github.com/iamdushu/harbor-health-server/blob/main/internal/db/sqlc/health.sql.go"

    %% Data flow to DB
    Store --> Postgres
    Migrations --> Postgres

    %% Utils usage
    AuthRegister --> OTP
    AuthRegister --> EmailNorm
    AuthRegister --> PhoneVerify
    MemberHandler --> EmailNorm
    VisitHandler --> OTP
    ProviderHandler --> BrevoWrapper

    BrevoWrapper --> Brevo
    OTP --> Twilio
    %% Utils config
    Config --> PASETOMaker
    Config --> Store

    %% Deployment arrows
    Dockerfile --> Postgres
    Dockerfile --> ApiServer

    %% Styling
    classDef client fill:#eef,stroke:#333,stroke-width:1px
    classDef api fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef logic fill:#b8daff,stroke:#333,stroke-width:1px
    classDef db fill:#d4edda,stroke:#333,stroke-width:1px
    classDef ext fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef infra fill:#e2e3e5,stroke:#333,stroke-width:1px
```
