# samverrall/microservice-example architecture

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

- Interactive diagram: https://gitdiagram.com/samverrall/microservice-example
- Repository: https://github.com/samverrall/microservice-example

## Overview

##### Project type and purpose
- This is a Go-based microservice demonstrating Domain-Driven Design (DDD) and Hexagonal Architecture (ports & adapters).
- It exposes a gRPC interface for other services to interact with user accounts and includes health‐check endpoints.
- It persists data in PostgreSQL and provides migration and test‐database utilities.

##### File structure
- cmd/main.go: application entry point (wires everything up).
- internal/app: core application (use‐cases/services) implementing DDD.
- user: account creation, email, password rules, repository interface.
- internal/grpc: transport layer (adapters)
- server.go: gRPC server bootstrap
- handler packages: user & health RPC handlers
- internal/postgres & internal/repository: persistence adapters implementing repository interfaces.
- pkg/config: configuration loader
- pkg/postgresutil: migration runner and test‐database helper
- pkg/proto: compiled protobuf messages & gRPC stubs
- Dockerfile, Makefile, run.sh: build, run, and generate proto scripts

##### README for additional insights
- Confirms Hexagonal / ports-and-adapters structure.
- Emphasizes the “internal/app” core.
- Mentions gRPC transport and proto generation targets.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External
    EC["External Client"]:::external

    %% Transport Adapter
    subgraph "gRPC Transport Adapter"
        Server["gRPC Server Bootstrap"]:::transport
        UserH["gRPC User Handler"]:::transport
        HealthH["gRPC Health Handler"]:::transport
        Protos["Protobuf Definitions & Stubs"]:::transport
    end

    %% Application Core Hexagon
    subgraph "Application Core"
        direction TB
        AppCore["Hexagon Core"]:::core
        UserSvc["UserService"]:::core
        HealthSvc["HealthService"]:::core
        RepoPort["Repository Port Interface"]:::core
    end

    %% Persistence Adapter
    subgraph "Persistence Adapter"
        PostgresAdapter["Postgres Repository Adapter"]:::persistence
    end

    %% Database
    DB["PostgreSQL Database"]:::persistence

    %% Infrastructure & Orchestration
    subgraph "Infrastructure & Orchestration"
        direction TB
        cmdMain["cmd/main.go"]:::infra
        Config["Configuration Loader"]:::infra
        Migrate["DB Migration Utility"]:::infra
        TestDB["Test-Database Helper"]:::infra
        PostgresUtil["General Postgres Utilities"]:::infra
        Docker["Dockerfile / Makefile / run.sh"]:::infra
    end

    %% Flows
    EC --> Server
    Server --> UserH
    Server --> HealthH
    Protos --> Server
    UserH --> UserSvc
    HealthH --> HealthSvc
    UserSvc --> RepoPort
    RepoPort --> PostgresAdapter
    PostgresAdapter --> DB
    HealthSvc --> RepoPort

    %% Startup Flow
    cmdMain --> Config
    cmdMain --> Migrate
    cmdMain --> Server
    Migrate --> DB
    cmdMain --> PostgresUtil
    cmdMain --> TestDB

    %% Click Events
    click Server "https://github.com/samverrall/microservice-example/blob/main/internal/grpc/server.go"
    click UserH "https://github.com/samverrall/microservice-example/blob/main/internal/grpc/user/handler.go"
    click HealthH "https://github.com/samverrall/microservice-example/blob/main/internal/grpc/health/handler.go"
    click Protos "https://github.com/samverrall/microservice-example/blob/main/pkg/proto/user.proto"
    click Protos "https://github.com/samverrall/microservice-example/blob/main/pkg/proto/user.pb.go"
    click Protos "https://github.com/samverrall/microservice-example/blob/main/pkg/proto/user_grpc.pb.go"
    click Protos "https://github.com/samverrall/microservice-example/blob/main/pkg/proto/health.proto"
    click Protos "https://github.com/samverrall/microservice-example/blob/main/pkg/proto/health.pb.go"
    click Protos "https://github.com/samverrall/microservice-example/blob/main/pkg/proto/health_grpc.pb.go"
    click AppCore "https://github.com/samverrall/microservice-example/blob/main/internal/app/app.go"
    click UserSvc "https://github.com/samverrall/microservice-example/blob/main/internal/app/user/service.go"
    click RepoPort "https://github.com/samverrall/microservice-example/blob/main/internal/app/user/repo.go"
    click PostgresAdapter "https://github.com/samverrall/microservice-example/blob/main/internal/postgres/user.go"
    click cmdMain "https://github.com/samverrall/microservice-example/blob/main/cmd/main.go"
    click Config "https://github.com/samverrall/microservice-example/blob/main/pkg/config/config.go"
    click Migrate "https://github.com/samverrall/microservice-example/blob/main/pkg/postgresutil/migrate.go"
    click TestDB "https://github.com/samverrall/microservice-example/blob/main/pkg/postgresutil/testdatabase/testdatabase.go"
    click PostgresUtil "https://github.com/samverrall/microservice-example/blob/main/pkg/postgresutil/postgresutil.go"
    click Docker "https://github.com/samverrall/microservice-example/tree/main/Dockerfile"

    %% Styles
    classDef external fill:#EEEEEE,stroke:#000,stroke-width:1px;
    classDef transport fill:#84C1FF,stroke:#000,stroke-width:1px;
    classDef core fill:#C1FF84,stroke:#000,stroke-width:1px;
    classDef persistence fill:#FFB84C,stroke:#000,stroke-width:1px;
    classDef infra fill:#D3D3D3,stroke:#000,stroke-width:1px;
```
