A serverless Event Registration & Ticketing System on AWS — replaces Microsoft Forms + Excel with a scalable REST API. Admins, Event Organizers, and Users each get a role-scoped API; events go through an approval workflow before they're public; registration issues an organizer-provided ticket link by email.
See docs/architecture.md for the system design,
docs/data-model.md for the DynamoDB schema,
docs/api.md for the full endpoint reference,
docs/security.md for the API security controls applied,
docs/branching-strategy.md for how changes
flow into main, and docs/decisions.md for why each
major choice was made.
.
├── backend/ Lambda source (TypeScript) — handlers, services, repositories
├── infrastructure/ AWS CDK app (TypeScript) — one stack per concern
├── frontend/ Vite + React SPA, deployed to S3/CloudFront
├── docs/ architecture, data model, API reference, ADRs
├── scripts/ seed-admin.ts — creates the first Admin account
└── .github/workflows/ CI — lint, typecheck, unit tests, cdk synth on every push/PR
Backend and infrastructure are pnpm workspaces sharing one pnpm install
and one TypeScript toolchain.
- Node.js 20+ and pnpm 9+ (
corepack enableornpm install -g pnpm) - An AWS account with credentials configured (
aws configureor SSO) cdk bootstraprun once per account/region (see below)
pnpm installThis installs both workspaces (backend, infrastructure) and the root
tooling (ESLint, Prettier, ts-node for scripts/).
pnpm --filter backend build # tsc typecheck + emit
pnpm test # Jest unit tests (services, repositories, lib)
pnpm run test:coverageThe backend has no local server — Lambdas are only meaningfully runnable
once deployed (or via sam local / manual invocation with a crafted event,
not included here). Unit tests mock the AWS SDK (aws-sdk-client-mock) and
the repository layer, so business logic in services/ is fully covered
without touching real AWS resources.
Every push and every PR into main runs
.github/workflows/ci.yml: lint → typecheck
(backend + infrastructure) → unit tests with coverage → cdk synth
(validates all seven stacks build without needing AWS credentials). See
docs/branching-strategy.md for how this gates
merges to main. Check the
Actions tab
for build history and logs.
.github/workflows/deploy.yml deploys
automatically once CI finishes successfully on main (workflow_run,
so a broken build never deploys). It runs against the AWS account behind
the repo's AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY secrets, region
eu-west-1 (Ireland) by default:
deploy-infrastructure—cdk bootstrap(idempotent) thencdk deploy --all, provisioning/updating all seven stacks, and captures theApi/Frontendstack outputs.deploy-frontend— builds the Vite app withVITE_API_BASE_URLset to the just-deployed API URL, syncsfrontend/distto theFrontendstack's S3 bucket, and invalidates its CloudFront distribution.
Repo-level config (Settings → Secrets and variables → Actions):
| Name | Kind | Purpose |
|---|---|---|
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY |
secret | credentials for the deploying IAM user |
AWS_REGION |
variable | deploy region (eu-west-1) |
STAGE |
variable | CDK stage/context (dev) |
ALERT_EMAIL |
variable | Budget/CloudWatch/SES alert recipient |
MONTHLY_BUDGET_USD |
variable | Budget stack threshold |
This is a demo/capstone deployment: stage dev uses long-lived IAM user
keys rather than an OIDC role, and dev-stage resources are destroyed
(not retained) on stack deletion — see RemovalPolicy usage across
infrastructure/lib/stacks/.
# One-time per AWS account/region:
cd infrastructure
pnpm run bootstrap
# See what would change:
pnpm run diff
# Deploy everything (Database → Auth → Notifications → Api → Monitoring → Budget):
pnpm run deployBy default the app deploys to stage dev and sends Budget/CloudWatch/SES
alerts to a placeholder email baked into
infrastructure/lib/config/environment.ts.
Override both via CDK context flags:
cd infrastructure
npx cdk deploy --all \
-c stage=dev \
-c alertEmail=you@example.com \
-c monthlyBudgetUsd=10After deploying, two manual one-time steps are required because SES starts in sandbox mode:
- AWS emails a verification link to
alertEmail(the SES sender identity) — click it before any notification email will send. - While in the SES sandbox, recipient addresses must also be verified (Admins reviewing test signups, organizers/users registering with test accounts) — verify them in the SES console, or request SES production access once you're ready for real end users.
Admins are never self-service (see
docs/decisions.md)
and the Deploy workflow never creates one automatically — after a fresh
deploy, no Admin account exists until you explicitly create one.
Recommended: run the Seed Admin
GitHub Actions workflow (.github/workflows/seed-admin.yml) —
Actions → Seed Admin → Run workflow, fill in email/name/password. It
resolves UserPoolId/UsersTableName from the deployed stacks' outputs
itself and uses the same AWS credentials Deploy already has, so no local
AWS setup is needed.
Alternatively, run it locally once you have AWS CLI credentials configured
and the stack outputs (aws cloudformation describe-stacks --stack-name EventTicketing-<stage>-Api / ...-Database):
USER_POOL_ID=<UserPoolId output from the Api stack> \
USERS_TABLE_NAME=<UsersTableName output from the Database stack> \
AWS_REGION=<your region> \
pnpm run seed:admin -- --email admin@example.com --name "Site Admin" --password 'Str0ngP@ssw0rd'cd infrastructure
pnpm run destroydev-stage DynamoDB tables and the Cognito User Pool are destroyed with
the stack; prod-stage versions of both are retained on stack deletion
(see RemovalPolicy in database-stack.ts / auth-stack.ts) as a
safety net against accidental data loss.
A Vite + React SPA in frontend/ (see frontend/README.md
for local dev). It's hosted on the Frontend CDK stack (S3 + CloudFront)
and deployed by deploy.yml — see that section
for how a push to main gets it live.
Every resource is pay-per-use (Lambda, API Gateway HTTP API, DynamoDB
on-demand) with no idle compute, so a dev/demo deployment should stay well
inside AWS Free Tier. The Budget stack alerts by email at 80% actual /
100% forecasted spend against a configurable monthly threshold
(monthlyBudgetUsd, default $10) as a guardrail. The Monitoring stack
tracks API request/error counts, Lambda duration, DynamoDB throttles, and
alarms if the API error rate exceeds 5% over a 5-minute window — see
docs/architecture.md and
docs/security.md for details.