{"id":41090860,"url":"https://github.com/allisson/go-project-template","last_synced_at":"2026-01-29T22:09:08.603Z","repository":{"id":334036828,"uuid":"1139250942","full_name":"allisson/go-project-template","owner":"allisson","description":"A production-ready Go project template following Clean Architecture principles","archived":false,"fork":false,"pushed_at":"2026-01-24T23:53:59.000Z","size":144,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-25T03:11:23.505Z","etag":null,"topics":["clean-architecture","docker","golang"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/allisson.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-21T18:06:08.000Z","updated_at":"2026-01-24T23:50:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/allisson/go-project-template","commit_stats":null,"previous_names":["allisson/go-project-template"],"tags_count":9,"template":true,"template_full_name":null,"purl":"pkg:github/allisson/go-project-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allisson%2Fgo-project-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allisson%2Fgo-project-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allisson%2Fgo-project-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allisson%2Fgo-project-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/allisson","download_url":"https://codeload.github.com/allisson/go-project-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allisson%2Fgo-project-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28886978,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-29T21:06:44.224Z","status":"ssl_error","status_checked_at":"2026-01-29T21:06:42.160Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clean-architecture","docker","golang"],"created_at":"2026-01-22T14:39:43.302Z","updated_at":"2026-01-29T22:09:08.596Z","avatar_url":"https://github.com/allisson.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 Go Project Template\n\n\u003e A production-ready Go project template following Clean Architecture and Domain-Driven Design principles, optimized for building scalable applications with PostgreSQL or MySQL.\n\n[![CI](https://github.com/allisson/go-project-template/workflows/CI/badge.svg)](https://github.com/allisson/go-project-template/actions)\n[![Go Report Card](https://goreportcard.com/badge/github.com/allisson/go-project-template)](https://goreportcard.com/report/github.com/allisson/go-project-template)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## ✨ Features\n\n- 🏗️ **Clean Architecture** - Clear separation of concerns with domain, repository, use case, and presentation layers\n- 📦 **Modular Domain Structure** - Easy to add new domains without affecting existing code\n- 🔌 **Dependency Injection** - Centralized component wiring with lazy initialization\n- 🗄️ **Multi-Database Support** - PostgreSQL and MySQL with dedicated repository implementations\n- 🔄 **Database Migrations** - Separate migrations for PostgreSQL and MySQL\n- 🆔 **UUIDv7 Primary Keys** - Time-ordered, globally unique identifiers\n- 💼 **Transaction Management** - Built-in support for database transactions\n- 📬 **Transactional Outbox Pattern** - Event-driven architecture with guaranteed delivery\n- ⚠️ **Standardized Error Handling** - Domain errors with proper HTTP status code mapping\n- ✅ **Input Validation** - Advanced validation with custom rules (email, password strength, etc.)\n- 🔒 **Password Hashing** - Secure Argon2id password hashing\n- 🧪 **Integration Testing** - Real database tests instead of mocks\n- 🐳 **Docker Support** - Multi-stage Dockerfile and Docker Compose setup\n- 🚦 **CI/CD Ready** - GitHub Actions workflow with comprehensive testing\n- 📊 **Structured Logging** - JSON logs using slog\n- 🛠️ **Comprehensive Makefile** - Easy development and deployment commands\n\n## 📚 Documentation\n\n- 📖 [Getting Started](docs/getting-started.md) - Installation and setup guide\n- 🏗️ [Architecture](docs/architecture.md) - Architectural patterns and design principles\n- 🛠️ [Development](docs/development.md) - Development workflow and coding standards\n- 🧪 [Testing](docs/testing.md) - Testing strategies and best practices\n- ⚠️ [Error Handling](docs/error-handling.md) - Error handling system guide\n- ➕ [Adding Domains](docs/adding-domains.md) - Step-by-step guide to add new domains\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Go 1.25+\n- PostgreSQL 12+ or MySQL 8.0+\n- Docker and Docker Compose (optional)\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/allisson/go-project-template.git\ncd go-project-template\n\n# Install dependencies\ngo mod download\n\n# Start a database (using Docker)\nmake dev-postgres  # or make dev-mysql\n\n# Run migrations\nmake run-migrate\n\n# Start the server\nmake run-server\n```\n\nThe server will be available at http://localhost:8080\n\nFor detailed setup instructions, see the [Getting Started Guide](docs/getting-started.md).\n\n## 📖 Project Structure\n\n```\ngo-project-template/\n├── cmd/app/                    # Application entry point\n├── internal/\n│   ├── app/                    # Dependency injection container\n│   ├── config/                 # Configuration management\n│   ├── database/               # Database connection and transactions\n│   ├── errors/                 # Standardized domain errors\n│   ├── http/                   # HTTP server infrastructure\n│   ├── httputil/               # HTTP utilities (JSON responses, error mapping)\n│   ├── validation/             # Custom validation rules\n│   ├── testutil/               # Test utilities\n│   ├── user/                   # User domain module\n│   │   ├── domain/             # User entities and domain errors\n│   │   ├── usecase/            # User business logic\n│   │   ├── repository/         # User data access\n│   │   └── http/               # User HTTP handlers and DTOs\n│   └── outbox/                 # Outbox domain module\n│       ├── domain/             # Outbox entities and domain errors\n│       ├── usecase/            # Outbox event processing logic\n│       └── repository/         # Outbox data access\n├── migrations/\n│   ├── postgresql/             # PostgreSQL migrations\n│   └── mysql/                  # MySQL migrations\n├── docs/                       # Documentation\n├── Dockerfile\n├── Makefile\n└── docker-compose.test.yml\n```\n\nLearn more about the architecture in the [Architecture Guide](docs/architecture.md).\n\n## 🧪 Testing\n\n```bash\n# Start test databases\nmake test-db-up\n\n# Run all tests\nmake test\n\n# Run tests with coverage\nmake test-coverage\n\n# Stop test databases\nmake test-db-down\n\n# Or run everything in one command\nmake test-with-db\n```\n\nThe project uses real PostgreSQL and MySQL databases for testing instead of mocks. See the [Testing Guide](docs/testing.md) for details.\n\n## 🛠️ Development\n\n### Build Commands\n\n```bash\nmake build                    # Build the application\nmake run-server              # Run HTTP server\nmake run-worker              # Run outbox event processor\nmake run-migrate             # Run database migrations\nmake lint                    # Run linter with auto-fix\nmake clean                   # Clean build artifacts\n```\n\n### API Endpoints\n\n#### Health Check\n```bash\ncurl http://localhost:8080/health\n```\n\n#### Register User\n```bash\ncurl -X POST http://localhost:8080/api/users \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"John Doe\",\n    \"email\": \"john@example.com\",\n    \"password\": \"SecurePass123!\"\n  }'\n```\n\nFor more development workflows, see the [Development Guide](docs/development.md).\n\n## 🔑 Key Concepts\n\n### Clean Architecture Layers\n\n- **Domain Layer** 🎯 - Business entities and rules (pure, no external dependencies)\n- **Repository Layer** 💾 - Data persistence (separate MySQL and PostgreSQL implementations)\n- **Use Case Layer** 💼 - Business logic and orchestration\n- **Presentation Layer** 🌐 - HTTP handlers and DTOs\n- **Utility Layer** 🛠️ - Shared utilities (error handling, validation, HTTP helpers)\n\n### Error Handling System\n\nThe project uses a standardized error handling system:\n\n- **Standard Errors**: `ErrNotFound`, `ErrConflict`, `ErrInvalidInput`, `ErrUnauthorized`, `ErrForbidden`\n- **Domain Errors**: Wrap standard errors with domain-specific context\n- **Automatic HTTP Mapping**: Domain errors automatically map to appropriate HTTP status codes\n\nExample:\n```go\n// Define domain error\nvar ErrUserNotFound = errors.Wrap(errors.ErrNotFound, \"user not found\")\n\n// Use in repository\nif errors.Is(err, sql.ErrNoRows) {\n    return nil, domain.ErrUserNotFound  // Maps to 404 Not Found\n}\n```\n\nLearn more in the [Error Handling Guide](docs/error-handling.md).\n\n### UUIDv7 Primary Keys\n\nAll entities use UUIDv7 for primary keys:\n- ⏱️ Time-ordered for better database performance\n- 🌍 Globally unique across distributed systems\n- 📊 Better than UUIDv4 for database indexes\n\n### Transactional Outbox Pattern\n\nEnsures reliable event delivery using a use case-based approach:\n1. Business operation and event stored in same transaction\n2. Outbox use case processes pending events with configurable retry logic\n3. Guarantees at-least-once delivery\n4. Extensible event processing via the `EventProcessor` interface\n\n## 🐳 Docker\n\n```bash\n# Build Docker image\nmake docker-build\n\n# Run server in Docker\nmake docker-run-server\n\n# Run worker in Docker\nmake docker-run-worker\n\n# Run migrations in Docker\nmake docker-run-migrate\n```\n\nThe worker command runs the outbox event processor, which handles asynchronous event processing using the transactional outbox pattern.\n\n## 🔧 Configuration\n\nAll configuration is done via environment variables. Create a `.env` file in your project root:\n\n```bash\nDB_DRIVER=postgres\nDB_CONNECTION_STRING=postgres://user:password@localhost:5432/mydb?sslmode=disable\nSERVER_HOST=0.0.0.0\nSERVER_PORT=8080\nLOG_LEVEL=info\n```\n\nSee the [Getting Started Guide](docs/getting-started.md) for all available configuration options.\n\n## ➕ Adding New Domains\n\nAdding a new domain is straightforward:\n\n1. Create domain structure (`domain/`, `usecase/`, `repository/`, `http/`)\n2. Define domain entity and errors\n3. Create database migrations\n4. Implement repositories (PostgreSQL and MySQL)\n5. Implement use case with business logic\n6. Create DTOs and HTTP handlers\n7. Register in DI container\n8. Wire HTTP routes\n\nSee the [Adding Domains Guide](docs/adding-domains.md) for a complete step-by-step tutorial.\n\n## 📦 Dependencies\n\n### Core Libraries\n\n- [google/uuid](https://github.com/google/uuid) - UUID generation (UUIDv7 support)\n- [jellydator/validation](https://github.com/jellydator/validation) - Advanced input validation\n- [urfave/cli](https://github.com/urfave/cli) - CLI framework\n- [allisson/go-env](https://github.com/allisson/go-env) - Environment configuration\n- [allisson/go-pwdhash](https://github.com/allisson/go-pwdhash) - Argon2id password hashing\n- [golang-migrate/migrate](https://github.com/golang-migrate/migrate) - Database migrations\n\n### Database Drivers\n\n- [lib/pq](https://github.com/lib/pq) - PostgreSQL driver\n- [go-sql-driver/mysql](https://github.com/go-sql-driver/mysql) - MySQL driver\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'feat: add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\nThis template leverages these excellent Go libraries:\n- github.com/allisson/go-env\n- github.com/allisson/go-pwdhash\n- github.com/jellydator/validation\n- github.com/google/uuid\n- github.com/urfave/cli\n- github.com/golang-migrate/migrate\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  \u003csub\u003eBuilt with ❤️ by \u003ca href=\"https://github.com/allisson\"\u003eAllisson\u003c/a\u003e\u003c/sub\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fallisson%2Fgo-project-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fallisson%2Fgo-project-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fallisson%2Fgo-project-template/lists"}