# sriniously/go-boilerplate architecture

> Architecture diagram of the GitHub repository sriniously/go-boilerplate, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sriniously/go-boilerplate
- Repository: https://github.com/sriniously/go-boilerplate

## Overview

1. This is a monorepo with two runtime applications and several shared packages:
   - `apps/backend`: the Go API/service
   - `apps/frontend`: a Vite/TypeScript client
   - `packages/*`: shared TypeScript packages for API contracts, validation, and email templates
   Turborepo coordinates builds/tasks at the repo root, while the backend has its own Go module and task runner.

2. The backend is the core system boundary. It is started from `apps/backend/cmd/go-boilerplate/main.go`, which wires configuration, logging, database, middleware, router, handlers, services, repositories, background jobs, and the HTTP server.

3. The HTTP layer uses Echo and is organized around:
   - `internal/router` for route registration
   - `internal/handler` for request/response endpoints
   - `internal/middleware` for cross-cutting concerns
   - `internal/errs` and `internal/sqlerr` for consistent error translation
   The included handlers are minimal in the tree (`health`, `openapi`), which suggests the repo is a template meant to be extended rather than a feature-complete app.

4. Request processing has a clear middleware pipeline. The repo includes middleware for:
   - request IDs
   - tracing
   - auth
   - rate limiting
   - context propagation
   - global security/response behavior
   These sit in front of handlers and are part of the API’s operational boundary.

5. Business logic is separated from transport and persistence. The backend follows a clean-architecture layout:
   - `internal/service` for use-case/business logic
   - `internal/repository` for data access
   - `internal/model` for domain/data structures
   - `internal/database` for PostgreSQL connectivity and migrations
   This makes the flow typically: HTTP handler → service → repository → database.

6. PostgreSQL is the primary persistent store. The database package manages connection setup and migration execution, and the repo includes SQL migrations under `internal/database/migrations` plus a bootstrap migration (`001_setup.sql`). This is the durable data boundary for the service.

7. Background jobs are a first-class subsystem. `internal/lib/job` contains Asynq-related job definitions and handlers, and the README confirms Redis-backed async processing. This creates a second execution path alongside HTTP: some work is enqueued by the app and processed out-of-band by job workers.

8. Email delivery is another distinct integration boundary. `internal/lib/email` contains the client, templates, and preview support for transactional emails, and the repo also includes HTML templates in `apps/backend/templates/emails`. The README identifies Resend as the outbound email provider. In practice, the backend likely renders templates, sends through the email client, and may trigger sends from jobs.

9. Authentication and security are built into the API layer rather than treated as a separate service. The README calls out Clerk and JWT validation, and the middleware/auth layer indicates auth is enforced centrally at the request boundary. Security concerns also include CORS, secure headers, and rate limiting.

10. Observability is wired into the service runtime. The codebase includes config for observability, a structured logger package, and tracing middleware; the README adds New Relic APM. That means production requests are meant to be traceable end-to-end, from request ID through handler execution and downstream calls.

11. The frontend is a separate TypeScript application in `apps/frontend`, built with Vite. Its `src/api` folder suggests a thin client-side API layer rather than direct business logic. The app likely consumes the backend over HTTP and uses environment-based configuration from `src/config/env.ts`.

12. Shared TypeScript packages indicate contract sharing across the frontend ecosystem:
   - `packages/openapi` contains OpenAPI contracts and generation utilities
   - `packages/zod` contains validation schemas aligned with those contracts
   - `packages/emails` contains TSX email templates
   These packages suggest the repo is designed to keep API schemas, validation, and templates consistent across app boundaries.

13. Testing is supported by dedicated infrastructure under `internal/testing`, including container helpers, transactional test helpers, and server helpers. The README’s mention of Testcontainers implies integration tests can spin up real dependencies like Postgres/Redis, which is important for diagramming the non-production dependency path.

14. The overall architecture is: browser/client → frontend app → backend HTTP API → service/repository/database, with side paths from the backend into Redis-backed jobs and outbound email/observability services. The repo is intentionally scaffolded so these external systems remain behind narrow internal packages, making it easy to replace or extend each integration point independently.

Main entry points: [`apps/backend/cmd/go-boilerplate/main.go`](https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/cmd/go-boilerplate/main.go) (API entry), [`apps/backend/internal/router/router.go`](https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/internal/router/router.go) (HTTP layer), [`apps/backend/internal/handler/handlers.go`](https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/internal/handler/handlers.go) (Handlers), [`apps/backend/internal/service/services.go`](https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/internal/service/services.go) (Services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_monorepo["Monorepo"]
  node_turbo["Turborepo<br/>build orchestrator<br/>[turbo.json]"]
end

subgraph group_backend["Backend"]
  node_backend_main["API entry<br/>go bootstrap<br/>[main.go]"]
  node_backend_config["Config<br/>[config.go]"]
  node_backend_logger["Logger<br/>structured logging<br/>[logger.go]"]
  node_backend_http["HTTP layer<br/>echo api<br/>[router.go]"]
  node_backend_middleware["Middleware<br/>request pipeline<br/>[middlewares.go]"]
  node_backend_handlers["Handlers<br/>endpoint layer<br/>[handlers.go]"]
  node_backend_services["Services<br/>use cases<br/>[services.go]"]
  node_backend_repos["Repositories<br/>data access<br/>[repositories.go]"]
  node_backend_db[("PostgreSQL<br/>database runtime<br/>[database.go]")]
  node_backend_jobs["Jobs<br/>async workers<br/>[job.go]"]
  node_backend_email["Email<br/>outbound mail<br/>[client.go]"]
  node_backend_auth["Auth<br/>security service<br/>[auth.go]"]
  node_backend_errs["Error mapping<br/>http errors<br/>[http.go]"]
  node_backend_obs["Observability<br/>tracing/telemetry<br/>[observability.go]"]
  node_backend_test["Test helpers<br/>test infra<br/>[helpers.go]"]
end

subgraph group_frontend["Frontend"]
  node_frontend_app["Frontend app<br/>vite client<br/>[main.tsx]"]
  node_frontend_api["Client API<br/>ts api layer<br/>[index.ts]"]
end

subgraph group_shared["Shared packages"]
  node_pkg_openapi["OpenAPI<br/>contract package<br/>[index.ts]"]
  node_pkg_zod["Zod schemas<br/>validation package<br/>[index.ts]"]
  node_pkg_emails["Email templates<br/>template package<br/>[welcome.tsx]"]
end

node_turbo -->|"builds"| node_backend_main
node_turbo -->|"builds"| node_frontend_app
node_turbo -->|"builds"| node_pkg_openapi
node_backend_main -->|"loads"| node_backend_config
node_backend_main -->|"initializes"| node_backend_logger
node_backend_main -->|"wires"| node_backend_http
node_backend_main -->|"wires"| node_backend_services
node_backend_main -->|"wires"| node_backend_repos
node_backend_main -->|"starts"| node_backend_db
node_backend_main -->|"starts"| node_backend_jobs
node_backend_main -->|"wires"| node_backend_email
node_backend_main -->|"enables"| node_backend_obs
node_backend_http -->|"uses"| node_backend_middleware
node_backend_http -->|"dispatches to"| node_backend_handlers
node_backend_handlers -->|"calls"| node_backend_services
node_backend_services -->|"queries"| node_backend_repos
node_backend_repos -->|"uses"| node_backend_db
node_backend_jobs -->|"sends"| node_backend_email
node_backend_jobs -->|"invokes"| node_backend_services
node_backend_handlers -->|"maps errors"| node_backend_errs
node_backend_middleware -->|"enforces"| node_backend_auth
node_backend_middleware -->|"traces"| node_backend_obs
node_backend_http -->|"serves contract"| node_pkg_openapi
node_frontend_app -->|"uses"| node_frontend_api
node_frontend_api -->|"aligns with"| node_pkg_openapi
node_frontend_api -->|"validates with"| node_pkg_zod
node_backend_handlers -->|"matches"| node_pkg_openapi
node_backend_email -->|"renders"| node_pkg_emails
node_backend_test -->|"provisions"| node_backend_db
node_backend_test -->|"boots"| node_backend_http

click node_turbo "https://github.com/sriniously/go-boilerplate/blob/main/turbo.json"
click node_backend_main "https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/cmd/go-boilerplate/main.go"
click node_backend_config "https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/internal/config/config.go"
click node_backend_logger "https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/internal/logger/logger.go"
click node_backend_http "https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/internal/router/router.go"
click node_backend_middleware "https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/internal/middleware/middlewares.go"
click node_backend_handlers "https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/internal/handler/handlers.go"
click node_backend_services "https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/internal/service/services.go"
click node_backend_repos "https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/internal/repository/repositories.go"
click node_backend_db "https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/internal/database/database.go"
click node_backend_jobs "https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/internal/lib/job/job.go"
click node_backend_email "https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/internal/lib/email/client.go"
click node_backend_auth "https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/internal/service/auth.go"
click node_backend_errs "https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/internal/errs/http.go"
click node_backend_obs "https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/internal/config/observability.go"
click node_backend_test "https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/internal/testing/helpers.go"
click node_frontend_app "https://github.com/sriniously/go-boilerplate/blob/main/apps/frontend/src/main.tsx"
click node_frontend_api "https://github.com/sriniously/go-boilerplate/blob/main/apps/frontend/src/api/index.ts"
click node_pkg_openapi "https://github.com/sriniously/go-boilerplate/blob/main/packages/openapi/src/index.ts"
click node_pkg_zod "https://github.com/sriniously/go-boilerplate/blob/main/packages/zod/src/index.ts"
click node_pkg_emails "https://github.com/sriniously/go-boilerplate/blob/main/packages/emails/src/templates/welcome.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_turbo toneBlue
class node_backend_main,node_backend_config,node_backend_logger,node_backend_http,node_backend_middleware,node_backend_handlers,node_backend_services,node_backend_repos,node_backend_db,node_backend_jobs,node_backend_email,node_backend_auth,node_backend_errs,node_backend_obs,node_backend_test toneAmber
class node_frontend_app,node_frontend_api toneMint
class node_pkg_openapi,node_pkg_zod,node_pkg_emails toneRose
```

## Components

### Monorepo

Root workspace and build orchestration

- [Turborepo](https://github.com/sriniously/go-boilerplate/blob/main/turbo.json): build orchestrator · Coordinates workspace tasks and builds at the repo root · `turbo.json`

### Backend

Go API/service runtime

- [API entry](https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/cmd/go-boilerplate/main.go): go bootstrap · Wires the backend runtime from config through server startup · `apps/backend/cmd/go-boilerplate/main.go`
- [Config](https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/internal/config/config.go): runtime config · Loads service settings and observability configuration · `apps/backend/internal/config/config.go`
- [Logger](https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/internal/logger/logger.go): structured logging · Provides structured application logging · `apps/backend/internal/logger/logger.go`
- [HTTP layer](https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/internal/router/router.go): echo api · Routes requests through middleware to handlers · `apps/backend/internal/router/router.go`
- [Middleware](https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/internal/middleware/middlewares.go): request pipeline · Cross-cutting request concerns including auth, tracing, IDs, rate limits, and response security · `apps/backend/internal/middleware/middlewares.go`
- [Handlers](https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/internal/handler/handlers.go): endpoint layer · HTTP endpoints such as health and OpenAPI serving · `apps/backend/internal/handler/handlers.go`
- [Services](https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/internal/service/services.go): use cases · Business logic and application workflows · `apps/backend/internal/service/services.go`
- [Repositories](https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/internal/repository/repositories.go): data access · Persistence-facing abstractions for storing and loading data · `apps/backend/internal/repository/repositories.go`
- [PostgreSQL](https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/internal/database/database.go): database runtime · Connection management and migration execution for the primary datastore · `apps/backend/internal/database/database.go`
- [Jobs](https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/internal/lib/job/job.go): async workers · Asynq-backed background task definitions and handlers · `apps/backend/internal/lib/job/job.go`
- [Email](https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/internal/lib/email/client.go): outbound mail · Transactional email client, templates, and preview support · `apps/backend/internal/lib/email/client.go`
- [Auth](https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/internal/service/auth.go): security service · Authentication and JWT-oriented request authorization logic · `apps/backend/internal/service/auth.go`
- [Error mapping](https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/internal/errs/http.go): http errors · Translates application and SQL errors into consistent HTTP responses · `apps/backend/internal/errs/http.go`
- [Observability](https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/internal/config/observability.go): tracing/telemetry · Request tracing and observability wiring for production runtime · `apps/backend/internal/config/observability.go`
- [Test helpers](https://github.com/sriniously/go-boilerplate/blob/main/apps/backend/internal/testing/helpers.go): test infra · Container, transaction, and server helpers for integration-style testing · `apps/backend/internal/testing/helpers.go`

### Frontend

Vite client application

- [Frontend app](https://github.com/sriniously/go-boilerplate/blob/main/apps/frontend/src/main.tsx): vite client · TypeScript browser application that consumes the backend API · `apps/frontend/src/main.tsx`
- [Client API](https://github.com/sriniously/go-boilerplate/blob/main/apps/frontend/src/api/index.ts): ts api layer · Thin frontend API wrapper and shared client types · `apps/frontend/src/api/index.ts`

### Shared packages

TypeScript contracts, validation, and email templates

- [OpenAPI](https://github.com/sriniously/go-boilerplate/blob/main/packages/openapi/src/index.ts): contract package · Shared API contracts and OpenAPI generation utilities · `packages/openapi/src/index.ts`
- [Zod schemas](https://github.com/sriniously/go-boilerplate/blob/main/packages/zod/src/index.ts): validation package · Shared validation schemas aligned to API contracts · `packages/zod/src/index.ts`
- [Email templates](https://github.com/sriniously/go-boilerplate/blob/main/packages/emails/src/templates/welcome.tsx): template package · Shared TSX email templates for transactional mail · `packages/emails/src/templates/welcome.tsx`

## Connections

- Turborepo → API entry: builds · Workspace task orchestration includes the backend runtime
- Turborepo → Frontend app: builds · Workspace task orchestration includes the frontend runtime
- Turborepo → OpenAPI: builds · Shared packages are part of the monorepo build graph
- API entry → Config: loads · Startup begins by loading configuration
- API entry → Logger: initializes · Bootstraps structured logging early in process startup
- API entry → HTTP layer: wires · Assembles router, middleware, handlers, and server
- API entry → Services: wires · Creates use-case layer dependencies
- API entry → Repositories: wires · Creates persistence layer dependencies
- API entry → PostgreSQL: starts · Opens database connectivity and runs migrations
- API entry → Jobs: starts · Brings up async job processing integration
- API entry → Email: wires · Connects outbound mail delivery
- API entry → Observability: enables · Configures observability and tracing support
- HTTP layer → Middleware: uses · Routes requests through the middleware pipeline
- HTTP layer → Handlers: dispatches to · Endpoints are handled after middleware passes
- Handlers → Services: calls · Handlers invoke application services
- Services → Repositories: queries · Business logic persists and loads data through repositories
- Repositories → PostgreSQL: uses · Repositories depend on PostgreSQL connectivity
- Jobs → Email: sends · Background work can trigger email delivery
- Jobs → Services: invokes · Workers share core business logic where needed
- Handlers → Error mapping: maps errors · HTTP responses are normalized through error translation
- Middleware → Auth: enforces · Authentication and authorization are handled at the request boundary
- Middleware → Observability: traces · Request tracing is attached in middleware
- HTTP layer → OpenAPI: serves contract · OpenAPI documentation and contracts are published from the backend
- Frontend app → Client API: uses · The client app consumes its local API wrapper
- Client API → OpenAPI: aligns with · Client request/response shapes follow shared API contracts
- Client API → Zod schemas: validates with · Client-side validation uses shared schemas
- Handlers → OpenAPI: matches · HTTP endpoints are shaped by the shared contract package
- Email → Email templates: renders · Backend email sending uses shared template definitions
- Test helpers → PostgreSQL: provisions · Tests can spin up real database dependencies
- Test helpers → HTTP layer: boots · Helpers support running the HTTP server in tests
