ntorga/clean-ddd-full-stack-go-poc

This system is a full-stack Go application for managing contacts, featuring a RESTful API and an interactive web interface. It provides complete CRUD operations for contact records, supporting both programmatic access via HTTP endpoints and user interaction through a dynamic UI with dark mode and real-time updates. The architecture separates domain logic, data persistence, and presentation layers, enabling consistent data handling across CLI, API, and web client interfaces.

The CLI now supports creating, reading, updating, and deleting contacts via the \contact\ command group. Users can use \contact create\ with \--name\, \--nickname\, and \--phone\ flags; \contact get\ to retrieve contacts; \contact update\ to modify existing contacts (passing only the fields to be updated); and \contact delete\ to remove contacts by ID.

src/presentation/cli/controller · high confidence

A new Contact domain entity has been introduced, containing fields for ID, name, nickname, and phone number. The entity includes a constructor and a method to return a list of three initial contact records (Christopher Pike, Una Chin-Riley, and Spock) for testing or seeding purposes. Additionally, a JsonSerialize method has been added to the Contact struct to handle JSON marshaling.

src/domain/entity · medium confidence

The application now includes new UI components for the presentation layer. Users can toggle dark mode with their preference persisted via Alpine.js. A loading overlay is provided to indicate active requests, and a toast notification system displays success or error messages from server responses.

src/presentation/ui/component · high confidence

A new \Render\ function is introduced in the \ui/helper\ package to simplify returning HTML responses. It sets the content type to text/html, writes the provided HTTP status code, and renders the main layout with the given page content.

src/presentation/ui/helper · high confidence

The contact page now renders a full user interface for managing contacts, including a data table that lists all contacts and supports deletion via Hotwire (HTMX) requests. A create form allows users to add new contacts, while an Alpine.js-powered modal provides an inline update interface. The view also includes a loading indicator overlay to show during asynchronous form submissions.

src/presentation/ui/page · high confidence

A new ContactPresenter has been introduced in the presentation layer to handle the contact index page. This component retrieves contact entities via the contact service and renders the corresponding UI page, effectively separating the presentation logic for this specific feature.

src/presentation/ui/presenter · high confidence

A new utility file (src/dev/util.go) was added to the development tools, providing a helper function to initialize and return a persistent database service instance, simplifying access to database connections during development.

src/dev · medium confidence

The domain layer now includes new value objects for managing contact identifiers, person names, nicknames, and phone numbers, each with strict validation rules. ContactId is a typed uint64 wrapper. PersonName, Nickname, and PhoneNumber are string-based value objects validated by regular expressions: PersonName allows letters, apostrophes, spaces, and hyphens; Nickname permits letters, digits, underscores, and hyphens; and PhoneNumber accepts digits with optional separators. All value objects include unit tests verifying valid and invalid inputs. Additionally, helper functions are introduced to convert interface types to strings and unsigned integers, supporting the new value objects.

src/domain/valueObject · high confidence

Introduced a new ContactService in the presentation layer that implements the full CRUD operations (Read, Create, Update, Delete) for contacts. The service validates input parameters using a new RequiredParamsInspector helper and maps domain use cases to service outputs, providing a structured response format with status codes like success, created, user error, and infrastructure error.

src/presentation/service · high confidence

The application now supports full contact management through new domain use cases: CreateContact, ReadContacts, UpdateContact, and DeleteContact. Each use case handles the specific operation (create, read, update, delete) by interacting with the respective repository interfaces. The implementation includes error handling that logs infrastructure errors and returns generic error messages to the caller, ensuring that internal implementation details are not exposed.

src/domain/useCase · high confidence

The API controller now exposes full CRUD operations for contacts. Users can now read a list of contacts, create new contacts, update existing ones, and delete them via the /v1/contact/ routes. Each endpoint delegates to the corresponding service layer method, with request bodies parsed and responses wrapped for consistency.

src/presentation/api/controller · high confidence

The project now includes configuration and scripts to streamline development and building. A \.air.toml\ file configures the Air hot-reload server, while a \Makefile\ provides targets for development (\make dev\), building (\make build\), and browser refresh. A \build.sh\ script automates cross-platform binary compilation and zipping. Additionally, a \tailwind.config.js\ file is added to support the Tailwind CSS tooling, and \.gitignore\ is updated to exclude build artifacts and logs.

(repo-wide) · high confidence

Introduced four new middleware functions in the API presentation layer: a panic handler that logs stack traces and returns appropriate HTTP status codes (500 for general errors, 400 for domain-layer panics) while protecting sensitive data for untrusted clients; a header setter that enforces cache control, CORS, and content-type defaults while skipping non-API paths; a trailing slash redirector that normalizes API routes but excludes Swagger endpoints; and a database service injector that attaches the persistent database service to the request context.

src/presentation/api/middleware · high confidence

Introduced a new PersistentDatabaseService that manages a SQLite database (stored in the system temp directory) using GORM. This includes a new Contact model with fields for name, nickname, and phone number, along with migration and seeding logic to initialize the database schema and populate it with default entries.

src/infra/db · high confidence

Added Go implementations for contact data access: ContactCmdRepo now supports Create, Update, and Delete operations, while ContactQueryRepo provides Read and ReadById methods to retrieve contact entities from the database. Corresponding unit tests validate the new repository behaviors.

src/infra · high confidence

The application now provides a command-line interface (CLI) for managing contacts and performing system operations. Users can create, read, update, and delete contacts via the CLI, alongside system commands such as checking the application version and starting the HTTP server. The CLI entry point initializes the database service and registers all routes, including a panic handler for error logging.

src/presentation/cli · high confidence

The application now exposes a new /api/v1/contact endpoint supporting full CRUD operations (Read, Create, Update, Delete) for contacts, alongside a Swagger UI at /api/swagger for interactive API documentation. This change introduces the API presentation layer, wiring the database service to the controllers and establishing the HTTP server's API routes.

src/presentation/api · high confidence

Added new repository interfaces to the domain layer: ContactCmdRepo defines methods for Create, Update, and Delete operations, while ContactQueryRepo defines Read and ReadById methods, establishing the contract for contact data persistence and retrieval.

src/domain/repository · high confidence

Added two new helper functions to the API presentation layer: ReadRequestBody, which parses HTTP request bodies (JSON, form data, or multipart) into a standardized map, and ResponseWrapper, which maps service-layer status codes to appropriate HTTP response codes and formats the output. These utilities provide a consistent way to handle incoming requests and structure outgoing API responses.

src/presentation/api/helper · high confidence

The CLI now formats JSON responses with syntax highlighting when running in an interactive terminal, improving readability. For non-interactive sessions (e.g., pipes, scripts), it outputs standard, unformatted JSON to ensure compatibility with automated tools. Error conditions now trigger an exit code of 1, while successful responses exit with code 0.

src/presentation/cli/helper · high confidence

The HTTP server now displays a custom ASCII art banner on startup and initializes the UI layer alongside the API layer. The server banner is now explicitly hidden from the default Echo framework output, replaced by a custom graphic that includes the version 'v0.0.1'. Additionally, the \UiInit\ function is called to set up the UI routes, indicating a new capability to serve UI-related endpoints or assets.

src/presentation · high confidence

Added src/presentation/ui/router.go and src/presentation/ui/ui.go to centralize route registration. The new UiInit function sets up the Echo router group and registers the contact page at the root path (/) instead of /contact/, ensuring the application's entry point is correctly mapped.

src/presentation/ui · medium confidence

The layout structure has been refactored by separating the header and main layout into distinct template files (header.templ and main.templ). The header now includes a dark mode toggle, and the main layout wraps the page content with appropriate styling and utility components like loading overlays and toasts.

src/presentation/ui/layout · medium confidence

The Go module path was changed from 'github.com/ntorga/clean-ddd-go-taghs-poc-contacts' to 'github.com/ntorga/clean-ddd-full-stack-go-poc'. The project's dependencies were updated to include 'github.com/a-h/templ', 'github.com/alecthomas/chroma', 'github.com/glebarez/sqlite', 'github.com/spf13/cobra', 'golang.org/x/term', and 'gorm.io/gorm', along with their respective indirect 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 54 → 50 (-3.8)
• Rubric changed (rubric-2026.08.19 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 98 → 98 (+0.8)
• Architecture 100 → 76 (-24.5)
• Maturity 62 → 62 (-0.0)
• Readiness 24 → 38 (+13.5)
• Security 91 → 85 (-6.7)
• Domain Modelling 100 → 100 (+0.0)
• Accessibility 46 (new)

• Coverage not included — suite not readable by the collector
• Critical CVE: [GHSA redacted] (go.mod)
• Dependency hygiene not measured — dependency manifest found but not parsed for hygiene
• Duplicated block (12 lines × 2) (src/presentation/api/middleware/panicHandler.go)
• Duplicated block (9 lines × 2) (src/presentation/api/middleware/panicHandler.go)
• High CVE: [GHSA redacted] (go.mod)
• Medium CVE: [GHSA redacted] (go.mod)
• Medium CVE: GO-2025-3503 (go.mod)
• Medium CVE: GO-2026-5024 (go.mod)
• Medium CVE: GO-2026-5970 (go.mod)
• No exposed public API
• Test reliability not included
• single-maintainer — knowledge-concentration (bus factor) risk

• Critical CVE: [GHSA redacted] (go.mod)
• Documentation: no installation or build instructions (README.md)
• Documentation: no usage examples (README.md)
• Duplicated block (14 lines × 2) (src/presentation/api/middleware/panicHandler.go)
• Duplicated block (7 lines × 2) (src/presentation/api/middleware/panicHandler.go)
• Duplicated block (8 lines × 2) (src/presentation/api/middleware/panicHandler.go)
• High CVE: [GHSA redacted] (go.mod)
• High CVE: [GHSA redacted] (go.mod)
• Hotspot: src/presentation/api/helper/readRequestBody.go (src/presentation/api/helper/readRequestBody.go)
• Medium CVE: [GHSA redacted] (go.mod)
• Medium CVE: GO-2025-3503 (go.mod)
• Medium CVE: GO-2026-5024 (go.mod)
• Medium CVE: GO-2026-5970 (go.mod)
• Medium: security finding (details withheld)
• Outdated: github.com/a-h/templ
• Outdated: github.com/labstack/echo/v4
• Outdated: github.com/spf13/cobra
• Outdated: github.com/swaggo/echo-swagger
• Outdated: github.com/swaggo/swag
• Outdated: golang.org/x/term
• …and 1 more

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

ntorga/clean-ddd-full-stack-go-poc 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.