Skip to content

README.md

Latest commit

 

History

History
118 lines (88 loc) · 5.79 KB

README.md

File metadata and controls

118 lines (88 loc) · 5.79 KB

Go Modulith Template 🚀

Go Modulith Architecture

Tests Coverage Go License

This is a professional, production-ready template for building Go applications following the Modular Monolith (Modulith) pattern. Designed for high-performance, maintainability, and scalability, it allows your application to evolve from a monolith to microservices without architectural friction.

✨ Key Features

  • 🏗️ Modular Architecture: Clean domain boundaries with decoupling via an internal Event Bus.
  • 📦 Registry Pattern: Explicit dependency injection without magic for maximum control and testability.
  • 🔐 gRPC & Protobuf: High-performance, type-safe RPC communication with automated generation via buf.
  • 🗄️ SQLC & Migrations: Type-safe data access and multi-module schema management with golang-migrate.
  • ⚡ High-Performance Caching: Native support for Valkey (the open-source Valkey alternative) for sessions and rate limiting.
  • 🔐 Complete Auth System: Passwordless login, sessions, JWT, refresh tokens, and RBAC.
  • 🔗 OAuth/Social Login: Integrated with Goth for Google, Facebook, GitHub, Apple, Microsoft, and Twitter/X.
  • 🤖 Messaging Bot Engine: Built-in support for WhatsApp and Telegram provider integrations.
  • 🔌 WebSocket Real-Time: Bidirectional communication integrated with the event bus for instant notifications.
  • 📊 Observability Stack: Native integration with OpenTelemetry, Jaeger (Tracing), Prometheus (Metrics), and Grafana dashboards.
  • ⚙️ Flexible Configuration: Hierarchy-based system (PORT > YAML > .env > system ENV > defaults) with source logging.
  • ⚡ Resilience & Errors: Integrated circuit breakers, retries, and a domain-specific error system mapped to gRPC codes.
  • 📧 Notification System: Extensible providers (SendGrid, Twilio, AWS SES/SNS) with template support.
  • 📊 Optional GraphQL: Advanced support with gqlgen for flexible frontend APIs (subscriptions included).
  • 🧪 Test Utilities: Comprehensive suite (internal/testutil) for integration tests with Testcontainers, gRPC servers, and mocks.
  • 🛠️ DevX Excellence: Hot reload with Air, task automation with Just, and environment diagnostics with doctor.

🛠️ Prerequisites

  • Go 1.25+
  • Docker & Docker Compose
  • Development tools: sqlc, buf, migrate, air, golangci-lint, just.

🚀 Quick Start

1. Automated Setup & Run (Recommended)

The fastest way to get started is using the integrated setup and run command:

git clone https://github.com/LoopContext/go-modulith-template.git my-project
cd my-project
just dev

This single command will:

  1. Start the minimal Docker infrastructure (DB + Valkey).
  2. Wait for the database to be ready.
  3. Run all database migrations.
  4. Seed the database with test users (admin, system, user).
  5. Install frontend dependencies (web/solid-example).
  6. Start the full stack (Backend + Frontend) with Hot Reload in a 3-pane tmux session.

2. See it in Action

To run a complete representative flow (E2E) and see how the system handles Auth, Events, and Logic:

just example

💡 Tip: For a full "setup + example" demo in one go, use just demo.

3. Development Mode

Run the monolith with hot reload (monitors code, proto, sql, and configs):

just dev

Run a specific module (e.g., auth):

just dev-module auth

🏗️ Project Structure

  • cmd/: Main entry points (server, worker, admin tasks, migration ops).
  • internal/: Core shared services (registry, cache, events, authz, telemetry).
  • modules/: Domain-specific modules (auth, stock, etc.). Each module is independent.
  • proto/: Protobuf definitions for gRPC and Event schemas.
  • scripts/: Utility scripts for DevX (scaffolding, validation, e2e).
  • web/: Documentation site and optional frontend examples.

📖 Complete Documentation

🛠️ Main Commands (just)

  • just proto: Generate gRPC and OpenAPI code.
  • just sqlc: Generate type-safe SQL code.
  • just new-module <name>: Scaffold a new domain module.
  • just setup: Automated, non-interactive setup (infra + migrate + seed).
  • just example: Run a representative example flow (E2E) to see the system in action.
  • just demo: Complete end-to-end demo (setup + example).
  • just test: Run all unit and integration tests.
  • just lint: Run strict linter (MANDATORY for quality).
  • just visualize: Generate an interactive module graph (docs/module-graph.html) with modules (gRPC + event bus) and database (tables from migrations) views; also FORMAT=json|dot for machine-readable output.
  • just admin TASK=<name>: Execute maintenance tasks (e.g., cleanup-sessions).

Made with ❤️ for developers seeking operational excellence.