A Go microservices template following Clean Architecture principles with event sourcing support.
- Clean Architecture with domain-driven design
- Event Sourcing via pericarp library
- Dependency Injection with Uber Fx
- Dual Entry Points - API server (Echo) + CLI (Cobra)
- Auto-detecting Database - SQLite for development, PostgreSQL for production
- Frontend Embedding - Single-binary deployment with SPA support
- Structured Logging - Zap with interface abstraction
- KSUID Identity - Time-sortable, URL-safe entity IDs
- Auth Ready - Pericarp auth integration with OAuth/session support
myapp/
├── application/ # DI module and service providers
├── cmd/
│ ├── api/ # API server entry point
│ └── cli/ # CLI entry point
├── domain/ # Domain entities and business logic
│ ├── entities/ # Domain entities (embed ddd.BaseEntity)
│ ├── repositories/ # Repository interfaces
│ └── services/ # Domain services
├── infrastructure/ # External concerns
│ ├── database/ # GORM database provider
│ ├── events/ # Event dispatcher provider
│ ├── external/ # External service clients
│ ├── logging/ # Zap logging implementation
│ └── models/ # GORM models
├── api/ # API layer
│ ├── handlers/ # HTTP handlers
│ ├── middleware/ # HTTP middleware (SPA, auth)
│ └── validators/ # Request validators
├── pkg/ # Public packages
│ ├── errors/ # Error definitions
│ ├── identity/ # KSUID-based entity ID generation
│ ├── utils/ # Utility functions
│ └── validators/ # Validation utilities
├── internal/ # Private application code
│ ├── auth/ # Authentication logic
│ ├── cli/ # Cobra CLI setup and DI
│ ├── config/ # Configuration management
│ ├── logging/ # Logging utilities
│ └── observability/ # OpenTelemetry setup
├── web/ # Embedded frontend assets
├── tests/ # Test files
│ ├── unit/ # Unit tests
│ ├── integration/ # Integration tests
│ ├── e2e/ # E2E tests (Godog/Gherkin)
│ └── newman/ # API canary tests
├── config/ # Configuration files
├── migrations/ # Database migrations
├── scripts/ # Utility scripts
└── docs/ # Documentation
- Clone and rename the module:
# Update go.mod module name
# Find and replace "myapp" with your module name across all Go files- Install dependencies:
make deps- Run the API server:
make run- Build all binaries:
make buildAll dependencies are wired in application/module.go. Add providers and invoke hooks there.
Domain entities embed *ddd.BaseEntity and record events via RecordEvent(). Services use SimpleUnitOfWork for atomic event persistence and dispatch.
Three-layer precedence: Defaults -> Environment Variables -> CLI Flags.
Auto-detects SQLite vs PostgreSQL from DSN format. Use SQLite locally, PostgreSQL in production.
See CONTRIBUTING.md for contribution guidelines.