# bluejedi/go-init architecture

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

## Overview

##### Project Type and Purpose
- This is a full-stack “real-world” boilerplate combining:
– A Go‐based RESTful API server following Clean Architecture and SOLID principles
– A Hyperapp2 single‐page web app as the front end
- Its purpose is to provide CRUD endpoints (albums, articles, profiles, auth, healthcheck), JWT authentication, structured logging, DB migrations, live reloading, and a client UI.

##### Main Components
a. Frontend SPA (“hyperreal”)
– Built with Hyperapp2 + Snowpack
– Static assets (HTML/CSS/JS in hyperreal/public) served via Go or separate static host
– Dev server with live reload (Snowpack)
b. API Server
– cmd/server (entrypoint.sh → main.go)
– HTTP layer: ozzo-routing endpoints under /v1 and /healthcheck
– Middleware: JWT auth, error handling, access logging
c. Business Logic Layers (per Clean Architecture)
– API Handlers (internal/*/api.go)
– Services (internal/*/service.go)
– Repositories (internal/*/repository.go)
– Entities (internal/entity/*.go)
– Shared libs (pkg/*: accesslog, dbcontext, log, pagination)
d. Database
– PostgreSQL container (via docker-compose)
– DB migrations (migrations/*.up.sql & *.down.sql using golang-migrate)
– Data seeded via testdata/testdata.sql
e. Configuration & Environment
– config/*.yml per environment (local, dev, qa, prod)
– Environment variables override (APP_* prefix)
f. Infrastructure
– Docker & Docker Compose orchestration (cmd/server Dockerfile, docker-compose.yml)
– Makefile tasks for build, run, migrate, db-start, run-live
– GitHub Actions CI (build.yml)
g. External Integrations
– JWT-GO for token handling
– Zap for structured logging
– ozzo-dbx for DB access

##### Relationships & Data Flow
- Browser ↔ HTTP(S) ↔ API Server
- API Server → Database (SQL queries via repositories)
- API Server ← Configuration files / Env Vars
- API Server → Migrations at startup or via CLI
- API Server → Stdout (structured logs) → Log aggregation
- (Dev) Frontend Snowpack server ↔ API Server (CORS)

##### Architectural Patterns
- Layered Clean Architecture:
– Presentation (API), Domain (services/entities), Infrastructure (repository, dbcontext)
- Dependency Injection via function parameters (e.g., transactional DB)
- Screaming Architecture: feature-based package layout under internal/
- Middleware chaining (auth, error, access log)
- Docker multi-stage build

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (hyperreal)" 
        direction TB
        Browser["Browser"]:::frontend
        Snowpack["Snowpack Dev Server"]:::frontend
        StaticHost["Static Assets<br/>(HTML/CSS/JS)"]:::frontend
        Browser -->|"loads SPA"| Snowpack
        Snowpack -->|"serves"| Browser
        Snowpack -->|"builds"| StaticHost
    end

    %% API Server
    subgraph "API Server" 
        direction TB
        subgraph "HTTP Layer" 
            direction TB
            AlbumAPI["Album API Handler<br/>(internal/album/api.go)"]:::api
            ArticleAPI["Article API Handler<br/>(internal/article/api.go)"]:::api
            AuthAPI["Auth API Handler<br/>(internal/auth/api.go)"]:::api
            ProfileAPI["Profile API Handler<br/>(internal/profile/api.go)"]:::api
            HealthAPI["Healthcheck Handler<br/>(internal/healthcheck/api.go)"]:::api
        end
        subgraph "Middleware" 
            direction TB
            AuthMW["Auth Middleware<br/>(internal/auth/middleware.go)"]:::middleware
            ErrorMW["Error Middleware<br/>(internal/errors/middleware.go)"]:::middleware
            AccessLogMW["AccessLog Middleware<br/>(pkg/accesslog/middleware.go)"]:::middleware
        end
        subgraph "Service Layer" 
            direction TB
            AlbumSvc["AlbumService<br/>(internal/album/service.go)"]:::service
            AuthSvc["AuthService<br/>(internal/auth/service.go)"]:::service
            ProfileSvc["ProfileService<br/>(internal/profile/service.go)"]:::service
        end
        subgraph "Repository Layer" 
            direction TB
            AlbumRepo["AlbumRepo<br/>(internal/album/repository.go)"]:::repo
            AuthRepo["AuthRepo<br/>(internal/auth/repository.go)"]:::repo
            ProfileRepo["ProfileRepo<br/>(internal/profile/repository.go)"]:::repo
        end
        subgraph "Domain Entities" 
            direction TB
            EntityAlbum["Album Entity<br/>(internal/entity/album.go)"]:::entity
            EntityID["ID Entity<br/>(internal/entity/id.go)"]:::entity
            EntityProfile["Profile Entity<br/>(internal/entity/profile.go)"]:::entity
            EntityUser["User Entity<br/>(internal/entity/user.go)"]:::entity
        end
        subgraph "Shared Libraries (pkg)" 
            direction TB
            DBContext["DBContext<br/>(pkg/dbcontext/db.go)"]:::infra
            Logger["Logger<br/>(pkg/log/logger.go)"]:::infra
            Pagination["Pagination<br/>(pkg/pagination/pages.go)"]:::infra
            AccessLogPkg["AccessLog<br/>(pkg/accesslog/middleware.go)"]:::infra
        end
        ConfigLoader["Config Loader<br/>(internal/config/config.go)"]:::config
        Entrypoint["EntryPoint<br/>(cmd/server/main.go)"]:::infra
        EntrypointSh["Entrypoint Script<br/>(cmd/server/entrypoint.sh)"]:::infra
        Dockerfile["Dockerfile<br/>(cmd/server/Dockerfile)"]:::infra
    end

    %% Database
    Database[(PostgreSQL)]:::db
    Migrations["Migrations<br/>(migrations/*.sql)"]:::config
    TestData["TestData<br/>(testdata/testdata.sql)"]:::config

    %% Infrastructure & CI
    DockerCompose["Docker Compose<br/>(docker-compose.yml)"]:::infra
    Makefile["Makefile"]:::infra
    CI["GitHub Actions CI<br/>(.github/workflows/build.yml)"]:::ci
    GoMod["go.mod & go.sum"]:::infra

    %% Connections
    Browser -->|"HTTP/JSON"| AlbumAPI
    Browser -->|"HTTP/JSON"| ArticleAPI
    Browser -->|"HTTP/JSON"| AuthAPI
    Browser -->|"HTTP/JSON"| ProfileAPI
    Browser -->|"HTTP/GET /health"| HealthAPI

    AlbumAPI -->|calls| AuthMW
    ArticleAPI -->|calls| AuthMW
    ProfileAPI -->|calls| AuthMW
    AuthAPI -->|calls| ErrorMW
    HealthAPI -->|calls| AccessLogMW

    AuthMW -->|injects| AuthSvc
    ErrorMW -->|wraps| AlbumSvc
    AccessLogMW -->|logs| AlbumAPI

    AlbumAPI -->|uses| AlbumSvc
    AlbumSvc -->|uses| AlbumRepo
    AlbumRepo -->|SQL| Database

    AuthAPI -->|uses| AuthSvc
    AuthSvc -->|uses| AuthRepo
    ProfileAPI -->|uses| ProfileSvc
    ProfileSvc -->|uses| ProfileRepo

    AlbumSvc -->|entities| EntityAlbum
    AuthSvc -->|entities| EntityUser
    ProfileSvc -->|entities| EntityProfile

    EntrypointSh --> Entrypoint
    Entrypoint --> ConfigLoader
    ConfigLoader -->|loads| Migrations
    Entrypoint -->|runs| Migrations
    Entrypoint -->|seeds| TestData

    Entrypoint -->|build| Dockerfile
    DockerCompose --> Entrypoint
    Makefile --> DockerCompose
    Makefile -->|runs| Entrypoint

    CI --> Makefile
    CI --> GoMod

    Database -->|migrates| Migrations

    %% Click Events
    click Browser "https://github.com/bluejedi/go-init/tree/master/hyperreal/"
    click Snowpack "https://github.com/bluejedi/go-init/blob/master/hyperreal/snowpack.config.json"
    click StaticHost "https://github.com/bluejedi/go-init/tree/master/hyperreal/public"
    click Entrypoint "https://github.com/bluejedi/go-init/blob/master/cmd/server/main.go"
    click EntrypointSh "https://github.com/bluejedi/go-init/blob/master/cmd/server/entrypoint.sh"
    click Dockerfile "https://github.com/bluejedi/go-init/tree/master/cmd/server/Dockerfile"
    click AlbumAPI "https://github.com/bluejedi/go-init/blob/master/internal/album/api.go"
    click ArticleAPI "https://github.com/bluejedi/go-init/blob/master/internal/article/api.go"
    click AuthAPI "https://github.com/bluejedi/go-init/blob/master/internal/auth/api.go"
    click ProfileAPI "https://github.com/bluejedi/go-init/blob/master/internal/profile/api.go"
    click HealthAPI "https://github.com/bluejedi/go-init/blob/master/internal/healthcheck/api.go"
    click AuthMW "https://github.com/bluejedi/go-init/blob/master/internal/auth/middleware.go"
    click ErrorMW "https://github.com/bluejedi/go-init/blob/master/internal/errors/middleware.go"
    click AccessLogMW "https://github.com/bluejedi/go-init/blob/master/pkg/accesslog/middleware.go"
    click AlbumSvc "https://github.com/bluejedi/go-init/blob/master/internal/album/service.go"
    click AuthSvc "https://github.com/bluejedi/go-init/blob/master/internal/auth/service.go"
    click ProfileSvc "https://github.com/bluejedi/go-init/blob/master/internal/profile/service.go"
    click AlbumRepo "https://github.com/bluejedi/go-init/blob/master/internal/album/repository.go"
    click AuthRepo "https://github.com/bluejedi/go-init/blob/master/internal/auth/repository.go"
    click ProfileRepo "https://github.com/bluejedi/go-init/blob/master/internal/profile/repository.go"
    click EntityAlbum "https://github.com/bluejedi/go-init/blob/master/internal/entity/album.go"
    click EntityID "https://github.com/bluejedi/go-init/blob/master/internal/entity/id.go"
    click EntityProfile "https://github.com/bluejedi/go-init/blob/master/internal/entity/profile.go"
    click EntityUser "https://github.com/bluejedi/go-init/blob/master/internal/entity/user.go"
    click DBContext "https://github.com/bluejedi/go-init/blob/master/pkg/dbcontext/db.go"
    click Logger "https://github.com/bluejedi/go-init/blob/master/pkg/log/logger.go"
    click Pagination "https://github.com/bluejedi/go-init/blob/master/pkg/pagination/pages.go"
    click ConfigLoader "https://github.com/bluejedi/go-init/blob/master/internal/config/config.go"
    click Migrations "https://github.com/bluejedi/go-init/blob/master/migrations/20191217202658_init.up.sql"
    click TestData "https://github.com/bluejedi/go-init/blob/master/testdata/testdata.sql"
    click DockerCompose "https://github.com/bluejedi/go-init/blob/master/docker-compose.yml"
    click Makefile "https://github.com/bluejedi/go-init/tree/master/Makefile"
    click CI "https://github.com/bluejedi/go-init/blob/master/.github/workflows/build.yml"
    click GoMod "https://github.com/bluejedi/go-init/blob/master/go.mod"

    %% Styles
    classDef frontend fill:#e0ffe0,stroke:#0a0,stroke-width:1px
    classDef api fill:#e0f0ff,stroke:#00a,stroke-width:1px
    classDef middleware fill:#fff0e0,stroke:#a60,stroke-width:1px
    classDef service fill:#f0f8ff,stroke:#08f,stroke-width:1px
    classDef repo fill:#f5f5dc,stroke:#aa0,stroke-width:1px
    classDef entity fill:#ffe0e0,stroke:#a00,stroke-width:1px
    classDef infra fill:#f0f0f0,stroke:#666,stroke-width:1px
    classDef db fill:#ffeadb,stroke:#a40,stroke-width:1px
    classDef config fill:#f0f0f0,stroke:#888,stroke-width:1px
    classDef ci fill:#e8e8ff,stroke:#44f,stroke-width:1px
```
