Topology and naming

How Go Elemental repositories, modules, packages, and release tags are named, and the module layout of each tier. The tiers themselves are defined by the organizational repository topology.

Repository names

A repository is named for its language and its tier, so the name states what a reader will find and where it belongs.

An adjacent library belongs to no tier, so it takes no go- prefix: it presents no one technology and is named for what it does, as sqlate and blobfs are.

Module layout per tier

Application-layer import direction

Every Go Elemental application — whatever its type — divides into three tiers with one import direction: of its own module's packages, cmd/* imports only internal/*; internal/* is the composition root and may import any root-level package; and nothing at the root level imports internal/*. Outside its module, cmd/* may import the SDK packages the application composes over: go-core for process setup, whose process package owns the signal context and the exit path, and the application SDK, such as go-cli-sdk, whose cli.Streams value carries a CLI's standard streams from its entrypoint into the composition root. A cmd/* binary is initialization alone: it constructs the application from internal/* and never reaches past it into its own module. internal/*'s own layers import each other and the root-level packages that make up the application's domain and infrastructure, but the reverse never happens — a root-level package importing back into internal/* would make domain code depend on how it is wired, not on what it is.

Go's internal/ visibility rule enforces only the outer edge: nothing outside the module can import a package under internal/. It enforces nothing on the inner one — within the module, a root-level package importing internal/domain compiles. The direction is a convention, kept by review and package documentation, not by the compiler.

The composition root, internal/app, describes the application as one dependency graph on go-core's graph, one file per layer of the architecture. Each layer file defines its layer's nodes in one define function: one file the infrastructure services, one the administrative services, one the domain services, and one the reactors, and the administrative and domain files also build their mounts. server.go defines the request edge: the readiness the probes report, the router, and the server. The list of mounts and the middleware stack are each a file of their own, and a layer the application adds, such as go-web-service's telemetry, is one more file. Beside them, app.go holds the Nodes value, one handle per node; New, which describes the graph and cannot fail; and Run, which builds the graph and runs it under the lifecycle coordinator. The layer files are the architecture's layer list, and extending the application means defining a node in its layer's define function, a reactor's node also joining Nodes.Reactors, while the signatures, the entrypoint, and Run stay untouched. A package that the layers share and that must not import the composition root, the application's database infrastructure for one, lives at the root level.

This is an Application-layer principle, independent of application type: a web service's internal/app is one realization, and a CLI composes its own internal/app the same way. It does not apply to a core SDK or an application SDK, which are libraries, not applications, and have no composition root of their own.

Release tags

Keyboard shortcuts

Settings