Phase 0 PR Review -- Scratch / Action Notes

Specific Actions for review findings:

3.1 Plan Deviations.

1. The proper location of the constructs is not in src/main/cdk/constructs/email but rather in src/main/cdk/constructs/xgress.

   • Rationale: the xgress directory contains all the mechanisms by which the system can send or receive information and interactions for the external world.

   Claude Question — C4

   When does the constructs/email/ → constructs/xgress/ relocation happen?

   • (a) Amend PR #445 to land it relocated.
   • (b) Land PR #445 as-is; first follow-up commit on main does the move.
   • (c) Bundle with the N8 redesign (§4.2 below) since both touch the same files.

   Also: with this change, does the external constructs category proposed in runtime-design-review.md §4.5 still apply, or does xgress subsume it? See related question C2 in runtime-design-review.md.

2. Should Adopt recommendation.

3. Follow M3 decision.

3.2 Scope Additions

• O.K. to keep, need to be documented as extension in the requirements and design documentation.

4. Findings

4.1 Major

Finding	Action
M1	Adopt Recommendation
M2	Adopt Recommendation
M3	(1) Adopt Short term recommendation (2) Create Issue in Linear: Team PDEV, Initiative Product / OAM / Security, Project Security / Improvements, Release: MVP3, Title: Infrastructure 1Password secret reader
M5	Adopt Recommendation
M4	Adopt Recommendation

4.2 Minor

| Finding | Action | | N1 | (1) Hoist logging.ts to scripts/lib/, (2) Adopt Recommendation | | N2 | Adopt recommendation after N1 mitigation is complete and logging.ts is relocated | | N3 | PENDING | | N4 | Keep As-Is for now | | N5 | Verify they are in Documentation PR: https://github.com/Arda-cards/documentation/pull/64 | | N6 | As part of the redaction utility relocation (N1), the coverage should be enhanced. The unit tests should also be moved and enhanced | | N7 | Agreed. This stack is very likely to not change much. DESTROY helps with the operations workflows | | N8 | This is actually a bigger issue than it appears. It conflates the “freeKanban” server with the partition configuration. It needs to be redesigned based on the newly stated principles so that (1) Partitions do not know anything at all about the free kanban tool (this is part of the Corporate instance class) and (2) there are no magic if-then-else conditions in the code, the behavior should be driven by configuration of the stack, not by “control flags” that introduce control coupling between different parts and layers in the system |

Claude Question — C3

N8 redesign timing. Post-redesign shape (per the principles): the FreeKanbanRecords stack is invoked from a Corporate App that consumes the partition’s DNS sub-zone via the cross-instance reference pattern (importValues, since the zone id is a CFN export). Today’s wire-in lives in apps/Al1x/partition.ts gated by INCLUDE_FREE_KANBAN_RECORDS=true. Choose:

• (a) Include the redesign in the immediate Phase 0 follow-up (consolidated updates list).
• (b) Defer to a successor project. Operationally costless because the wire-in is dormant until Phase 1 lands the prod.ardamails.com sub-zone.
• (c) Couple with C4 timing — whichever PR moves the construct to xgress/ also performs the redesign.

MP Comment — C3

This surfaces one more inconsistency. The domain for the free kanban tool should not be part of prod.ardamails.com as it introduces a cross-domain dependency. It should be part of the corporate instance class. This may require adding extra zones, that for now will live in the Root account. The prefix should be arda resulting in a root domain for all email to be sent by corporate: arda.ardamails.com.

The Corporate App should not consume Partition resources in this case

5.3 Nit Findings

| Finding | Action | | Nit-1 | Should be part of next round of commits | | Nit-2 | No Action | | Nit-3 | Make the update in the next push | | Nit-4 | Add the comment |

Corporate Infrastructure Composition

Reading the Diagram, unless an arrow has a specific label:

• The contents of Runtime represents the instances that are created when the scripts are run.
• The contents of IaC represents the code Artifacts that define the configuration for the instances.
• .|> arrows mean instantiation of
• .> arrows in the IaC scope mean import as it is the only meaningful relationship at code time.
• .> arrows in the Runtime scope means uses the values of the target object.
• *-> arrows mean contains as in the Application contains Stack.

Additional Round After Reading Diagram

Claude Feedback

Inconsistencies to resolve

I1. Construct path for Postmark thin-wrappers

• Your C2 MP Comment says: “Create a constructs directory under platform that contains the thin wrappers …” → platform/constructs//.
• The diagram shows: constructs/external/postmark/PostmarkServer.

Which path is correct? Possibilities:

• (a) Diagram is canonical → src/main/cdk/constructs/external//. Treats third-party-API constructs as a sibling category to xgress/, compute/, etc.
• (b) C2 text is canonical → src/main/cdk/platform/constructs//. Treats third-party-API constructs as part of platform/ (the configuration / external-reference layer) rather than the resource-construct layer.

The semantic implication differs: (a) says these are first-class Arda constructs that happen to wrap external APIs; (b) says they’re platform-level definitions that other constructs treat as primitives.

I2. Stack class name

• Your B.4 answer said: “Stack name should be more focused: CorporateEmailDnsStack. It should be placed in stacks/corporate/dns.ts”.
• The diagram labels the stack CorporateEmail.

Which is intended? CorporateEmailDnsStack is more precise (explicit it’s the DNS layer, not e.g. SES). CorporateEmail is broader (could later own SPF/DMARC at the corporate-zone level too).

I3. Arrow direction FreeToolPostmarkServer gets values from FreeToolDnsRecordSet

The legend says .> in Runtime scope means “uses the values of the target.” Reading the arrow FreeToolPostmarkServer <.u. FreeToolDnsRecordSet : gets values from:

• Strict reading: PostmarkServer is the target; DnsRecordSet uses the server’s values.
• Label reading: PostmarkServer gets values from DnsRecordSet.

These contradict. In Postmark reality the server emits the DKIM key (and you publish it in DNS), so the values flow Server → Records. The arrow likely needs reversing (or the label says “verifies via”), but I’d like you to confirm intent before I encode it in the consolidation.

Implementation question

J1. How does the external/postmark/PostmarkServer construct create a Postmark server at deploy time?

Three plausible mechanisms:

• (a) AWS CDK Custom Resource: Lambda-backed; the construct emits a Custom Resource into the CFN template; the Lambda calls the Postmark API on stack create / update / delete. This is the only fully-declarative path within a single cdk deploy. Cost: Lambda code in inline-lambdas/, IAM role for the Lambda, Postmark token visible to that Lambda.
• (b) Two-phase deploy orchestrated by the Corporate CLI: phase 1 = imperative call to Postmark API to create server (via the thin wrapper), capture results into CDK context; phase 2 = cdk deploy reads context and emits records. Conceptually two artefacts, glued by the CLI.
• (c) Synth-time helper: the construct’s constructor runs the Postmark API call during synth (network-side-effecting synth). Fast but breaks CDK reproducibility (synth becomes non-deterministic and requires Postmark auth at synth time).

(a) is the most CDK-idiomatic; (b) is closest to today’s Phase 0; (c) is fastest to implement but architecturally questionable. Which path do you intend?

The choice cascades into other Phase 2 deliverables — the Lambda inline-code, IAM scoping, and how the Corporate CLI orchestrates the deploy.

I1

(b) C2 text is canonical

I2

The Diagram is correct:

Rationale: We want to differentiate between the Stack (set of resources that share a lifecycle, i.e. deploy together) and the Constructs that define them. The Stack is properly named CorporateEmail as it will include all the resources needed for Corporate Email, not just Dns records, even though right now the only contents is those records.

I3

This is a mistake in the diagram. That was intended to be an informative arrow. The real mechanism is that the PostMarkServer construct will have some built-with values that the Stack will transfer to the DnsRecordSet and neither construct depends on the other. The arrow can be eliminated, the dependency is handled by the calling Stack.

J1

The correct solution is (a). For this interim we are going to externalize that dependency and absorb it in the Corporate CLI layer (b). Documentation must reflect this explicit Tradeoff.