How sriniously/go-boilerplate works
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: main.go API entry · router.go HTTP layer · handlers.go Handlers · services.go Services
Components 21
Monorepo
Root workspace and build orchestration
- Turborepo · Coordinates workspace tasks and builds at the repo root
turbo.json
Backend
Go API/service runtime
- API entry · Wires the backend runtime from config through server startup
apps/backend/cmd/go-boilerplate/main.go - Config · Loads service settings and observability configuration
apps/backend/internal/config/config.go - Logger · Provides structured application logging
apps/backend/internal/logger/logger.go - HTTP layer · Routes requests through middleware to handlers
apps/backend/internal/router/router.go - Middleware · Cross-cutting request concerns including auth, tracing, IDs, rate limits, and response security
apps/backend/internal/middleware/middlewares.go - Handlers · HTTP endpoints such as health and OpenAPI serving
apps/backend/internal/handler/handlers.go - Services · Business logic and application workflows
apps/backend/internal/service/services.go - Repositories · Persistence-facing abstractions for storing and loading data
apps/backend/internal/repository/repositories.go - PostgreSQL · Connection management and migration execution for the primary datastore
apps/backend/internal/database/database.go - Jobs · Asynq-backed background task definitions and handlers
apps/backend/internal/lib/job/job.go - Email · Transactional email client, templates, and preview support
apps/backend/internal/lib/email/client.go - Auth · Authentication and JWT-oriented request authorization logic
apps/backend/internal/service/auth.go - Error mapping · Translates application and SQL errors into consistent HTTP responses
apps/backend/internal/errs/http.go - Observability · Request tracing and observability wiring for production runtime
apps/backend/internal/config/observability.go - Test helpers · Container, transaction, and server helpers for integration-style testing
apps/backend/internal/testing/helpers.go
Frontend
Vite client application
- Frontend app · TypeScript browser application that consumes the backend API
apps/frontend/src/main.tsx - Client API · Thin frontend API wrapper and shared client types
apps/frontend/src/api/index.ts
Shared packages
TypeScript contracts, validation, and email templates
- OpenAPI · Shared API contracts and OpenAPI generation utilities
packages/openapi/src/index.ts - Zod schemas · Shared validation schemas aligned to API contracts
packages/zod/src/index.ts - Email templates · Shared TSX email templates for transactional mail
packages/emails/src/templates/welcome.tsx
Connections 30
- 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