naeemaei/golang-clean-web-api

This system is a Go-based web API service that manages resources such as cars, properties, and users through a clean, layered architecture. It provides comprehensive CRUD endpoints protected by JWT-based authentication and role-based authorization, supported by structured logging, Prometheus metrics, and rate limiting. The application is containerized with Docker, integrating with external services like Postgres, Redis, and the ELK stack for logging and monitoring.

18 changes.

The project established the core application infrastructure, including environment-specific configuration, database connections, and structured logging. A comprehensive v1 API was launched with full CRUD endpoints for various entities, supported by robust error handling and DTOs. Additionally, the codebase was modernized with Go 1.22, and extensive observability features were added, including Prometheus metrics, Grafana dashboards, and an ELK stack for logging.

4 changes.

The codebase was restructured into a clean architecture, introducing domain models, repository interfaces, and generic CRUD handlers. This period also established a comprehensive API middleware suite for authentication, logging, and rate limiting, alongside new endpoints for user authentication and testing.

The Grafana instance is now pre-configured with a Prometheus data source and four provisioned dashboards: 'Docker Prometheus Monitoring', 'Golang Web API Dashboard', 'Node Exporter Full with Node Name', and 'Server Status'. These dashboards provide out-of-the-box visibility into host metrics, Go application performance, and server status, alongside a new configuration file for Grafana's admin credentials and user sign-up settings.

docker/grafana · high confidence

The docker/elk directory now includes full Docker Compose support for the ELK stack. This adds containerized configurations for Elasticsearch, Filebeat, and Kibana, each with their own Dockerfiles, configuration files, and .dockerignore files. A dedicated setup service initializes Elasticsearch users and roles (specifically for Filebeat) upon startup, ensuring the logging pipeline is ready for use.

docker/elk · high confidence

The application now exposes Prometheus-compatible metrics for observability. A new counter tracks the total number of database calls, categorized by type, operation, and status. Additionally, a histogram measures HTTP response durations, with specific buckets defined for latency analysis, capturing path, method, and status code labels.

src/pkg/metrics · high confidence

The common package now includes new utility functions to support application logic. A generic TypeConverter is available for JSON-based type conversion. String handling includes a ToSnakeCase converter and helpers to validate passwords (checking length, character types, and digits) and generate secure random passwords and OTPs. Additionally, a validator for Iranian mobile numbers has been added. These changes replace the previous empty placeholder in the common directory.

src/common · high confidence

The application now loads settings from environment-specific YAML files (config-development.yml, config-docker.yml, config-production.yml) via a new Go-based config loader. This introduces structured configuration for the server (internal/external ports, run mode), database connections (Postgres, Redis), password validation rules, OTP parameters, and JWT token expiration durations. The Go code in src/config/config.go reads these files and allows the external port to be overridden by the PORT environment variable, providing a consistent way to manage environment-specific settings across development, Docker, and production deployments.

src/config · high confidence

The API router now exposes new endpoints for user authentication, including login by username and mobile number, registration, OTP sending, and a refresh-token endpoint. Additionally, a test router is added with various user and binder test endpoints, and constants for JWT claims and roles are defined.

src/api/router, src/constant · medium confidence

The codebase is restructured into a clean architecture with new domain models (e.g., CarModel, Property, User), repository interfaces and Postgres implementations, and validation helpers (e.g., IranianMobileNumberValidator, PasswordValidator). A generic base repository and dynamic query builder are added to support filtering, sorting, and pagination, while migration scripts seed initial data for countries, car types, and default users.

(repo-wide) · high confidence

The API server now exposes a fully structured v1 endpoint for managing resources including countries, cities, files, companies, colors, years, properties, and a complete set of Car-related models (types, gearboxes, models, colors, years, price histories, images, properties, and comments). Access to these endpoints is protected by authentication and authorization middleware, with admin or specific role requirements enforced. The release also introduces structured logging, Prometheus metrics for HTTP duration and database calls, Swagger documentation, and a health check endpoint.

src/api · medium confidence

The src/api/middleware directory now includes a comprehensive set of new middleware components. Authentication and authorization middleware validate JWT tokens and enforce role-based access control. CORS headers are configured for cross-origin requests. A custom recovery handler standardizes 500 error responses. Rate limiting is applied via a generic request limiter and a specific OTP (One-Time Password) IP-based limiter. Additionally, structured logging captures request details, Prometheus metrics track HTTP duration, and a test middleware validates an API key header.

src/api/middleware · high confidence

The application now supports structured logging via two configurable backends: Zap and Zerolog. The new \src/pkg/logging\ package introduces a \Logger\ interface and a \NewLogger\ factory that selects the implementation based on the \cfg.Logger.Logger\ configuration value. The \zap\_logger.go\ file implements logging using the \go.uber.org/zap\ library with JSON encoding and file rotation, while \zero\_logger.go\ implements it using \github.com/rs/zerolog\. Both implementations support categorized and subcategorized log levels (Debug, Info, Warn, Error, Fatal) with extra context fields, allowing users to switch logging engines via configuration.

src/pkg/logging · high confidence

The API data transfer objects were expanded to support new and existing entities. New DTOs were introduced for car-related models (car type, gearbox, model, color, year, price history, images, properties, and comments), as well as for city, color, company, country, file, property, user authentication, and Persian year models. These changes enable the API to handle requests and responses for these resources.

src/api/dto · high confidence

The main entry point for the application has been updated to initialize essential services at startup. This includes setting up the Redis cache, connecting to the Postgres database, running database migrations, and starting the API server. The application now explicitly manages the lifecycle of these dependencies, ensuring they are properly initialized and closed.

src/cmd · high confidence

The application now uses a centralized error handling package that defines specific error codes for tokens, OTPs, users, and database operations, and wraps them in a structured ServiceError type that exposes both user-facing and technical messages.

_src/pkg/service\errors · medium confidence

A new IP rate limiter implementation has been added to the limiter package. This introduces a mechanism to track and limit requests per IP address, specifically to enforce rate limits on the send-OTP endpoint to prevent abuse.

src/pkg/limiter · medium confidence

The API now returns a consistent JSON response structure (BaseHttpResponse) that includes a result code, success flag, and optional validation or error details. A new ResultCode enum defines specific error codes for validation, authentication, and other scenarios. Additionally, a status code mapping translates internal service errors (like 'RecordNotFound' or 'OtpExists') into appropriate HTTP status codes (e.g., 404, 409), ensuring clients receive standard HTTP status codes for common error conditions.

src/api/helper · high confidence

The Redis configuration file (redis.conf) now includes a password requirement (requirepass), meaning the Redis instance will require authentication via a password for access.

docker/redis · high confidence

The API layer has been restructured into a clean architecture with a generic base handler for standard CRUD operations. This new pattern is applied to create handlers for CarModel, CarModelColor, CarModelComment, CarModelImage, CarModelPriceHistory, CarModelProperty, CarModelYear, CarType, City, Color, Company, and Country, each exposing Create, Update, Delete, GetById, and GetByFilter endpoints.

src/api/handler, src/usecase · high confidence

The empty placeholder files (.gitkeep) in the src/data/cache, src/data/db, and src/data/models directories have been removed. This cleanup eliminates unused directory structures that previously served only as placeholders for future data layer components.

src/constants, src/services, src/data · medium confidence

The empty .gitkeep files in the src/api/forms and src/scripts directories have been removed, cleaning up the project structure.

src/api/forms, src/scripts · high confidence

The empty .gitkeep placeholder files in the src/api/handlers and src/api/routers directories have been removed. This cleanup reflects the addition of actual handler and router implementations, replacing the previous empty directory structures.

src/api/handlers, src/api/routers · high confidence

The empty .gitkeep file in the src/api/validations directory has been removed. This cleanup eliminates an unused placeholder file, indicating the directory is now actively used for validation logic rather than being a reserved but empty directory.

src/api/middlewares, src/api/validations · high confidence

The project has been upgraded to Go 1.22. Additionally, the \go.mod\ and \go.sum\ files have been updated to include a new set of dependencies, including \gin\, \zap\, \redis\, \prometheus\, \jwt\, \uuid\, \viper\, and \swagger\ libraries, along with their transitive dependencies.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 40 → 42 (+2.0)
• Rubric changed (rubric-2026.08.19 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 97 → 99 (+1.3)
• Architecture 100 → 74 (-25.9)
• Maturity 57 → 57 (-0.3)
• Readiness 22 → 25 (+3.6)
• Security 78 → 64 (-13.3)
• Domain Modelling 37 → 46 (+9.6)

• Critical CVE: [GHSA redacted] (src/go.mod)
• Critical CVE: [GHSA redacted] (src/go.mod)
• Dependency hygiene not measured — dependency manifest found but not parsed for hygiene
• Duplicated block (10 lines × 2) (src/api/handler/property_simple.go)
• Duplicated block (10 lines × 3) (src/api/handler/user.go)
• Duplicated block (11 lines × 2) (src/api/handler/base_generic_crud.go)
• Duplicated block (11 lines × 2) (src/usecase/user_usecase.go)
• Duplicated block (13 lines × 2) (src/api/handler/base_generic_crud.go)
• Duplicated block (7 lines × 2) (src/infra/persistence/migration/1_Init.go)
• Duplicated block (8 lines × 2) (src/api/handler/file.go)
• Duplicated block (8 lines × 2) (src/usecase/token_usecase.go)
• High CVE: [GHSA redacted] (src/go.mod)
• High: security finding (details withheld)
• High: security finding (details withheld)
• Medium CVE: [GHSA redacted] (src/go.mod)
• Medium CVE: [GHSA redacted] (src/go.mod)
• Medium CVE: GO-2025-3503 (src/go.mod)
• Medium CVE: GO-2026-5024 (src/go.mod)
• Medium CVE: GO-2026-5970 (src/go.mod)
• Medium IaC: CKV_DOCKER_2 (docker/elk/setup/Dockerfile)
• …and 6 more

• Critical CVE: [GHSA redacted] (src/go.mod)
• Critical CVE: [GHSA redacted] (src/go.mod)
• Documentation: no usage examples (README.md)
• Duplicated block (10 lines × 2) (src/api/handler/base_generic_crud.go)
• Duplicated block (11 lines × 2) (src/api/handler/base_generic_crud.go)
• Duplicated block (11 lines × 2) (src/api/handler/property_simple.go)
• Duplicated block (11 lines × 3) (src/infra/persistence/migration/1_Init.go)
• Duplicated block (15–17 lines × 2) (src/usecase/user_usecase.go)
• Duplicated block (16–17 lines × 3) (src/api/handler/user.go)
• Duplicated block (5 lines × 14) (src/usecase/carModelColor_usecase.go)
• Duplicated block (5 lines × 2) (src/usecase/carType_usecase.go)
• Duplicated block (6 lines × 5) (src/infra/persistence/migration/1_Init.go)
• Duplicated block (7 lines × 2) (src/infra/persistence/migration/1_Init.go)
• Duplicated block (8–10 lines × 2) (src/api/handler/file.go)
• Duplicated block (9 lines × 2) (src/infra/persistence/repository/postgres_user_repository.go)
• Duplicated block (9 lines × 2) (src/usecase/token_usecase.go)
• High CVE: [GHSA redacted] (src/go.mod)
• High IaC: WD-COMPOSE-0002 (docker/docker-compose.yml)
• High IaC: WD-COMPOSE-0002 (docker/docker-compose.yml)
• High IaC: WD-COMPOSE-0002 (docker/docker-compose.yml)
• …and 42 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

naeemaei/golang-clean-web-api was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.