# 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.