The whole system on one page

In 1 minute

MiniTickets has two apps that answer users, a web app and an API, both running as containers on ECS Fargate behind one load balancer. The API is the only part that touches the data: Postgres for records, Valkey for fast shared memory. Background work runs on SNS, SQS and two Lambda functions. DNS (Cloudflare) and the build pipeline (GitHub Actions) live outside AWS.

Picture it

flowchart TB
  B[Browser] --> ALB[ALB]
  ALB -->|"pages"| W["Web app<br/>Next.js on ECS"]
  ALB -->|"/trpc/*"| A["API<br/>Fastify on ECS"]
  W -->|"http://api:4000"| A
  A --> PG[(RDS Postgres)]
  A --> V[(ElastiCache Valkey)]
  A -->|"events"| S["SNS → SQS"]
  S --> L["Lambda: email, tickets"]

Learn this picture first. Every later chapter zooms into one box or one arrow.

How it works

1. The browser loads pages and calls the API on the same address. It never talks to a database.
2. The ALB (Application Load Balancer) is the one way in. It sends /trpc/* to the API and everything else to the web app.
3. The web app renders pages. To render /events on the server, it calls the API on a private name, http://api:4000, that never leaves AWS.
4. The API holds all the business logic and is the only code that reads or writes Postgres and Valkey.
5. Background work starts from an SNS topic: queues feed one Lambda that sends emails and one that makes QR tickets, stored in DynamoDB and S3.

In MiniTickets

Part	Where it runs	Code
Web app (Next.js)	ECS Fargate, port 3000	apps/web
API (Fastify + tRPC)	ECS Fargate, port 4000	apps/api
Worker and tickets functions	Lambda, one arm64 image	apps/worker
Infrastructure	Pulumi, TypeScript	infra
DNS	Cloudflare, outside AWS	records printed by Pulumi
CI and CD	GitHub Actions, outside AWS	.github/workflows

Four switches in the committed infra/Pulumi.dev.yaml decide what exists: dataEnabled, computeEnabled and entryEnabled are on; cdnEnabled is off, so CloudFront is built in code but not running. The map grows the system in 25 stages, from the account (stage 0) to the alarms (stage 24).

Open the full map →

See it in AWS

Console

Resource Groups → Tag Editor, region us-east-1: every resource of the stack has a name that starts with minitickets-dev.

CLI

aws ecs list-services --cluster minitickets-dev lists the two long-running services.

Code

The infrastructure entry point imports one file per layer: infra/index.ts.

Break it

Symptom	Cause	Where to look
Pages load, every /trpc/* call fails	The API has no healthy task	ECS → minitickets-dev-api → Events
/events shows an error, the rest works	The web server cannot reach http://api:4000	The /minitickets/dev/web log group
The domain does not open at all	DNS points at an old ALB	Cloudflare record vs the ALB’s DNS name

Say it in an interview

Say it like this (20-30 seconds)

MiniTickets runs in one AWS account in us-east-1. An internet-facing ALB routes /trpc/* to a Fastify API and everything else to a Next.js app; both run as one Fargate Spot task each. Only the API reaches RDS Postgres and ElastiCache Valkey in private subnets. Bookings publish to SNS, which fans out to SQS queues and two Lambda functions for email and tickets. DNS is Cloudflare, and GitHub Actions deploys with Pulumi.

Follow-ups

Why does the web app call the API instead of the database?

One rule, one place: every check (who may book, how many seats) lives in the API. If the web app read Postgres too, those rules would have to exist twice and could drift apart.

What is the single point of failure here?

Several: one api task, one web task, one Valkey node and a single-AZ database. That is a cost choice for a dev environment. Production would run at least two tasks and a Multi-AZ database.

Why are DNS and CI outside AWS?

The domain was already at Cloudflare, and the code is on GitHub. AWS trusts GitHub through OIDC, so no AWS key is stored there. The cost is that a person adds the DNS records by hand.

Advanced: Where the pieces are created

infra/index.ts calls the layers in build order: network, security groups, budget and certificate, data (Postgres, Valkey, secrets), registry, release and CI/CD roles, the always-on queues and ticket storage, then compute (cluster, IAM roles, entry, api), the two Lambda functions, the web service and finally observability. Each layer file starts with a header that lists what it NEEDS, what it CREATES and what it GIVES to later layers. The web app’s own server-side client is apps/web/src/lib/trpc/server.ts → makeServerTrpcClient.

Checkpoint

Answer these without scrolling up. If one feels hard, reread that section.

1. Which part is the only one that touches Postgres and Valkey?
2. How does the ALB decide between the web app and the API?
3. How does the web server reach the API while it renders /events?
4. Which parts live outside AWS?
5. Which switch is off in the committed config, and what does that turn off?

Redraw it from memory: the eight boxes: browser, ALB, web app, API, Postgres, Valkey, SNS to SQS, the Lambda functions

Try this: on the map, drag the stage slider to 9, then 13, then 24, and say what each stage added

Mark this page as read