Go Elemental

The Go implementation of the Elemental Architecture. Go Elemental implements the architecture on the Go standard library, and its goal is to demonstrate what the platform provides by itself: a complete reference architecture with the smallest deliberate dependency surface, expressing the architecture's supply-chain purpose in its strictest form.

The dependency line

Every Go Elemental module follows one dependency line: bottom-up, no provider in a base, kept light. The Dependencies principle states it per tier, along with when a capability is written in-house and when a library is sourced.

The declared stack of the standard's reference architecture selects one provider per service; for SQL that provider is Postgres.

Principles

The conventions every Go Elemental repository shares, enhancing the architecture principles. A member repository may enhance one further, stating the enhancement beside its link to the principle.

Member repositories

By tier of the repository topology. Each repository documents itself: its README states its place in the standard and the principles it enhances, and its package documentation states its API.

Tier Repository Purpose
Core SDK go-core The common primitives every Go Elemental application type uses: layered configuration, the process lifecycle, logging, the process sequence with its integration toolkit, the reactor that joins a source of occurrences to a handler, and the CloudEvents event envelope a domain raises its events in.
Infrastructure libraries go-database The SQL infrastructure service: the connection pool with its configuration, lifecycle, and readiness, the database admin service, the general sweeper (sweep), which runs a service's reclaimers as one reactor under a per-reclaimer advisory lock, and the PostgreSQL provider as a sub-module.
Infrastructure libraries go-messaging The messaging infrastructure service: the broker-agnostic contract a service emits events and runs reactors on, the transactional outbox and the idempotent inbox, with the PostgreSQL engine, which holds the outbox and inbox retentions, and the NATS JetStream provider as sub-modules.
Infrastructure libraries go-observability The observability infrastructure service: OpenTelemetry configuration and process lifecycle, the trace-correlating log handler, HTTP server middleware, and the request-ID source function, with the OTLP exporters as a sub-module.
Infrastructure libraries go-storage The object storage infrastructure service: the standard-tier client interface over the operations Azure Blob and S3 share, the lifecycle wrapper that bounds and gates it, and the conformance suite a provider proves itself against, with the Azure Blob and S3 providers as sub-modules.
Application SDKs go-web-sdk The SDK for Go Elemental web services: the server, routing, problem responses, paginated reads, the probes, middleware, and the integration toolkit.
Application SDKs go-cli-sdk The SDK for Go Elemental command-line tools: a dispatcher on the standard library's flag whose commands build only the graph nodes they declare, and the scenario runner.
Templates go-web-sdk-template Scaffolds an initial Go Elemental web service, engine-free, with the composition root as one file per layer and the integration tier in place.
Templates go-cli-sdk-template Scaffolds an initial Go Elemental CLI, engine-free, with the composition root as one file per layer and the integration tier in place.
Reference architectures go-web-service The holistic Go Elemental web service reference, grown in documented layers on the declared stack; versionless until its 1.0.

Two libraries stand adjacent to the standard rather than in it: standalone libraries any Go project can adopt on its own, each with its guide in its own repository.

Keyboard shortcuts

Settings