codexgo

README

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

Usage

Docker (Demo)

[!NOTE]

• System Requirements
• In the Demo version, the link to confirm the account is sent through the Terminal.
  • "Hi <username>, please confirm your account through this link: <link>"
• We can define our own SMTP configuration in the .env.demo file by simply modifying the CODEXGO_SMTP_* variables, then we will be able to receive the links by mail.

make demo

Features

Project Layout

• Based on Standard Go Project Layout.

Git

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

    make commit
    

Linting/Formatting Tools

• Go: staticcheck and gofmt.
• templ: templ fmt.
• Gherkin: Cucumber extension.
• Others: Prettier cli/extension.

Scanners

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

Testing Packages

• 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
• Workflows running:
  • Automatically (Triggered by Push or Pull requests):
    • Secrets Scanning (TruffleHog Action)
    • Linting
    • Testing
  • Manually (Using the Actions tab on GitHub):
    • Upgrade Dependencies
    • Automate Release
• Issue Templates (Defaults).

Devcontainer

• Multiple Features already pre-configured:
  • Go
  • Node
  • Docker in Docker
• Extensions and their respective settings to work with:
  • Go
  • templ
  • Cucumber
    • Gherkin
  • Prettier
  • Better Comments
  • Todo Tree
  • cSpell

Docker

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

Message Broker

• Routing Key based on AsyncAPI Topic Definition.

Security

• Form validation at the client using Fomantic - Form Validation.
  • On the server, the validations are performed using the Value Objects defined in the Context.
• Data authentication via JWT managed by Session Cookies.
• Account confirmation via Mail or Terminal.
• Password hashing using Bcrypt.
• Requests Rate Limiting.
• Server log files.

Scripts

• syncenv
  • Synchronize all .env* files in the directory using an .env model.
• copydeps
  • Copies the files required by the browser dependencies from the node_modules folder and places them inside the static folder on the server.
• upgrade
  • Perform the following steps to upgrade the project:
    • Upgrade Go, Node and Tools.
    • Linting and Testing.
    • Commit upgrades.
• 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.

Basic Workflow (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 (Event/Command)
    • 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

App > Server > (Presentation)

• Presentation (Consumers of Bounded Context Modules)
  • Services (Mapping)
    • Centralize Imports
  • Server
    • Templates
    • Handlers
    • Routes
    • Features (Gherkin)
      • Acceptance Tests

Idiomatic

• Domain
  • errors.New*(), errors.BubbleUp() & errors.Panic()
    • Only in the "Domain" can we throw a panic().
• Infrastructure
  • Open() & Close()
    • session
  • errors.New*() & errors.BubbleUp()
• Application
  • Run(), Handle() & On()
  • errors.New*() & errors.BubbleUp()
• Modules
  • Start() & Stop()
  • errors.BubbleUp()
• Services / Apps
  • Up() & Down()
    • log.[Wrap]()
  • errors.New*() & errors.BubbleUp()
• Main
  • log.Fatal() & log.[Wrap]()
    • Only main() can use log.Fatal().
• Logs
  • [embed]
    • We use [] to "embed" external values such as error messages, fields, etc... inside our messages.

First Steps

Clone

HTTPS

git clone https://github.com/bastean/codexgo.git && cd codexgo

SSH

git clone git@github.com:bastean/codexgo.git && cd codexgo

Initialize

Dev Container (recommended)

1. System Requirements

   • Docker

     • Dev Containers

2. Start VS Code

   code .
   

3. Open Command Palette

   • Ctrl+Shift+P

4. Run

   Dev Containers: Reopen in Container
   

Locally

1. System Requirements

   • Go
   • Node
   • Make
   • Docker

2. Run

   make init
   

ZIP

[!NOTE]

• System Requirements
• We need to change <user> and <repository> with our own values.

curl -sSfLO https://github.com/bastean/codexgo/archive/refs/heads/main.zip \
&& unzip main.zip \
&& mv codexgo-main <repository> \
&& rm main.zip \
&& cd <repository> \
&& make genesis \
&& git commit -m "chore: add codexgo" \
&& git branch -M main \
&& git remote add github https://github.com/<user>/<repository>.git \
&& git push -u github main \
&& git status

GitHub Repository

[!IMPORTANT] These settings are necessary to be able to execute the Actions Workflows.

Settings tab

Actions

• General

  • Workflow permissions

    • Read and write permissions

Secrets and variables

• Actions

  • New repository secret

    • BOT_GPG_PRIVATE_KEY

      gpg --armor --export-secret-key [Pub_Key_ID (*-BOT)]
      

    • BOT_GPG_PASSPHRASE

Run

ENVs

[!IMPORTANT] Before running it, we must initialize the following environment variable files:

• .env.example
  • We will have to create a .env.(dev|test|prod) for each runtime environment.
  • In the .env.example.demo file, we can see the values that can be used.

In case we only want to run the Integration or Acceptance tests, in addition to having the .env.test file, we must have the following files created:

• .env.example.test.integration
  • Rename the file to .env.test.integration.
• .env.example.test.acceptance
  • Rename the file to .env.test.acceptance.

Development

make compose-dev

Tests

Unit

make test-unit

Integration

make compose-test-integration

Acceptance

make compose-test-acceptance

Unit/Integration/Acceptance

make compose-tests

Production

make compose-prod

Tech Stack

Base

• Go
• Gin
• templ
  • Fomantic-UI
• RabbitMQ
• MongoDB

Please see

• go.mod
• package.json

Contributing

• Contributions and Feedback are always welcome!
  • Open a new issue

License

• MIT