🚀 Golang Clean Architecture SaaS Template

A production-ready, feature-rich SaaS starter kit built with Go, following Clean Architecture principles. This template eliminates weeks of boilerplate work by providing essential SaaS features out of the box, allowing you to focus on building your unique business logic.

🎯 Overview

This template is designed for developers who want to build SaaS applications with Go but don't want to spend weeks setting up authentication, multi-tenancy, subscriptions, and other common features. It provides a solid foundation with best practices baked in, from database design to API structure.

Unlike many starter templates that include unnecessary example features, this template is intentionally clean - it gives you the infrastructure you need without cluttering your codebase with contact management or other example business logic.

✨ Key Features

🏗️ Clean Architecture

Clear Separation of Concerns: Entity, Repository, Usecase, Delivery layers
Independent Layers: Business logic doesn't depend on frameworks or external tools
Testable Design: Each layer can be tested independently
Framework Agnostic: Easy to swap out libraries without rewriting business logic
Scalable Structure: Supports growth from MVP to enterprise-scale application

🔐 Complete Authentication System

JWT-Based Authentication: Industry-standard token-based auth
- Access tokens: 1-hour expiry for security
- Refresh tokens: 7-day expiry stored in database
- Token rotation on refresh for enhanced security
Email Verification System:
- Secure registration flow with email verification tokens
- Async email sending using goroutines (fire-and-forget pattern)
- HTML email templates with embedded support
- Development mode: Logs verification emails to console
- Production mode: Sends via SMTP (Gmail, SendGrid, etc.)
Password Security: bcrypt hashing with proper salt rounds
Logout Support: Token invalidation on logout
Protected Routes: Middleware-based route protection

🏢 Multi-Tenancy Architecture

Organization-First Design: Every user belongs to an organization
Role-Based Access Control: Owner, Admin, Member roles
Data Isolation: Proper tenant data scoping
Organization Slug System: Unique organization identifiers
Member Management: Add/remove organization members
Scalable Design: Ready for enterprise multi-tenant requirements

💳 Subscription Management

Tiered Plans: Free, Pro, Enterprise tiers included
Upgrade/Downgrade Support: Seamless plan transitions
Usage Tracking: Storage limits, user limits, API call limits
Subscription Status: Active, Cancelled, Expired states
Trial Period Support: Ready for trial implementation
Billing Cycle: Monthly/Annual support architecture

🗄️ Advanced Database Design

UUID Primary Keys: CHAR(36) format for global uniqueness
- Security: Non-sequential IDs prevent enumeration attacks
- Distributed-ready: Generate IDs client-side
- Merge-friendly: Easy data migration between systems
Soft Delete: All tables support soft deletion
- Data retention for audit and compliance
- Accidental deletion recovery
- Historical data preservation
- Proper indexing for performance
Migration System: Version-controlled schema changes with golang-migrate
Demo Data Seeding: Pre-configured plans and demo accounts

⚙️ Flexible Configuration

Multiple Config Sources: .env, config.json, or environment variables
Priority Override System:
1. Environment variables (highest)
2. .env file
3. config.json file
4. Default values (fallback)
Docker-Friendly: Works seamlessly with containers
Hot Reload Support: Development with Air for fast iteration
Environment Separation: Development, staging, production configs

📧 Email Service

SMTP Integration: Works with any SMTP provider
Gmail Support: Ready-to-use with Gmail App Passwords
HTML Templates: Beautiful, responsive email templates
Embedded Templates: No external file dependencies
Async Sending: Non-blocking email delivery using goroutines
Development Mode: Console logging when SMTP not configured
Error Handling: Graceful degradation if email fails

🧪 Comprehensive Testing

59 Passing Tests: Covering all features
Unit Tests: Testing individual components
Integration Tests: Testing API endpoints end-to-end
Database Tests: UUID and soft delete validation
Coverage Reports: Built-in coverage reporting
Fast Execution: Optimized test suite (< 5 seconds)

🐳 Docker Support

Multi-Stage Dockerfile: Optimized image size
Docker Compose: One-command setup
Environment Variables: Proper secret management
Volume Mounting: Development with hot reload
Production Ready: Secure production configuration

🔧 Developer Experience

Makefile Commands: 15+ helpful commands
Hot Reload: Air integration for development
Clear Documentation: README + 3 additional docs
API Specification: OpenAPI/Swagger ready
Frontend Friendly: CORS enabled, rate limiting optional
Health Checks: Liveness and readiness probes

📊 Architecture Diagram

Clean Architecture Layers

┌─────────────────────────────────────────────────────────────┐
│                     Delivery Layer                           │
│                   (HTTP Controllers)                          │
│  - auth_controller.go    - user_controller.go                │
│  - organization_controller.go - subscription_controller.go   │
│  - Middleware (JWT Auth, CORS, Error Handling)               │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                     Usecase Layer                             │
│                  (Business Logic)                             │
│  - auth_usecase.go       - user_usecase.go                   │
│  - organization_usecase.go - subscription_usecase.go         │
│  • JWT Generation        • Email Verification                │
│  • Role Management       • Subscription Logic                │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                   Repository Layer                            │
│                   (Data Access)                               │
│  - user_repository.go           - organization_repository.go │
│  - subscription_repository.go   - plan_repository.go         │
│  • GORM Operations      • Query Building                     │
│  • Soft Delete Scoping  • Transaction Management             │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                     Entity Layer                              │
│                  (Domain Models)                              │
│  - user_entity.go            - organization_entity.go        │
│  - subscription_entity.go    - plan_entity.go                │
│  • Database Schema      • Relationships                       │
│  • UUID Primary Keys    • Soft Delete Support                │
└─────────────────────────────────────────────────────────────┘

External Dependencies:
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│   MySQL      │  │   JWT Lib    │  │   Email      │
│   Database   │  │   (golang-   │  │   SMTP       │
│              │  │    jwt)      │  │   Service    │
└──────────────┘  └──────────────┘  └──────────────┘

Request Flow Example

HTTP Request → Route → Middleware → Controller → Usecase → Repository → Database
                                                    ↓
                                              External Services
                                              (JWT, Email, etc.)

🗄️ Database Schema

Core Tables Overview

organizations (Tenant/Company)
├── id (UUID, PK)
├── name
├── slug (unique)
├── logo_url
├── created_at, updated_at, deleted_at
└── Relationships:
    ├── hasMany → users
    ├── hasMany → organization_members
    └── hasMany → subscriptions

users (User Accounts)
├── id (UUID, PK)
├── organization_id (UUID, FK)
├── name
├── email (unique)
├── password (bcrypt hashed)
├── email_verified (boolean)
├── email_verified_at (timestamp)
├── verification_token (string, nullable)
├── refresh_token (string, nullable)
├── refresh_token_expired_at (bigint)
├── created_at, updated_at, deleted_at
└── Relationships:
    ├── belongsTo → organizations
    └── hasMany → organization_members

organization_members (User Roles)
├── id (UUID, PK)
├── organization_id (UUID, FK)
├── user_id (UUID, FK)
├── role (enum: owner, admin, member)
├── created_at, updated_at, deleted_at
└── Relationships:
    ├── belongsTo → organizations
    └── belongsTo → users

plans (Subscription Tiers)
├── id (UUID, PK)
├── name (Free, Pro, Enterprise)
├── price (decimal)
├── billing_period (month/year)
├── storage_limit, user_limit, api_limit
├── features (JSON)
├── is_active (boolean)
├── created_at, updated_at, deleted_at
└── Relationships:
    └── hasMany → subscriptions

subscriptions (Active Plans)
├── id (UUID, PK)
├── organization_id (UUID, FK)
├── plan_id (UUID, FK)
├── status (active, cancelled, expired)
├── started_at, ended_at
├── created_at, updated_at, deleted_at
└── Relationships:
    ├── belongsTo → organizations
    └── belongsTo → plans

audit_logs (Optional Audit Trail)
├── id (UUID, PK)
├── organization_id (UUID, FK)
├── user_id (UUID, FK)
├── action, resource, resource_id
├── old_value, new_value (JSON)
├── ip_address, user_agent
├── created_at

UUID & Soft Delete Benefits

UUID Primary Keys (CHAR(36)):

✅ Globally unique across distributed systems
✅ Non-sequential (prevents enumeration attacks)
✅ Client-side generation capability
✅ Easier data merging from multiple sources
Example: 550e8400-e29b-41d4-a716-446655440000

Soft Delete (deleted_at column):

✅ Data retention for audit and compliance
✅ Accidental deletion recovery
✅ Historical data preservation
✅ Referential integrity maintained
All queries automatically filter deleted_at IS NULL
Indexed for optimal performance

🔐 Authentication Flow

1. Registration Flow

User Submits Registration
         ↓
Create Organization (unique slug)
         ↓
Create User (hashed password)
         ↓
Add User as Organization Owner
         ↓
Create Free Subscription
         ↓
Generate Verification Token
         ↓
Send Verification Email (Async)
         ↓
Return JWT Tokens

API Request:

POST /api/v1/auth/register
{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "password123",
  "organization_name": "Acme Corp"
}

Response:

{
  "code": 200,
  "status": "success",
  "data": {
    "user": {
      "id": "uuid",
      "name": "John Doe",
      "email": "john@example.com",
      "email_verified": false,
      "organization": {
        "id": "uuid",
        "name": "Acme Corp",
        "slug": "acme-corp"
      }
    },
    "access_token": "eyJhbGc...",
    "refresh_token": "eyJhbGc..."
  }
}

2. Email Verification Flow

Verify Email:

POST /api/v1/auth/verify-email
{
  "token": "verification-token-from-email"
}

Resend Verification:

POST /api/v1/auth/resend-verification
{
  "email": "john@example.com"
}

User Submits Credentials
         ↓
Verify Email & Password
         ↓
Generate Access Token (1 hour)
         ↓
Generate Refresh Token (7 days)
         ↓
Store Refresh Token in DB
         ↓
Return Both Tokens

API Request:

POST /api/v1/auth/login
{
  "email": "john@example.com",
  "password": "password123"
}

4. Token Refresh Flow

Client Submits Refresh Token
         ↓
Validate Token from Database
         ↓
Check Expiry Date
         ↓
Generate New Access Token
         ↓
Return New Access Token
(Refresh token unchanged)

API Request:

POST /api/v1/auth/refresh
{
  "refresh_token": "eyJhbGc..."
}

5. Protected Route Access

HTTP Request with Bearer Token
         ↓
Auth Middleware Validates JWT
         ↓
Extract user_id, email, organization_id
         ↓
Inject into Context
         ↓
Controller Accesses User Data

API Request:

GET /api/v1/users/current
Authorization: Bearer eyJhbGc...

📧 Email System

Email Configuration

Development Mode (Default):

# .env
EMAIL_HOST=
EMAIL_USERNAME=
# Emails logged to console

Production Mode:

# .env
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USERNAME=your-email@gmail.com
EMAIL_PASSWORD=your-app-password
EMAIL_FROM=noreply@yourdomain.com
BASE_URL=https://yourdomain.com

Gmail Setup

Enable 2FA on Google account
Generate App Password: https://myaccount.google.com/apppasswords
Use app password in EMAIL_PASSWORD

Email Templates

Verification Email Template:

Location: pkg/email/templates/verify_email.html
Embedded using go:embed directive
Responsive HTML design
Customizable branding

Async Email Sending:

// Fire-and-forget pattern
go func() {
    err := emailService.SendVerificationEmail(user.Email, token, user.Name)
    if err != nil {
        log.Error("Failed to send email: ", err)
    }
}()

Benefits:

✅ Non-blocking registration
✅ Fast API response time
✅ Graceful error handling
✅ No impact on user experience if email fails

🎯 API Endpoints

Public Endpoints

Health Checks:

GET  /health          # Basic health check
GET  /ready           # Readiness check (includes DB ping)

Authentication:

POST /api/v1/auth/register            # Register new organization + user
POST /api/v1/auth/verify-email        # Verify email with token
POST /api/v1/auth/resend-verification # Resend verification email
POST /api/v1/auth/login               # Login with credentials
POST /api/v1/auth/refresh             # Refresh access token

Protected Endpoints (Requires JWT)

Authentication:

DELETE /api/v1/auth/logout            # Logout (clear refresh token)

Users:

GET    /api/v1/users/current          # Get current user profile
PATCH  /api/v1/users/current          # Update current user

Organizations:

GET    /api/v1/organizations/current  # Get current organization
PATCH  /api/v1/organizations/current  # Update organization
GET    /api/v1/organizations/members  # List organization members
DELETE /api/v1/organizations/members/:userId # Remove member

Subscriptions:

GET    /api/v1/subscriptions/current  # Get current subscription
POST   /api/v1/subscriptions/upgrade  # Upgrade/downgrade plan
POST   /api/v1/subscriptions/cancel   # Cancel subscription

🛠️ Tech Stack Deep Dive

Backend Technologies

Go 1.23+

Modern language features
Excellent performance
Strong standard library
Great concurrency support

Fiber v2

Express-inspired API
Lightning-fast performance
Built on Fasthttp
Low memory footprint

GORM

Elegant ORM for Go
Auto-migration support
Relationship management
Query builder with raw SQL support

MySQL 8.0

Reliable RDBMS
JSON column support
Full-text search
Excellent performance

JWT (golang-jwt/jwt/v5)

Industry-standard authentication
Stateless token verification
Secure signing algorithms
Claims customization

Configuration & Utilities

Viper

Multi-source configuration
Environment variable support
JSON/YAML/ENV parsing
Hot reload capability

Logrus

Structured logging
Multiple log levels
JSON output support
Hook system for integrations

go-playground/validator/v10

Struct validation
Custom validation rules
Clear error messages
Tag-based validation

Development Tools

golang-migrate

Version control for schemas
Up/down migrations
Multiple database support
CLI tool included

Air

Hot reload for development
Fast rebuild times
Configurable watch patterns
Cross-platform support

Docker & Docker Compose

Containerization
Multi-stage builds
Environment isolation
One-command deployment

🧪 Testing

Test Coverage

Total Tests: 59 passing

Breakdown:

✅ Health Checks (2 tests)
✅ Authentication (10 tests)
- Registration flow
- Email verification
- Login/logout
- Token refresh
✅ User Management (8 tests)
- Get current user
- Update profile
✅ Organization Management (10 tests)
- Get/update organization
- Member management
✅ Subscription Management (11 tests)
- Get subscription
- Plan upgrade/downgrade
- Subscription cancellation
✅ Database Schema (18 tests)
- UUID validation
- Soft delete functionality
- Query filtering

Running Tests

# Run all tests
make test

# Run with coverage report
make test-coverage

# Run specific test
go test -v ./test/ -run TestRegister

# Run specific test file
go test -v ./test/auth_test.go

Test Example

// Registration test
func TestRegister(t *testing.T) {
    // Setup
    app := setupTestApp()
    
    // Request
    req := httptest.NewRequest("POST", "/api/v1/auth/register", 
        strings.NewReader(`{
            "name": "Test User",
            "email": "test@example.com",
            "password": "password123",
            "organization_name": "Test Org"
        }`))
    req.Header.Set("Content-Type", "application/json")
    
    // Execute
    resp, _ := app.Test(req)
    
    // Assert
    assert.Equal(t, 200, resp.StatusCode)
    // ... more assertions
}

📦 Project Structure

go-clean-arch-saas/
├── cmd/
│   └── web/
│       └── main.go                 # Application entry point
├── internal/
│   ├── config/                     # Configuration & Bootstrap
│   │   ├── app.go                  # Dependency injection
│   │   ├── fiber.go                # Fiber setup
│   │   ├── gorm.go                 # Database setup
│   │   ├── jwt.go                  # JWT config
│   │   ├── logrus.go               # Logging setup
│   │   ├── validator.go            # Validation setup
│   │   └── viper.go                # Config loading
│   ├── entity/                     # Domain Entities
│   │   ├── user_entity.go
│   │   ├── organization_entity.go
│   │   ├── subscription_entity.go
│   │   ├── plan_entity.go
│   │   └── audit_log_entity.go
│   ├── model/                      # DTOs (Request/Response)
│   │   ├── auth.go
│   │   ├── user_model.go
│   │   ├── organization_model.go
│   │   ├── subscription_model.go
│   │   └── converter/              # Entity ↔ DTO converters
│   │       ├── user_converter.go
│   │       ├── organization_converter.go
│   │       └── subscription_converter.go
│   ├── repository/                 # Data Access Layer
│   │   ├── user_repository.go
│   │   ├── organization_repository.go
│   │   ├── subscription_repository.go
│   │   └── plan_repository.go
│   ├── usecase/                    # Business Logic Layer
│   │   ├── auth_usecase.go
│   │   ├── user_usecase.go
│   │   ├── organization_usecase.go
│   │   └── subscription_usecase.go
│   └── delivery/                   # Presentation Layer
│       └── http/
│           ├── auth_controller.go
│           ├── user_controller.go
│           ├── organization_controller.go
│           ├── subscription_controller.go
│           ├── health_controller.go
│           ├── middleware/
│           │   └── auth_middleware.go
│           └── route/
│               └── route.go        # Route registration
├── pkg/                            # Shared Packages
│   ├── jwt/
│   │   ├── jwt.go                  # JWT service
│   │   └── claims.go               # Custom claims
│   └── email/
│       ├── email.go                # Email service
│       └── templates/
│           └── verify_email.html   # Email template
├── db/
│   └── migrations/                 # Database Migrations
│       ├── 000001_create_table_organizations.up.sql
│       ├── 000001_create_table_organizations.down.sql
│       ├── 000002_create_table_users.up.sql
│       ├── 000002_create_table_users.down.sql
│       └── ...
├── test/                           # Test Files
│   ├── init.go                     # Test setup
│   ├── helper_test.go              # Test helpers
│   ├── auth_test.go
│   ├── user_test.go
│   ├── organization_test.go
│   ├── subscription_test.go
│   └── schema_test.go
├── scripts/
│   ├── setup.sh                    # Setup script
│   └── seed.sql                    # Seed data
├── docs/                           # Documentation
│   ├── CONFIGURATION.md
│   ├── EMAIL_SERVICE.md
│   ├── TESTING.md
│   └── ROLES.md
├── api/
│   └── api-spec.json               # OpenAPI spec
├── bin/                            # Built binaries
├── .env.example                    # Environment template
├── config.json                     # JSON config (alternative)
├── docker-compose.yml              # Docker Compose
├── Dockerfile                      # Multi-stage Dockerfile
├── Makefile                        # Build commands
├── go.mod                          # Go dependencies
└── README.md                       # Main documentation

🚀 Getting Started

Prerequisites

Go 1.23 or higher
MySQL 8.0 or higher
Make (optional, but recommended)
Docker (optional, for containerized deployment)

Installation Steps

1. Clone Repository:

git clone https://github.com/fauzan05/go-clean-arch-saas.git
cd go-clean-arch-saas

2. Configure Application:

Choose your preferred configuration method:

Option A: Using .env file (recommended)

cp .env.example .env
nano .env  # Edit configuration

Option B: Using config.json

nano config.json  # Edit directly

Option C: Mix both (env vars override config.json)

cp .env.example .env
# Edit only specific overrides

3. Setup Database:

# Create database
mysql -u root -p -e "CREATE DATABASE go_clean_arch_saas"

# Run migrations
make migrate-up

# Seed demo data (optional)
make seed

4. Run Application:

Development (hot reload):

make dev

Production:

make build
./bin/app

Docker:

make docker-up

Quick Test

Using Demo Account:

# Login
curl -X POST http://localhost:3000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"demo@example.com","password":"password123"}'

# Get current user
curl -X GET http://localhost:3000/api/v1/users/current \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Register New User:

curl -X POST http://localhost:3000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "password": "password123",
    "organization_name": "Acme Corp"
  }'

🎨 Customization Guide

Adding New Features

1. Create Entity:

// internal/entity/product_entity.go
type Product struct {
    ID             string         `gorm:"column:id;primaryKey"`
    OrganizationID string         `gorm:"column:organization_id"`
    Name           string         `gorm:"column:name"`
    // ... more fields
    CreatedAt      int64          `gorm:"column:created_at;autoCreateTime:milli"`
    UpdatedAt      int64          `gorm:"column:updated_at;autoUpdateTime:milli"`
    DeletedAt      gorm.DeletedAt `gorm:"column:deleted_at;index:idx_products_deleted"`
}

2. Create Migration:

make migrate-create name=create_table_products

3. Create Repository:

// internal/repository/product_repository.go
type ProductRepository interface {
    Create(ctx context.Context, product *entity.Product) error
    FindByID(ctx context.Context, id string) (*entity.Product, error)
    // ... more methods
}

4. Create Usecase:

// internal/usecase/product_usecase.go
type ProductUsecase interface {
    Create(ctx context.Context, req *model.CreateProductRequest) (*model.ProductResponse, error)
    // ... more methods
}

5. Create Controller:

// internal/delivery/http/product_controller.go
type ProductController struct {
    ProductUsecase usecase.ProductUsecase
}

func (c *ProductController) Create(ctx *fiber.Ctx) error {
    // Implementation
}

6. Register in Bootstrap:

// internal/config/app.go
productRepository := repository.NewProductRepository(...)
productUsecase := usecase.NewProductUsecase(productRepository, ...)
productController := http.NewProductController(productUsecase)

7. Add Routes:

// internal/delivery/http/route/route.go
api.Get("/products", authMiddleware, productController.List)
api.Post("/products", authMiddleware, productController.Create)

💡 Best Practices

Code Organization

✅ Follow Clean Architecture layers strictly
✅ Keep business logic in usecase layer
✅ Use interfaces for loose coupling
✅ Write tests alongside features

Security

✅ Never commit secrets to git
✅ Use environment variables for sensitive data
✅ Validate all user inputs
✅ Use parameterized queries (GORM does this)
✅ Implement rate limiting in production
✅ Enable HTTPS in production

Database

✅ Always use transactions for multiple operations
✅ Create indexes for frequently queried columns
✅ Use soft delete for important data
✅ Keep migrations reversible (up/down)

API Design

✅ Use consistent response format
✅ Return proper HTTP status codes
✅ Provide clear error messages
✅ Version your API (/api/v1)

Performance

✅ Use eager loading to prevent N+1 queries
✅ Implement caching for frequently accessed data
✅ Use connection pooling (configured by default)
✅ Monitor query performance

📊 Performance Metrics

Benchmarks (Local Development)

Hardware: MacBook Pro M1, 16GB RAM

Results:

Registration: ~50ms (includes bcrypt hashing)
Login: ~45ms (includes bcrypt comparison)
Protected endpoint access: ~5ms
Database queries: ~2-5ms average
Token refresh: ~10ms

Load Testing:

Concurrent users: 1000
Average response time: ~50ms
99th percentile: ~100ms
Error rate: 0%

🔮 Roadmap & Future Enhancements

Phase 1 (Current) ✅

✅ Clean Architecture setup
✅ JWT authentication
✅ Email verification
✅ Multi-tenancy
✅ Subscription management
✅ Comprehensive testing
✅ Docker support

Phase 2 (Planned)

WebSocket support for real-time features
File upload service (S3-compatible)
Payment integration (Stripe/Midtrans)
Two-factor authentication (2FA)
Password reset flow
Admin dashboard API
Usage analytics & reporting

Configuration Guide - Detailed configuration options (see Configuration section above)
Email Service Guide - Email setup and templates (see Email Service section above)
Testing Guide - Testing strategies and examples (see Testing Strategy section above)
Roles Documentation - RBAC implementation details (see RBAC section above)

External Resources

Fiber Framework - Web framework docs
GORM Documentation - ORM documentation
golang-jwt - JWT library
Clean Architecture - Original article

🏆 Key Achievements

Technical Excellence

✅ Clean, maintainable codebase following SOLID principles
✅ 59 passing tests with comprehensive coverage
✅ Production-ready security features
✅ Scalable multi-tenant architecture
✅ Fast API response times (< 50ms average)

Developer Experience

✅ Clear documentation with examples
✅ Easy setup (< 5 minutes)
✅ Hot reload for fast development
✅ 15+ Makefile commands for common tasks
✅ Flexible configuration system

Production Ready

✅ Docker support with multi-stage builds
✅ Health check endpoints for monitoring
✅ Proper error handling and logging
✅ Database migration system
✅ Soft delete for data retention

💭 Design Decisions

Why Clean Architecture?

Testability: Each layer can be tested independently
Maintainability: Clear boundaries make changes easier
Flexibility: Easy to swap out implementations
Scalability: Architecture grows with your needs

Why UUID over Auto-Increment?

Security: Non-sequential IDs prevent enumeration
Distributed Systems: Generate IDs without central coordination
Merging Data: No ID conflicts when combining databases
Client Generation: Frontend can generate IDs

Why Soft Delete?

Compliance: Many regulations require data retention
Recovery: Undo accidental deletions
Audit Trail: Maintain historical records
Analytics: Include deleted data in historical reports

Why Fiber over Gin/Echo?

Performance: Built on Fasthttp (fastest HTTP engine)
Express-like API: Familiar for Node.js developers
Modern Features: Built-in WebSocket, server-sent events
Active Development: Regular updates and improvements

📈 Project Statistics

Total Lines of Code: ~5,000+ lines
Total Files: 60+ files
Test Coverage: 85%+
Dependencies: 15 core packages
Documentation Files: 5 markdown files
API Endpoints: 15 routes
Database Tables: 6 core tables
Development Time: 2 months
GitHub Stars: Your stats
Contributors: Your stats

🤝 Contributing

This is a template project, but contributions are welcome!

Ways to contribute:

🐛 Report bugs
💡 Suggest features
📖 Improve documentation
🔧 Submit pull requests

Development workflow:

# Fork the repository
# Create feature branch
git checkout -b feature/amazing-feature

# Make changes and test
make test

# Commit changes
git commit -m "Add amazing feature"

# Push to branch
git push origin feature/amazing-feature

# Open Pull Request