Files
coding-standards/components/domains.md
T
2026-11-14 19:16:24 +05:00

4.2 KiB

Domains

All domains must conform to the generic domain interface located in internal/application:

type Domain interface{
	// Configure performs domain configuration. Called after ConnectDependencies().
	Configure() error
	// ConnectDependencies gets necessary dependencies (other domains) from application singleton's
	// registry. Called on application start after all needed domains are registered with singleton.
	ConnectDependencies() error
	// Initialize initializes internal state. Called when RegisterDomain() is issued.
	Initialize() error
	// LaunchStartupTasks launches tasks that should perform some actions on start or when these tasks
	// should work in background (in separate goroutine). Called after ConnectDependencies() and Configure().
	LaunchStartupTasks() error
	// Name returns domain name.
	Name() string
	// Shutdown performs shutdown actions for domain.
	Shutdown() error
}

Domains categories

Every domain MUST have proper categorisation. Currently this document defines some standard categories:

  • core - core/low-level functionality (e.g. HTTP server, database connection handling, low-level local disk storage handling).
  • features - business code itself (e.g. working with users).
  • integrations - third-party integrations proxy domains (e.g. integration with third-party API).

This isn't a comprehensive list, as specific application might require own domain category not described here, for example, protocols category where chat protocols lie (for a multi-protocol messaging app).

Domains registration

Domains should register themselves in Initialize(app *application.Application) error function which should be called in main() function of binary. It should be done like that:

in main.go:

package main

import "log/slog"

func main() {
	app := application.New()

	lgr := app.Logger("module", "main")

	checkError(lgr, somedomain.Initialize(app))

	checkError(lgr, app.Start())

	<-app.ShutdownChan

	if errs := app.Shutdown(); errs != nil {
		lgr.Error("Failed to shutdown app!", "errors", errs)

		os.Exit(2)
	}
}

func checkError(lgr *slog.Logger, err error) {
	if err == nil {
		return
	}

	lgr.Error("Failed to start app!", "error", err.Error())

	//revive:disable-next-line:deep-exit
	os.Exit(1)
}

in internal/domains/core/somedomain/somedomain.go:

var errDomain = errors.New(core.DomainNameSomeDomain)

type domain struct {
	app *application.Application
}

func Initialize(app *application.Application) error {
	dmn := &domain{
		app: app,
	}

	if err := app.RegisterDomain(dmn); err != nil {
		return fmt.Errorf("%w: %w", errDomain, err)
	}

	return nil
}

On application singleton's side function (a *Application) RegisterDomain(domain Domain) error should be implemented (see above).

Domain-specific data

Domain-specific data should be placed in domainname.go file within category, e.g. internal/domains/core/config.go for configuration domain internal/domains/core/config. It should look like that:

package core

import (
	"errors"

	"internal/domains/core/config/dto"
)

// DomainNameConfig is a configuration handling domain name.
const DomainNameConfig = "core/config"

// ErrConfigIsInvalid indicates that configuration domain implementation isn't conforming to its interface.
var ErrConfigIsInvalid = errors.New(DomainNameConfig + " implementation is invalid")

// Config is an interface for configuration handling implementations.
type Config interface{
	Get() *dto.Config
}

Where:

  • DomainNameConfig is a constant with domain's name that is returned by Name() string function of that domain.
  • ErrConfigIsInvalid is a domain's error that should be exported for later use by other domains in any way (checking for presence or even returning it). There can be more than one error here.
  • Config is a domain-specific interface that can be used by other domains.

Domain-specific interface

In addition to domains common interface described above, every domain might have own interface which discloses inter-domain API. That API should use only DTOs (see DTOs and models).

All signatures here should have comments describing what this function does, as these comments will be shown to end users in IDEs or editors with LSPs attached when using autocomplete or documentation browser.