Apps, Stacks, and Environments

## Three layers, one tree An AWS CDK program is not a script that calls AWS APIs. It is a program that builds an in-memory tree of objects and then prints CloudFormation. The nodes of that tree are **constructs**: objects whose constructor signature is `(scope, id, props)`, where `scope` is the parent construct. A construct by itself creates nothing in AWS — it is a piece of a description. Two constructs carry special meaning. **`Stack`** is the boundary at which description turns into a deployable artifact. One `Stack` instance synthesizes into exactly one CloudFormation template and is deployed as exactly one CloudFormation stack, into one AWS account and one region. **`App`** is the root. You create it first, scope your stacks to it, and never deploy it — there is no AWS object called an App. ```typescript const app = new cdk.App(); const env = { account: '111122223333', region: 'eu-west-1' }; new NetworkStack(app, 'Network', { env }); new ServiceStack(app, 'Service', { env }); app.synth(); ``` ## What synthesis produces `cdk synth` walks the tree, lets each construct contribute CloudFormation resources to the stack it lives under, and writes a **cloud assembly**: a directory (`cdk.out` by default) containing one template file per stack plus metadata the CLI uses. From that moment on, AWS sees only CloudFormation. Your classes, your loops, your `if` statements and the construct tree itself do not exist at deploy time — they ran already, during synthesis, on your machine or your build runner. This is the reason the question has exactly one answer: the Stack is the thing AWS creates. `cdk deploy Network` calls CloudFormation with the template that stack produced. ## Why the Stack boundary is the one that matters Because a stack is the CloudFormation unit, it is simultaneously the unit of several things you care about: - **Deployment.** `cdk deploy Service` deploys one stack; `cdk deploy --all` deploys every stack in the app. `cdk list` shows you the names. - **Rollback and blast radius.** A failed update rolls that stack back. Resources in a different stack are untouched. - **Limits.** CloudFormation caps the number of resources in a single stack, so a large estate has to be split. - **Lifecycle.** A VPC that changes twice a year and a service that deploys twice a day do not belong in the same stack, because every deploy of the fast-moving thing puts the slow-moving thing into an update. So splitting an app into stacks is an architectural decision, not code tidying. The rule of thumb is: things that must deploy together and roll back together go in one stack; things with independent lifecycles go in separate stacks. Constructs are the opposite — they are free to reorganise. Wrapping several resources in your own construct class does not create a new deployment unit; those resources still belong to whichever stack the construct is scoped under. Composition is a code-structure tool; stacks are a deployment tool. ## Where the environment attaches `env` — the account and region a stack targets — is a property of a **Stack**, not of the App and not of an individual construct. Two stacks in one app can target two different accounts, or two regions, because each one becomes its own CloudFormation stack in its own environment. This is also why an App is not "an account": one app routinely spans several. Between App and Stack there is an optional layer, `Stage`: a group of stacks you can instantiate more than once, typically once per environment. `App` is itself a subclass of `Stage`, which is why stages nest naturally under it. ## What candidates get wrong The two common errors are collapsing the layers in either direction. One is treating the App as the deployable thing ("the app is my CloudFormation stack"), which makes stack boundaries look like folders and leads to one enormous stack. The other is imagining that each construct maps to a stack, which makes the resource limit and rollback behaviour incomprehensible. A third, subtler error is believing the CDK talks to AWS while your code runs. It does not — apart from synth-time context lookups, the CDK's entire job is to emit templates, and every deployment decision is CloudFormation's.