Aldero Architecture

Overview

Aldero is a multi-tenant backend platform with three core services:

┌─────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Auth        │     │  Billing         │     │  Notifications   │
│  *.aldero.io │     │  *.billing.      │     │  *.ntf.          │
│              │     │    aldero.io     │     │    aldero.io     │
├─────────────┤     ├──────────────────┤     ├─────────────────┤
│ Users        │     │ Entitlements     │     │ Templates        │
│ OAuth2/OIDC  │     │ Products         │     │ Push (APNS/FCM)  │
│ MFA          │     │ Credits          │     │ Email (SES)      │
│ Sessions     │     │ Subscriptions    │     │ SMS              │
│ Webhooks     │     │ RevenueCat       │     │ Custom Domains   │
│ Passkeys     │     │ Stripe           │     │ Device Tokens    │
└──────┬───────┘     └────────┬─────────┘     └────────┬────────┘
       │                      │                         │
       └──────────────────────┼─────────────────────────┘
                              │
                    ┌─────────┴─────────┐
                    │  Dashboard        │
                    │  dashboard.       │
                    │    aldero.io      │
                    └───────────────────┘

Multi-Tenancy

Each tenant gets a subdomain per service:

Service	Production	Sandbox
Auth	`faxdash.aldero.io`	`faxdash-sandbox.aldero.io`
Billing	`faxdash.billing.aldero.io`	`faxdash-sandbox.billing.aldero.io`
Notifications	`faxdash.ntf.aldero.io`	`faxdash-sandbox.ntf.aldero.io`

Tenant resolution: Host header → extract subdomain → resolve tenant config from DynamoDB.

Authentication Model

Three-tier auth on billing and notification services:

Master admin key — stored in AWS Secrets Manager, full access
Per-tenant API keys — prefixed (bil_, ntf_), scoped to tenant + environment
JWT — validated against per-tenant JWKS ({slug}.aldero.io/.well-known/jwks.json)

Infrastructure

Component	Technology
Runtime	Node.js 24 (Lambda ARM64)
Framework	Hono
Database	DynamoDB (per-service tables)
Email	Amazon SES
Push	APNS + FCM
IaC	Terraform
CDN	CloudFront
DNS	Route 53
Secrets	AWS Secrets Manager

Data Flow: Purchase → Entitlement

User taps "Buy" in app
  → Apple/Google processes payment
  → RevenueCat receives transaction
  → RevenueCat sends webhook to billing service
  → Billing service:
      1. Resolves tenant from subdomain
      2. Verifies webhook secret
      3. Looks up product in products table
      4. Creates entitlement record with features + grants
  → App queries GET /v1/entitlements/:userId
  → Billing service aggregates active entitlements
  → Returns features, grants, subscriptions, consumables
  → App checks features and displays content accordingly

Environment Isolation

Auth: Separate user pools per environment (different signing keys, different users)
Billing: Shared tenant, entitlements tagged by environment
Notifications: Shared tenant, device tokens and logs scoped by environment
Products/Templates: Shared across environments

Services at a Glance

Auth Service

Multi-tenant OAuth2/OIDC provider
Per-tenant signing keys (RS256)
Social login (Google, GitHub, Apple)
MFA (TOTP, email)
Passkeys (WebAuthn)
Token refresh with family-based theft detection

Billing Service

Entitlement system with features + generic grants
Product catalog per tenant
RevenueCat + Stripe webhook handlers
Credit system (balance + transaction log)
Subscription management (upgrades/downgrades)
Promotion/promo code system
RevenueCat sync for recovery

Notification Service

Multi-channel: email (SES), push (APNS/FCM), SMS
Template system with variable substitution
Custom domain support (DKIM verification)
Device token management
Delivery tracking (queued → sent → delivered → opened)
SQS-based async dispatch

Getting Started Flutter (Dart SDK)