Introduction#
dxaws-* is a service based ecosystem.
The goal of this architecture is to establish a solid, stable foundation that service modules can build upon without coupling themselves to orchestration layers (runbooks, aggregators, Step Functions). This is achieved by enforcing immutable public contracts at the Manager boundary and by standardizing runtime construction through factories.
The Players#
We have a cast of players in our ecosystem, each with a specific role.
The Manager#
The manager is the client-facing member of the module. Clients that wish to use the module will talk with the manager, basically giving the manager their desired state of the system. Once the desired state of the system has been communicated, the manager will work with the team to achieve the client’s desired system state.
Clients express desired capabilities (e.g. storage, distribution, naming, trust), not concrete AWS resources. The Manager is responsible for selecting and orchestrating appropriate implementations to satisfy those capabilities. So, the client may ask for storage. The manager could implement this with a number of different AWS services. The client should not know or care which AWS services are being used. This allows the module to evolve as the underlying systems and available services change over time.
The Planner#
The planner is non-destructive. The planner gets the desired state ot the system from the manager and compares it to the current state of the system. The planner then makes decisions about how to proceed with either a:
- NOOP - no changes are required
- CREATE - a new resource is required
- UPDATE - an existing resource is required
- DELETE - a resource is no longer required
This plan is then returned to the manager, who will then either tell the client that the state of the system matches their desired state OR, will take the planners plan and hand it off to the executor.
The Executor#
Takes the plan from the manager and works with the provider to execute it.
The Provider#
The provider is the link between AWS and dxaws. The planner and the executor use the provider to learn the state of the system and make changes.
The Factory#
A Factory is the composition root for dxaws runtime objects. It is responsible for constructing and caching shared primitives (AWS session context, providers, observability emitters) so that:
- managers do not manually wire dependencies
- orchestration layers never instantiate providers directly
- policy (default region, account selection, correlation IDs) is injected consistently across modules
Factories are extend-only: new construction helpers may be added over time, but existing construction behaviour and signatures are treated as contract.
Observability (o11y)#
Observability is a first-class primitive in dxaws-core. Managers emit well-structured events during planning and execution so actions can be traced, correlated, and audited consistently across all modules.
Key rules:
- o11y is transport-agnostic: the event envelope is stable, sinks are swappable (noop, logging, EventBridge, etc.)
- modules may emit events freely; emitting must always be safe (noop by default)
- correlation IDs are injected by factories and carried through planning and execution
The Management Team#
Clients interact with dxaws modules exclusively through the Manager. Module internals (planners, executors, providers) are not part of the public contract.
This is the commonality between all dxaws services. Each module will have access to a number of common resources so that clients using the system can know how to frame desired plans and how the work that a module is doing can be observed.
This does not necessarily mean that all module managers use the same shapes for their desired planes and results, but rather that the all modules work in a similar way. The client talks to the manager, conveys a desired state of the system, the manager then works with the internal team to achieve that state and then reports back to the client.
Managers provide built-in observability hooks so planning and execution can be traced, correlated, and audited consistently across all modules.
Design Invariants#
The following design invariants apply across all dxaws-* modules.
These are intentional constraints and should be treated as architectural
rules rather than implementation details.
The Manager is the only public entry point
Clients interact with a module exclusively through its Manager. Planners, executors, providers, and other internal components are not part of the public contract and may change freely without impacting clients.Clients express desired capabilities, not implementations
Clients describe what they want (e.g. storage, distribution, naming, trust), not how it is implemented. The Manager is responsible for selecting and orchestrating appropriate underlying services.Planning is non-destructive
The Planner must never modify external state. Its sole responsibility is to compare desired and current state and produce a deterministic plan describing the required actions.Execution is the only place side effects occur
All interactions that mutate external systems (e.g. AWS APIs) are performed by the Executor via a Provider. This boundary is explicit and enforced to support reasoning, testing, and observability.Module internals are replaceable
Providers, planners, and executors are implementation details. They may be replaced, extended, or refactored without changing the module’s external contract.Managers expose stable contracts
The shapes used to describe desired state, plans, and results form a module’s public contract. These contracts are expected to be stable and backwards-compatible over time.Observability is built in by default
All Managers provide standard observability hooks so that planning and execution can be traced, correlated, audited, and debugged consistently across modules.Factories standardise construction
Managers are constructed via standard factory mechanisms (e.g. control-plane factories). This ensures consistent injection of runtime context, observability, and policy across all modules.Testing reflects architectural boundaries
Unit, integration, and acceptance tests are structured to reinforce these boundaries: planners are tested without side effects, providers are validated independently, and acceptance tests verify real-world behaviour.
Contracts and Versioning#
dxaws module contracts are defined at the Manager boundary: the shapes used to express desired state, plans, and results. These contracts are treated as immutable and must be backwards-compatible over time.
Rules:
- contracts are extend-only (add optional fields, never rename/remove)
- behavioural changes that affect existing clients require a major version bump
- internal components (planner/executor/provider) may be refactored freely as long as Manager-visible contracts remain stable
Factories and o11y are also treated as contracts because they define standard construction and observability behaviour across the ecosystem.