Design Notes for dxaws-website

Architecture

dxaws-website is an orchestration module that composes primitive modules (S3, ACM, CloudFront, DNS) without implementing raw AWS service logic in this package.

This module:

  • does not expose a Module facade

  • does not expose legacy planner/executor top-level APIs

  • does expose a manager-centric flow: get_current -> plan -> apply -> execute

Typed inputs and outputs

Primary intent is represented by WebsiteDesired.

Current state is represented by WebsiteCurrent.

Execution returns WebsiteResult and optional WebsiteOutputs (when apply runs).

Convergence actions

WebsiteManager.plan() chooses one action:

  • create: required components are missing

  • update: some components exist but state is partial or not ready for full convergence

  • wait: async readiness is pending (for example ACM certificate still validating, or CloudFront distribution still deploying)

  • noop: all required components exist and are ready

noop is only selected when all of the following are true:

  • origin is present

  • certificate exists and is issued

  • distribution exists and is deployed

  • DNS records are ready

Execution behavior

WebsiteManager.execute(desired):

  1. Reads current state via provider get_current.

  2. Plans an action.

  3. Applies only for create and update.

  4. Returns outcome:

    • applied when changes were executed

    • wait when convergence is pending async readiness

    • noop when already converged

Boundaries and dependencies

The manager orchestrates and delegates to provider operations:

  • ensure origin

  • ensure certificate

  • ensure distribution

  • ensure DNS

Provider implementations can route to primitive modules/adapters. The orchestration layer remains responsible for action selection and stable result shape.