How bluejedi/go-init works
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