Adding a module¶
A module is a feature with its own backend rings, frontend feature folder, settings, documentation and tests. This page is the reference for what a module consists of. If you would rather learn by building one, follow the developer guide, which writes a small widget step by step in about 30 minutes.
Start with the generator¶
make new-module NAME=quotes TITLE="Quotes"
The generator creates every file listed below with working placeholder code and tests, and registers the module through files of its own. Nothing in a shared list needs editing, so two modules developed in parallel do not conflict. Modules explains the convention.
The steps below use a quotes module that shows a random quote as the
example.
Backend¶
-
Domain,
internal/modules/quotes/domain/. The entityQuotewith a constructor that enforces its invariants, and domain errors that wrap the kinds frominternal/shared/kernel, such askernel.NewPublicError(kernel.ErrNotFound, "…"). Only the standard library and the kernel may be imported here. Cover the rules with table tests. -
Use cases,
internal/modules/quotes/usecase/. One input-port interface per use case (RandomQuote), the output ports it needs (QuoteRepository,kernel.Clock), request and response models, and the implementations. Use cases never return entities; they map them to response models. Test them with fakes for the ports. -
Gateway,
adapter/gateway/. Implementations of the output ports: SQLite throughdatabase/sql, HTTP clients injected from outside. Migrations go intoadapter/gateway/migrations/0001_init.sql, embedded and exposed throughMigrations() fs.FS. Map rows to entities and back, and write integration tests withdbtest.Open. -
Presenter,
adapter/presenter/. JSON DTOs and the functions that map response models to them. -
Controller,
adapter/controller/. Request DTOs indto.goand handlers that decode withhttpapi.DecodeJSON, call the input port and answer withhttpapi.WriteJSONorhttpapi.WriteDomainError. Test them withhttptestand fake use cases. -
Module,
internal/modules/quotes/module.go. Embedmodules.Base, build gateway, use cases and handlers inNew(...)and implementName,DataKind, andMigrations,RegisterRoutes,JobsandWidgetKindsas needed.DataKindis required and says who owns the module's data (ADR 0018):InstanceDatafor what admins manage for everyone,PersonalSettingsfor one row per account,PersonalContentfor records people create themselves. A personal-content module addsowner_idandvisibilityto its tables and filters every query withsqlutil.VisibleTo(reads) orsqlutil.OwnedBy(changes);internal/archtestrefuses a query that forgets it. Add the module to the list incmd/server/datakind_test.goand the table in the ADR. Register everything that needs a session throughr.Protected. For sample data, implementmodules.Seederwith an idempotent use case. -
Composition root,
cmd/server/module_quotes.go. Registers the module withregisterModuleininit(). Add the module name to the list in.env.example. -
End-to-end check,
cmd/server/api_quotes_test.go. Registers a check withregisterModuleE2E: a fake upstream, a configuration override and a request against the fully wired server.
Frontend¶
-
Types. Run
make generate. The generator finds the presenter and controller DTO packages by convention and writes the TypeScript types. -
Feature folder,
web/src/features/quotes/, withdomain/,usecase/(the port interface and the use case class),adapter/api/(implements the port and maps DTOs to domain types),ui/(the widget and an optional settings component),i18n/en.tsandi18n/de.ts, and anindex.tsthat exports the public API. -
Registration, each in a file of its own:
web/src/app/services/quotes.ts(the service in the container),web/src/app/widgets/quotes.ts(the widget, its picker category and icon) and, if the module has settings,web/src/app/settings/quotes.ts. Answers in the quick search go intoweb/src/app/search/quotes.ts. -
Browser test,
web/e2e/features/quotes.spec.ts, if the widget does something worth clicking through. Importaccountandpasswordfrom../supportand log in at the start; the account already exists, because thesetupproject runs first. Leave shared state as you found it, or work on a tab of your own, since all specs use one server. The file is new, so it never conflicts with other open pull requests.
Documentation and API¶
-
Module page,
docs/modules/quotes.md: what the module does, its configuration, the outside requests it makes and its endpoints. Add a line to the feature overview as well. -
OpenAPI,
api/modules/quotes.yaml: tags, paths and schemas of the module.make openapimerges and checks the fragments. -
Decision record. If the module introduces a notable decision, such as a new kind of outside access, write an ADR in
docs/adr/.
Run make ci and make smoke before you open the pull request. The
checklist for integrations with outside services, covering timeouts,
secrets and outbound requests, is at the end of the
developer guide.