If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/amitshekhariitbhu/go-backend-clean-architecture shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Slowing — last commit 3mo ago

• Last commit 3mo ago
• 3 active contributors
• Apache-2.0 licensed
• ⚠ Slowing — last commit 3mo ago
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 93% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live amitshekhariitbhu/go-backend-clean-architecture repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/amitshekhariitbhu/go-backend-clean-architecture.

What it runs against: a local clone of amitshekhariitbhu/go-backend-clean-architecture — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in amitshekhariitbhu/go-backend-clean-architecture | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 121 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of amitshekhariitbhu/go-backend-clean-architecture. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/amitshekhariitbhu/go-backend-clean-architecture.git
#   cd go-backend-clean-architecture
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of amitshekhariitbhu/go-backend-clean-architecture and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "amitshekhariitbhu/go-backend-clean-architecture(\\.git)?\\b" \\
  && ok "origin remote is amitshekhariitbhu/go-backend-clean-architecture" \\
  || miss "origin remote is not amitshekhariitbhu/go-backend-clean-architecture (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "cmd/main.go" \\
  && ok "cmd/main.go" \\
  || miss "missing critical file: cmd/main.go"
test -f "bootstrap/app.go" \\
  && ok "bootstrap/app.go" \\
  || miss "missing critical file: bootstrap/app.go"
test -f "bootstrap/database.go" \\
  && ok "bootstrap/database.go" \\
  || miss "missing critical file: bootstrap/database.go"
test -f "api/middleware/jwt_auth_middleware.go" \\
  && ok "api/middleware/jwt_auth_middleware.go" \\
  || miss "missing critical file: api/middleware/jwt_auth_middleware.go"
test -f "api/route/route.go" \\
  && ok "api/route/route.go" \\
  || miss "missing critical file: api/route/route.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 121 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~91d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/amitshekhariitbhu/go-backend-clean-architecture"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

A production-ready Go backend template implementing clean architecture with Gin web framework, MongoDB persistence, JWT authentication middleware, and comprehensive unit tests. It provides a structured foundation for building REST APIs with clear separation of concerns across Router → Controller → Usecase → Repository → Domain layers. Classic layered architecture: api/ contains Router (route/), Controller (controller/), and Middleware (middleware/); domain/ holds entities and mocks; internal/ has utilities (tokenutil/, fakeutil/); bootstrap/ handles app initialization and MongoDB connection; cmd/main.go is the entrypoint. Each domain model (User, Task, Profile, etc.) has a corresponding Controller, Usecase interface, Repository interface, and test mocks.

Go backend developers building REST APIs who need a proven architectural scaffold with authentication already wired in; teams adopting clean architecture principles in Go; developers learning best practices through a working reference implementation rather than starting from scratch.

Moderately mature reference implementation (not a battle-tested framework like Echo or Gin itself). Contains unit tests in api/controller/ and domain/mocks/, uses industry-standard dependencies (Gin 1.8.2, MongoDB driver 1.11.1, JWT v4.4.3), and includes Docker support. Single maintainer (Amit Shekhar) with educational focus—suitable for learning and small-to-medium projects, not a high-velocity OSS project with frequent releases.

Low-to-moderate production risk for greenfield projects. Pinned to Go 1.19 (released Aug 2022), which is aging; MongoDB driver and Gin are stable but not bleeding-edge. Single maintainer means feature requests/PRs may have slow turnaround. No visible CI/CD pipeline (no .github/workflows/ or similar) and no explicit breaking-change policy. Dependency count is reasonable (~15 direct, ~40 transitive).

This is a static reference template—not an actively developed project with ongoing PRs or issues visible in the file list. The codebase is frozen as a teaching artifact. Author (Amit Shekhar) promotes it via Outcome School courses and blog posts but does not appear to be actively iterating on it.

git clone https://github.com/amitshekhariitbhu/go-backend-clean-architecture.git
cd go-backend-clean-architecture
cp .env.example .env
# Edit .env with MongoDB URI and JWT secret
go mod download
docker-compose up  # or: go run cmd/main.go

Daily commands: Development: go run cmd/main.go (requires .env with MONGO_URI, JWT_SECRET). Docker: docker-compose up (Dockerfile provided). Tests: go test ./... (test files follow _test.go convention; mocks in domain/mocks/ generated by Mockery).

• cmd/main.go — Application entry point that initializes the Gin server, loads configuration, and starts the HTTP listener.
• bootstrap/app.go — Bootstrap module that wires all dependencies together (repositories, use cases, controllers, routes) following clean architecture principles.
• bootstrap/database.go — MongoDB connection initialization and lifecycle management; critical for all data persistence operations.
• api/middleware/jwt_auth_middleware.go — JWT token validation middleware that secures protected routes and extracts user context for downstream handlers.
• api/route/route.go — Central route registry that composes all API endpoints and applies middleware across public/private route groups.
• domain/user.go — Core domain entity defining the User struct with validation tags; foundational for authentication and profile management.
• internal/tokenutil/tokenutil.go — JWT token generation and parsing utilities; essential for login flow and token refresh logic.

Add a New Protected API Endpoint

1. Create domain DTOs in domain/ (e.g., domain/newfeature.go) with request/response structures (domain/newfeature.go)
2. Implement use case logic in usecase/newfeature_usecase.go calling repository methods (usecase/newfeature_usecase.go)
3. Add HTTP handler in api/controller/newfeature_controller.go binding Gin context to DTOs (api/controller/newfeature_controller.go)
4. Create route group in api/route/newfeature_route.go and register in api/route/route.go under protected routes (api/route/newfeature_route.go)
5. Wire use case and controller in bootstrap/app.go constructor function (bootstrap/app.go)

Add a New Data Entity with CRUD Operations

1. Define entity struct in domain/ (e.g., domain/product.go) with MongoDB BSON tags (domain/product.go)
2. Implement repository interface in repository/product_repository.go with Create/Read/Update/Delete methods (repository/product_repository.go)
3. Add use case orchestration in usecase/product_usecase.go calling repository methods with business logic (usecase/product_usecase.go)
4. Create controller handlers in api/controller/product_controller.go for each CRUD operation (api/controller/product_controller.go)
5. Register routes in api/route/product_route.go and bootstrap in bootstrap/app.go (api/route/product_route.go)

Implement User Authentication Requirement on Endpoint

1. Add route to protected group in api/route/route.go using .Use(middleware.JwtAuthMiddleware()) (api/route/route.go)
2. Access authenticated user ID from Gin context via c.GetString("userId") in controller (api/controller/task_controller.go)
3. Pass user ID to use case and repository for ownership-based data filtering (usecase/task_usecase.go)
4. Add MongoDB query filters in repository to ensure user isolation (e.g., bson.M{"user_id": userId}) (repository/task_repository.go)

• Go 1.19 — Statically typed, compiled language with fast execution, excellent concurrency primitives (goroutines), and strong standard library suitable for production backends.
• Gin Web Framework — Lightweight HTTP router with excellent performance, middleware support, and minimal dependencies compared to larger frameworks like Echo or chi.
• MongoDB — NoSQL document database flexible for rapid prototyping; well-suited for storing user and task documents without rigid schema constraints.
• JWT (golang-jwt/jwt) — Stateless token-based authentication avoiding server-side session storage; industry standard for mobile and SPA client authentication.
• Docker & docker-compose — Containerization for consistent dev/prod environments; docker-compose simplifies local MongoDB setup for development without manual installation.
• Testify Assertions — Provides readable assertion syntax and mocking capabilities for unit and integration testing; reduces boilerplate vs. standard library testing.

• Clean Architecture with strict layer separation (domain, use case, repository, controller)

  • Why: Enforces testability, loose coupling, and clear separation of concerns; enables swapping MongoDB for PostgreSQL without touching business logic.
  • Consequence: Increased file count and boilerplate (DTOs, repository interfaces, use cases); slower initial development vs. tightly-coupled monolithic approach.

• No ORM; direct MongoDB driver with manual query construction

  • Why: Minimal dependencies, full query control, and excellent performance; simpler codebase for learners.
  • Consequence: More verbose CRUD code than GORM/sqlc; requires manual index management and schema migration strategies; N+1 query patterns possible without discipline.

• JWT stored client-side (no refresh token rotation server-side)

  • Why: Simpler stateless architecture without session store; aligns with SPA/mobile client patterns
  • Consequence: undefined

.env file required: Must define MONGO_URI (MongoDB connection string) and JWT_SECRET before running; .env.example exists but is not auto-copied. MongoDB must be running: Whether local or in docker-compose, connection will fail silently at startup if missing. Viper config precedence: Environment variables override .env file; easy to miss when debugging config mismatches. JWT token format: Bearer token expected in Authorization header as 'Bearer <token>' (case-sensitive); Postman must include this exactly. No request validation on certain fields: Controllers accept input but domain models lack explicit validation tags; garbage in → garbage out.

• Clean Architecture / Hexagonal Architecture — This repo's entire structure (domain → repository → usecase → controller → router layers) is built on this pattern; understanding it explains why files are organized this way and how to add features.
• Dependency Inversion Principle (DIP) — Repository and Usecase are defined as interfaces in domain/, implemented elsewhere; this inversion enables testing with mocks and swapping implementations without changing business logic.
• JWT (JSON Web Token) Authentication — Core auth mechanism in api/middleware/jwt_auth_middleware.go and internal/tokenutil/tokenutil.go; tokens carry user claims without server-side session storage, enabling stateless API scaling.
• MongoDB ObjectID & BSON Marshaling — Domain models (domain/user.go, domain/task.go) use bson struct tags for MongoDB serialization; understanding BSON types (ObjectID) is essential when querying or inserting documents.
• Interface-based Testing & Mocking — domain/mocks/ contains auto-generated mocks (e.g., MockUserRepository) that implement domain interfaces; tests in api/controller/ use these mocks to isolate units without hitting real MongoDB.
• Viper Configuration Management — bootstrap/env.go uses Viper to load .env files and environment variables into a Config struct; enables 12-factor-app-compliant config without hardcoding secrets.
• Gin Middleware & Routing — api/route/ files chain middleware (JWT auth) and register HTTP handlers; Gin's Use() and middleware pattern is the glue between HTTP requests and business logic.

• golang-standards/project-layout — Defines the standard Go project directory structure (cmd/, internal/, domain/) that this repo follows; essential reference for Go layout conventions.
• codingwithmanny/golang-clean-architecture — Comparable clean architecture example in Go with similar layering; useful for comparing design decisions and seeing alternative implementations.
• urfave/cli — Popular Go CLI library; complements this backend template when you need command-line tooling alongside the REST API.
• vektra/mockery — The mock code generator used in domain/mocks/; understanding how mocks are generated is essential for extending tests in this repo.
• golang-jwt/jwt — The JWT library powering authentication (v4.4.3); refer here for token signing/validation details and best practices.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for api/middleware/jwt_auth_middleware.go

The JWT authentication middleware is critical to the security model but currently has no corresponding test file. This middleware validates tokens and controls access to protected routes. A new file api/middleware/jwt_auth_middleware_test.go should cover: valid token scenarios, expired tokens, malformed tokens, missing authorization headers, and invalid signatures. This is foundational for a secure backend.

• [ ] Create api/middleware/jwt_auth_middleware_test.go
• [ ] Mock JWT token generation using internal/tokenutil/tokenutil.go
• [ ] Test valid token extraction and validation
• [ ] Test error cases: expired tokens, invalid signatures, missing headers
• [ ] Test context population with user claims
• [ ] Achieve >80% code coverage for the middleware

Add integration tests for api/route/route.go and all route files

The route configuration orchestrates all endpoints (login_route.go, signup_route.go, task_route.go, profile_route.go, refresh_token_route.go), but there are no integration tests verifying routes are registered correctly and middleware chains work end-to-end. Create api/route/route_integration_test.go to test the complete request flow through actual route handlers.

• [ ] Create api/route/route_integration_test.go
• [ ] Setup test gin.Engine instance with all routes from route.go
• [ ] Test public routes (login, signup) are accessible without auth
• [ ] Test protected routes (task, profile) require valid JWT
• [ ] Test middleware chain execution order
• [ ] Verify 404 on undefined routes

Add missing repository and usecase unit tests following existing test patterns

Only 4 test files exist (profile_controller_test.go, user_repository_test.go, task_usecase_test.go, and mocks). The repository/task_repository.go has no corresponding test file, and usecases for login, profile, refresh_token, and signup are untested. Using the existing mock patterns in domain/mocks/, create: repository/task_repository_test.go and unit tests for usecase/{login,profile,refresh_token,signup}_usecase.go files.

• [ ] Create repository/task_repository_test.go mirroring user_repository_test.go patterns
• [ ] Test CRUD operations (Create, Find, Update, Delete) against mocked MongoDB
• [ ] Create usecase/login_usecase_test.go using LoginUsecase mock and UserRepository mock
• [ ] Create usecase/signup_usecase_test.go testing user creation and validation
• [ ] Create usecase/profile_usecase_test.go testing profile retrieval
• [ ] Create usecase/refresh_token_usecase_test.go testing token refresh logic
• [ ] Ensure all tests use existing mocks from domain/mocks/ and mongo/mocks/

• Add comprehensive test coverage to api/controller/login_controller.go and refresh_token_controller.go (only profile_controller_test.go exists); follow the pattern in profile_controller_test.go with mocks from domain/mocks/.
• Document the .env configuration schema in README.md with descriptions for each variable (MONGO_URI, JWT_SECRET, DB_NAME, etc.) and which are required vs. optional.
• Add input validation middleware or field tags (validate struct tags) to domain models (domain/user.go, domain/task.go, domain/login.go) to reject invalid email formats, empty passwords, and missing required fields.

• Critical · Hardcoded Secrets in .env.example — .env.example. The .env.example file contains placeholder values for sensitive tokens (ACCESS_TOKEN_SECRET, REFRESH_TOKEN_SECRET) that appear to be example/default values. If these defaults are used in production or if actual secrets are committed to version control, this exposes authentication credentials. Fix: Ensure .env file is in .gitignore (verify in .gitignore), never commit actual secrets, use a secrets management system (HashiCorp Vault, AWS Secrets Manager), and rotate tokens regularly. Provide only truly example values in .env.example.
• High · Weak JWT Token Expiry Configuration — .env.example, internal/tokenutil/tokenutil.go (likely). The JWT access token expiry is set to only 2 hours (ACCESS_TOKEN_EXPIRY_HOUR=2), which is reasonable, but the refresh token expiry is 168 hours (7 days). If a refresh token is compromised, an attacker has 7 days of access. Additionally, token rotation strategy and refresh token invalidation mechanism should be verified in the implementation. Fix: Implement shorter refresh token expiry (24-48 hours), implement refresh token rotation on each use, add token revocation/blacklist capability, and ensure secure storage of refresh tokens in httpOnly cookies.
• High · Missing MongoDB Authentication in Docker Setup — docker-compose.yaml, .env.example. The docker-compose.yaml shows DB_USER and DB_PASS environment variables are set from .env, but the .env.example shows these as empty strings (DB_USER= and DB_PASS=). This means MongoDB may run without authentication enabled, allowing unauthenticated access to the database. Fix: Ensure DB_USER and DB_PASS are always set with strong credentials in production. Update docker-compose.yaml to explicitly require these values. Implement MongoDB authentication and use encrypted connection strings. Never run MongoDB without authentication in any environment.
• High · MongoDB Port Exposed Without Network Isolation — docker-compose.yaml. The docker-compose.yaml exposes MongoDB port 27017 to the host machine (ports: - '$DB_PORT:$DB_PORT'). Combined with missing authentication, this allows direct network access to the database from the host and potentially from external networks if the host is exposed. Fix: Remove the ports mapping for MongoDB from docker-compose.yaml unless absolutely necessary. If access is required, restrict it to specific networks using Docker networks. In production, never expose database ports to public interfaces. Use internal Docker networking only.
• High · No HTTPS/TLS Configuration — Dockerfile, bootstrap/app.go (likely), docker-compose.yaml. The application appears to be configured to run over HTTP without TLS/SSL encryption. The Dockerfile and server configuration (SERVER_ADDRESS=:8080) show no evidence of HTTPS setup. JWT tokens will be transmitted in plaintext, vulnerable to interception. Fix: Implement HTTPS by configuring TLS certificates in the Gin application. Use Let's Encrypt for automatic certificate management. Configure proper certificate rotation. In docker-compose, add an SSL/TLS reverse proxy (nginx) in front of the application. Enforce HSTS headers.
• High · Missing Security Headers Configuration — api/middleware/jwt_auth_middleware.go, api/route/route.go. No evidence of security headers (HSTS, X-Content-Type-Options, X-Frame-Options, Content-Security-Policy, X-XSS-Protection) in the route or middleware configuration. This leaves the application vulnerable to various attacks including MIME-type sniffing, clickjacking, and XSS. Fix: Implement security middleware to add standard security headers. Create a custom middleware that sets: HSTS, X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Content-Security-Policy, X-XSS-Protection: 1; mode=block. Use Gin middleware hooks to apply globally.
• Medium · Outdated Go Version — go.mod. The project uses Go 1.19 (go 1.19 in go.mod), which is no longer the latest stable version. Newer versions include security patches and improvements. Using outdated versions increases exposure to known vulnerabilities. Fix: Upgrade to the latest stable Go version (1.21+). Update Dockerfile

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.