Stack sharding
Why a large app splits into nested stacks, and why it's mostly transparent.
CloudFormation caps a single stack at 500 resources. A wisp route costs roughly 5 of those (function, role, log group, route, integration, permission) — a stack saturates somewhere around 60–70 routes. wisp handles this before you hit it.
What happens
Every function always lives in a shard — a nested AWS::CloudFormation::Stack, not a special case that kicks in
only for large apps. Functions are grouped by their source directory: everything in src/routes/ lands in one
shard, src/queues/ in another, and so on — the mapping between your file layout and the console is meant to stay
intuitive.
Shared resources (Store, Queue, Api, Bucket) stay in the root stack. A route's Integration/Permission, a
queue consumer's EventSourceMapping, a schedule's whole complex, and a workflow's Lambda all travel with their
owning function into its shard — otherwise sharding wouldn't actually relieve the resource-count problem it exists
to solve.
If one directory alone would exceed roughly 350 resources, wisp splits it further automatically and prints a warning naming the directory — the one case where the "one shard per directory" mapping stops being perfectly 1:1.
What you don't have to think about
Cross-shard references — a route in one shard reading from a Store that lives in root, or a workflow's Lambda
living in a different shard than its own state machine — are wired up automatically via CloudFormation nested-stack
parameters and outputs. wisp deploy uploads every shard's template to your artifact bucket and deploys them all as
part of one root-stack change set; there's nothing to orchestrate by hand.
Where it's visible
wisp synth writes every shard's template to .wisp/shards/, alongside the root template at
.wisp/cloudformation.json — worth a look if you're curious how a specific cross-shard reference resolved, but not
something a normal wisp workflow requires you to open.