[](https://github.com/bastean/codexgo)

Example CRUD project applying Hexagonal Architecture, Domain-Driven Design (DDD), Event-Driven Architecture (EDA), Command Query Responsibility Segregation (CQRS), Behavior-Driven Development (BDD), Continuous Integration (CI), and more... in Go.

Showcase

CLI

Run (Demo)

go run github.com/bastean/codexgo/v4/cmd/codexgo@latest -demo

[!NOTE]

• Demo version does not require any configuration, because the required ENV values are already preset.
• Here we can find the ENV preset values that are used in the Demo.
• In-Memory implementation will be used for EventBus, CommandBus, QueryBus and Database (BadgerDB).
• Links to confirm and recover the account are sent through the Terminal with the following messages:
• "Hi \<username>, please confirm your account through this link: \<link>".
• "Hi \<username>, please reset your password through this link: \<link>".

Installation

go install github.com/bastean/codexgo/v4/cmd/codexgo@latest

codexgo -h

              _________               ________________
_____________ ______  /_____ ____  __ __  ____/__  __ \
_  ___/_  __ \_  __  / _  _ \__  |/_/ _  / __  _  / / /
/ /__  / /_/ // /_/ /  /  __/__>  <   / /_/ /  / /_/ /
\___/  \____/ \__,_/   \___/ /_/|_|   \____/   \____/  v4.17.4

Example CRUD project applying Hexagonal Architecture, DDD, EDA, CQRS, BDD, CI, and more... in Go.

Usage: codexgo [flags]

  -demo
        Use preset ENV values
  -env string
        Path to custom ENV file
  -v    Print version

Usage

[!NOTE]

• We can use the .env.demo.cli file or we can create our own .env file where we define our own values.
• In the .env.example.cli file, we can see the values that can be used.
  • If CODEXGO_SMTP_* is omitted, the links to confirm and recover the account are sent through the Terminal with the following messages:
  • "Hi \<username>, please confirm your account through this link: \<link>".
  • "Hi \<username>, please reset your password through this link: \<link>".
  • We can define our own SMTP configuration by simply modifying the CODEXGO_SMTP_* variables, then we will be able to receive the links by mail.
  • If CODEXGO_BROKER_* is omitted, an in-memory EventBus will be used.
  • In-Memory implementation will be used for CommandBus and QueryBus.
  • If CODEXGO_DATABASE_* is omitted, a BadgerDB in-memory database will be used.
  • We can use a file as a database instead of memory by defining the file name in the CODEXGO_DATABASE_BADGERDB_DSN variable.

codexgo -env path/to/.env

Docker

Run (Demo)

[!NOTE]

• System Requirements
• In the Demo version (.env.demo):
• RabbitMQ implementation will be used for the EventBus.
  • URL: http://localhost:15672
  • User/Password: codexgo-demo
• In-Memory implementation will be used for CommandBus and QueryBus.
• MongoDB implementation will be used as Database.
  • Compass: mongodb://codexgo-demo:codexgo-demo@localhost:27017
• Mailpit will be used as SMTP to receive emails with the links to confirm and recover the account.
  • URL: http://localhost:8025
• codexGO Server.
  • URL: http://localhost:8080

task demo

Features

Project Layout

• Based on Standard Go Project Layout.

Git

• Hooks managed by husky:
• Pre-Push:
  • Scanning Repository for secrets using TruffleHog CLI and Trivy
• Pre-Commit: lint-staged
  • Scanning files for secrets using TruffleHog CLI
  • Formatting files using GolangCI-Lint and Prettier.
• Commit-Msg: commitlint
  • Check Conventional Commits rules
• Commit message helper using czg.
• Interactive prompt that allows you to write commits following the Conventional Commits rules: bash task commit

Scanners

• TruffleHog CLI: Secrets.
• Trivy: Secrets, Vulnerabilities and Misconfigurations.
• OSV-Scanner: Vulnerabilities.

Linters/Formatters

• *.go: GolangCI-Lint.
• *.templ: templ fmt.
• *.feature (Gherkin): Cucumber extension.
• *.*: Prettier cli/extension.

Debuggers

• *.go: deadcode.

Tests

• Random data generator: Gofakeit.
• Unit/Integration: Testify.
• Acceptance: Testify, Godog (Cucumber) and Playwright.

Releases

• Automatically managed by Release It!:
• Before/After Hooks for:
  • Linting
  • Testing
• Bump version based on Conventional Commits and SemVer:
  • CHANGELOG generator
  • Commits and Tags generator
  • GitHub Releases

GitHub

• Actions for:
• Setup Languages and Dependencies (setup)
• Workflows running:
• Automatically (Triggered by Push or Pull requests) (ci):
  • Secrets
  • Vulnerabilities
  • Misconfigurations
  • Linting
  • Testing
• Manually (Using the Actions tab on GitHub):
  • Upgrade Dependencies (upgrade)
  • Automate Release (release)
• Issue Templates (Defaults).

Devcontainer

• Multiple Features already pre-configured:
• Go
• Task
• Docker in Docker
• Light-weight Desktop (Fluxbox)
• SSH
• Extensions and their respective settings to work with:
• Go
• Task
• Docker
• MongoDB
• Postman
• templ
• Cucumber
  • Gherkin
• YAML
• TOML
• Prettier
• Better Comments
• Comment Divider
• Todo Tree
• cSpell
• Fomantic Snippets

Docker

• Dockerfile
• Multi-stage builds:
  • Development
  • Testing
  • Build
  • Production
• Compose
• Switched by ENVs and Profiles.

Broker

• Message Routing Key based on AsyncAPI Topic Definition.

Server

• Progressive Web App (PWA)
• Manifest

Security

• Server log files.
• Requests Rate Limiting.
• Data authentication via JWT managed by Session Cookies.
• Captcha implementation in forms.
• Form validation at the client using Fomantic - Form Validation.
• On the server, the validations are performed using the Value Objects defined in the Context.
• Account confirmation and recovery via Mail or Terminal.
• Limited to a certain number of attempts in a given time interval.
• Password hashing using Bcrypt.

Tools

• cDeps
• Copies the files required by the browser dependencies from the node_modules folder and places them inside the static folder on the server.
• syncENV
• Synchronize all .env* files in the directory using an .env model.

Scripts

• run
• Display the logs and redirect them to a file whose name depends on the time at which the service was run.
• Used in Production Image.

Domain > (Infrastructure | Application) > Presentation

Bounded Context (App/Business/Department) > Modules (Troubleshooting) > Layers (Domain, Infrastructure & Application)

• Domain (Logic Core)
• Value Objects (Entities)
  • Mother Creators
  • Unit Tests
• Messages
  • Mother Creators
• Aggregates (Sets of Entities)
  • Aggregate Root (Core Set)
  • Mother Creators
• Role Interfaces (Ports)
  • Repository
  • Broker
• Model Interfaces
  • Use Cases
  • Handlers/Consumers
• Services (Abstract Logic)
• Errors (Management)
• Infrastructure (Port Adapters)
• Persistence
  • Repository Mocks
  • Implementations (Adapters)
  • Integration Tests
• Communication
  • Broker Mocks
  • Implementations (Adapters)
  • Integration Tests
• Application (Orchestration of Domain Logic)
• Use Cases
  • Implementations
• Commands
  • Mother Creators
• Queries/Responses
  • Mother Creators
• Handlers/Consumers
  • Implementations
  • Unit Tests

Services > App > (Presentation)

• Presentation (Consumers of Bounded Context Modules)
• Services (Mapping)
  • Centralize Imports
  • Initializations
• Server
  • Templates
  • Handlers
  • API
  • Views
  • Routes
  • API /v*
  • Views
  • Features (Gherkin)
  • Acceptance Tests
    • API
    • Views

Workflow

Idea

The system allows users to register a new account, log in and update their data or permanently delete their account, as well as verify and reset their account through a link sent to their email.

Functionality

It is a monolith where CRUD operations can be performed from different presentations to the same database, this allows us to manage users from the different presentations available, in addition to having a messaging system that allows to communicate the events occurred, thus avoiding a coupling to the source of the same.

Folders

1. pkg/context/(modules)

2. It is the logical core that contains all the necessary functionalities that are agnostic of any presentation.

3. internal/pkg/service

4. It is responsible for initializing all context functionalities so that they are ready for use, as well as for "mapping" certain values to centralize all imports required for presentations in a single place.

5. internal/app/(presentations)

6. These applications will be used as presentations in order to serve the functionalities to an end user.

Idiomatic

[!TIP] VSCode Snippets available (We can see them in IntelliSense (Ctrl+Space) or simply by typing go-).

• Domain
• errors.New[...](), errors.BubbleUp() & errors.Panic()
  • Only in the Domain layer and in the *_test.go files can we throw errors.Panic().
• Infrastructure
• New*(), Open() & Close()
  • session
• errors.New[...]() & errors.BubbleUp()
• Application
• Run(), Handle() & On()
• errors.New[...]() & errors.BubbleUp()
• Presentation
• Modules
  • Start() & Stop()
  • errors.BubbleUp()
• Services / Apps
  • Init(), Up() & Down()
  • log.[Wrap]()
  • errors.New[...]() & `errors.BubbleU