Overview

The Runtime view describes Arda’s platform from the perspective of the resources that make it operate: compute, storage, networking, ingress / egress, identity, secrets, and the third-party services Arda depends on. It is one of the system views, alongside the Source view (repositories, code structure) and the Process view (development, build, release workflows).

Guiding Principles

The Runtime view is governed by the following principles. They apply to every page in this section and to every resource described in it.

1. The infrastructure repository is the single reference for the Arda platform

The infrastructure repository is the authoritative description of every resource the Arda platform depends on, regardless of where that resource ultimately lives. Resources fall into three categories:

Category	Examples	How infrastructure represents them
AWS resources managed by Arda	VPCs, EKS clusters, S3 buckets, IAM roles	Defined and deployed via CDK (preferred) or CloudFormation (legacy)
External resources Arda consumes but does not create	Postmark accounts, 1Password account, GitHub organization, Documint account, domain registrations	References to the externally-created resource: identifiers, secret references for credentials, plan / version attributes
Resources in third-party services Arda creates and maintains via IaC	Postmark servers and sending domains, GitHub Actions secrets, Helm releases	Defined in code; created and reconciled via the third-party’s API, CDK custom resources, or specialized tools

If a resource is part of how the Arda platform runs and it is not defined or referenced in this repository, that is a defect.

2. IaC is unit-tested

Every IaC module — CDK constructs, stacks, apps, and the supporting code that drives third-party APIs — has unit tests covering its internal logic and resource-shaping decisions. Unit tests run locally and in CI before any change merges.

3. Resource management is operator-driven via dedicated scripts

Day-to-day creation, update, and reconciliation of resources is manual in the sense that an operator triggers it. The operator does not make discretionary configuration changes at invocation time. Each operation has a dedicated script that:

• Is robust — designed to avoid partial failures and to be safely rerunnable.
• Is self-defined — sources every value it acts on from versioned configuration in this repository, not from operator-provided parameters or interactive prompts. Operator inputs are limited to selecting which target instance to act on and to local-environment variability (AWS profile, kubectl context, dry-run mode).
• Is self-documenting — explains what it is about to do, what it has done, and surfaces the operator-facing prerequisites it depends on.

4. Drift is detected automatically

Periodic integration tests run against the live runtime to verify that each resource’s actual state matches its IaC description. Drift surfaced by these tests is treated as a defect — either in the IaC, in the upstream service, or in operator practice.

5. The platform is organized as instance groups

Three instance groups make up the runtime platform. Each group has its own naming, lifecycle, and ownership conventions. The same code hierarchy (Constructs → Stacks → Apps) applies to all three.

Group	Members	Purpose
Arda Application Runtimes	Infrastructures: Alpha001, Alpha002, SandboxKyle002. Partitions: dev, stage, demo, prod, kyle. Amplify applications per partition.	Deliver Arda’s commercial products to end-users. See Platform Structure.
Platform-level	Root (cross-cutting resources such as DNS root zones); OAM (operate, administer, maintain — placeholder, to be defined).	Resources that span the whole platform and are not attributable to any single application runtime.
Corporate	free-kanban-tool (part of arda.cards). Future: HubSpot integrations, marketing website assets, other internal information systems.	Information systems that support Arda’s business but are not part of the customer-facing application platform.

6. Code follows the CDK hierarchy

The infrastructure repository organises its TypeScript code in three tiers, mirroring the CDK abstractions even when the underlying tool is not strictly AWS CDK:

• Constructs — reusable resource patterns parametrised by behavioural configuration. See Constructs.
• Stacks — groups of resources deployed together; fix most configuration but receive naming and context from their callers. See Stacks.
• Apps — top-level definitions that deploy one or more stacks for a specific instance, fixing names and instance-level configuration. See Apps.

The same hierarchy applies to non-AWS IaC code (e.g., third-party API choreography): operations have reusable units (constructs-equivalent), composed groups (stacks-equivalent), and instance-scoped invocations (apps-equivalent).

Contents

• Platform Structure — Application Runtime containment hierarchy (Root → Infrastructure → Partition → Component → Resource), naming conventions, FQN composition.
• Runtime Environments — current Infrastructures and Partitions, mapped to AWS accounts and regions.
• Build and Deployment — how component artefacts are produced and installed into a partition.
• Development Pipelines — CI/CD pipeline structure across repositories.
• DNS Structure — three-level DNS hierarchy for public capability URLs.
• URL Naming — URL composition rules and versioning conventions.
• Network Routing — request path from client through Arda’s network stack.
• mTLS — mutual-TLS layer between Amplify BFF and the API Gateway.
• Static Assets — asset-storage subsystem.
• Infrastructure as Code — CDK code organisation, stack and construct patterns, deployment orchestration.