Skip to main content

Infrastructure and Delivery

Alternun provisions infrastructure from the monorepo through packages/infra.

The project uses:

  • SST as the app wrapper and deployment entrypoint
  • Pulumi AWS resources inside the infra modules
  • CodeBuild and CodePipeline for managed delivery flows
  • Route53 and ACM for DNS and certificates

Stage Model​

The platform is split into several deployment families.

Public AIRS stages​

  • production
  • dev
  • mobile

Default public domains:

  • airs.alternun.co
  • testnet.airs.alternun.co
  • preview.airs.alternun.co

Backend and internal stages​

  • dashboard-dev
  • dashboard-prod
  • admin-dev
  • admin-prod
  • identity-dev
  • identity-prod

These let the team deploy internal surfaces independently or as a combined release unit.

Retired stage aliases:

  • api-dev, api-prod
  • backend-dev, backend-prod
  • backend-api-dev, backend-api-prod

Those old backend-only aliases normalize to the dashboard stacks in local tooling and must not be used as standalone live deploy targets.

Domain Model​

The current domain family separates public product surfaces from marketing surfaces.

Notable detail:

  • the public marketing/corporate site stays on alternun.io
  • application and identity surfaces use the alternun.co domain family

What The Infra Package Provisions​

Public app delivery​

For AIRS, the infra package provisions:

  • static site delivery for the Expo web build
  • asset buckets
  • CloudFront-backed distribution path
  • stage-aware redirects
  • release-update manifest and worker assets generated from the current package version

Frontend deploys also depend on stage-scoped public auth config coming from AWS SSM Parameter Store. For the public AIRS bundles, EXPO_PUBLIC_AUTH_EXECUTION_PROVIDER and EXPO_PUBLIC_BETTER_AUTH_URL must be set in SSM for each frontend stage, especially dev/testnet and production, so the exported bundle stays aligned with the owning API/auth runtime instead of relying on inferred defaults.

For EXPO_PUBLIC_BETTER_AUTH_URL, keep the value browser-facing on the stage API origin root such as https://testnet.api.alternun.co or https://api.alternun.co; the client and proxy layers append /auth internally.

Backend API delivery​

For the custom API, the infra package provisions:

  • Lambda
  • API Gateway HTTP API
  • CloudWatch logging
  • custom domain mapping
  • ACM and DNS validation when needed

Database changes for the live backend are handled separately from stack deploys:

  • preview with scripts/sync-db-migrations.sh <stage> --dry-run
  • apply exactly one reviewed migration file at a time with --file
  • use --force-prod for any production migration apply
  • do not batch-apply the full backlog unless you are doing a deliberate recovery run

Admin delivery​

For the admin console, the infra package provisions:

  • static site hosting
  • CDN distribution
  • custom domains and certificates

Identity delivery​

For Authentik, the infra package provisions:

  • VPC and security groups
  • EC2 runtime host
  • optional RDS PostgreSQL
  • Secrets Manager payloads
  • Route53 records
  • ACME or ACM-backed TLS paths depending on stage

Pipeline Model​

The default pipeline catalog includes:

  • production
  • dev
  • identity-dev
  • identity-prod
  • dashboard-dev
  • dashboard-prod

The default branch map in the infra config sends dev-oriented stacks to develop and production-oriented stacks to master.

Current Testnet Ownership​

The live testnet rollout is intentionally split:

  • dev owns testnet.airs.alternun.co
  • dashboard-dev owns testnet.api.alternun.co and testnet.admin.alternun.co
  • identity-dev owns testnet.sso.alternun.co

This is the canonical ownership model. Retired backend-only stage aliases must not be used for live testnet API/admin deploys.

Delivery Flow​

Why There Are Combined And Dedicated Stacks​

The infra system supports both:

  • combined dashboard stacks for admin and API together
  • dedicated stacks for admin-only and identity-only operations

That design is pragmatic:

  • it keeps normal releases simpler
  • it still allows controlled component-specific deployment paths where they are intentionally supported
  • it reduces accidental deletion risk by putting safety guards into the infra logic

The former backend-only api-* and backend-* stages were retired after they created duplicate public testnet resources and routing drift.

Practical Source Of Truth​

If you want the live infra definitions, read these files in this order:

  1. packages/infra/infra.config.ts
  2. packages/infra/config/infrastructure-specs.ts
  3. packages/infra/modules/*
  4. packages/infra/INFRASTRUCTURE_SPECS.md

The public docs here summarize those sources for human understanding, but the code remains the actual source of truth.