The Trinity Beast — Subscription Lifecycle

1. Overview

The Trinity Beast subscription lifecycle is managed by two Lambda functions working in tandem:

• trinity-beast-receipt — The primary handler. Processes checkout completions (subscriptions, donations, LRS add-ons, webhook subscriptions) and Stripe webhook events (tier changes, cancellations, payment failures, recoveries, refunds).
• trinity-beast-email-sender — A brainless SQS consumer that picks up pre-built emails from the queue and delivers them via SES. No logic, no DB, no Valkey — just sends.

Architecture (July 2026)

Lambda Specifications

2. Subscription Tiers

LPO — Listener Price Oracle (Pull API)

Webhook Push (Real-Time Delivery)

Webhook Associates receive prices pushed directly to their endpoints — no polling required. Every tier includes both UDP and HTTPS delivery and LRS reporting, and selects from the full prewarmed catalog across all 6 exchanges up to the tier's asset ceiling.

3. New Subscription Flow

When a customer completes a Stripe Checkout session on the subscription page, the thank-you page renders instantly with translated defaults (Phase 1), then calls the Lambda for personalization (Phase 2). The Lambda processes the session, records everything via PostgreSQL functions, and enqueues a localized receipt email.

sequenceDiagram
    participant C as Customer
    participant S as Stripe Checkout
    participant TY as Thank-You Page
    participant L as Lambda (receipt)
    participant API as LPO Admin API
    participant DB as Aurora (PG functions)
    participant EC as ElastiCache (Valkey)
    participant SQS as SQS Email Queue
    participant ES as Lambda (email-sender)
    participant SES as SES

    C->>S: Select tier & pay
    S->>TY: Redirect with session_id
    Note over TY: Phase 1: Instant translated defaults
    TY->>L: POST {session_id, type: "subscription"}
    L->>EC: Check session dedup
    EC-->>L: Not found (first call)
    L->>S: Get checkout session (expand: payment_link)
    S-->>L: Session details + Payment Link metadata
    L->>API: SELECT * FROM record_subscription(...)
    API->>DB: Execute PG function
    DB-->>API: {user_id, api_key, txn_id}
    API-->>L: Result rows
    L->>EC: Read email:frames (cached 5min)
    L->>L: Assemble localized email from frames
    L->>SQS: Enqueue pre-built email
    L->>API: /admin/invalidate-key
    L->>EC: Cache response (1hr dedup)
    L-->>TY: {success, api_key, transaction_id}
    Note over TY: Phase 2: Personalize with name/key
    SQS-->>ES: Batch pickup (3-6s)
    ES->>SES: Send email
    SES-->>C: Receipt email arrives
        

Processing Steps

1. Session dedup check — ElastiCache key receipt:session:{id} with 1-hour TTL prevents double-processing if the thank-you page calls twice (page refresh, back button).
2. Read Stripe session — Retrieves session with AddExpand("payment_link") to access Payment Link metadata. Reads: customer email, name, amount, payment status, customer ID, and metadata (tier from Payment Link metadata, locale from client_reference_id).
3. Language resolution — Priority: metadata.locale → client_reference_id (passed from cpmp-lang localStorage via the checkout URL) → Stripe session locale → fallback "en".
4. Execute PostgreSQL function — Calls record_subscription(email, name, tier, amount, stripe_customer_id, stripe_subscription_id, lang, charge_id, metadata) via the admin API. The PG function handles user upsert, API key generation with tier-specific limits, Stripe ID linking, transaction recording, and LRS auto-enable for Unlimited/Lifetime tiers — all in a single atomic operation.
5. Assemble email — Reads pre-translated frame labels from Valkey (email:frames, 5-minute local cache). Builds the complete HTML email (subject, heading, labels, values, footer) in the customer's language. Zero Bedrock calls.
6. Enqueue email — Drops the fully-assembled email JSON onto SQS (trinity-beast-email-queue). Takes ~20 ms. Falls back to direct SES if SQS fails.
7. Invalidate cache — Calls /admin/invalidate-key on both api.cpmp-site.org and lrs.cpmp-site.org so the new key is immediately active.
8. Cache response — Stores the full response in ElastiCache for 1-hour session dedup.

Thank-You Page — Two-Phase Architecture

The thank-you page does not wait for the Lambda to render content. It uses a two-phase approach:

• Phase 1 (instant, < 500 ms): Renders translated defaults immediately — heading, description, processing indicator. Loads header, footer, and i18n translations in parallel. The user sees content before the Lambda even responds.
• Phase 2 (enhancement, ~1 s): When the Lambda response arrives, the page updates with personalized data — subscriber's name, API key, receipt link. If the Lambda is slow or fails, Phase 1 content remains visible with a "check your email" fallback message.

4. LRS Add-On Activation

The LRS (Listener Reporting Service) add-on upgrades a subscriber from 10 reports/month to unlimited reports. It's a separate Stripe subscription linked to the same customer.

Activation Steps

1. Execute PostgreSQL function — Calls record_lrs_addon(email, name, amount, stripe_customer_id, stripe_subscription_id, lang, charge_id) via the admin API. The PG function finds the active API key by email, validates eligibility, sets lrs_enabled = true, links the LRS subscription ID, and records the transaction — all atomically.
2. Assemble and enqueue email — Builds the LRS confirmation email from pre-translated Valkey frames in the subscriber's language, then enqueues to SQS for async delivery.
3. Invalidate cache — Calls /admin/invalidate-key on both api.cpmp-site.org and lrs.cpmp-site.org so the LRS upgrade takes effect immediately.

5. Donation Processing

Donations follow a focused flow — no API key generation, no tier assignment. The Lambda records the donation via a PostgreSQL function and sends a personalized, localized receipt email with impact-specific messaging.

Processing Steps

1. Read Stripe session — Expands Payment Link to read impact_type from Payment Link metadata (e.g., freedom, water, wheelchair, medical, bible, audio_bible, provisions, education, sewing, general).
2. Execute PostgreSQL function — Calls record_donation(email, name, amount, impact_type, lang, charge_id, stripe_customer_id) via the admin API. The PG function upserts the user, records the transaction with impact_type, and returns the transaction ID.
3. Load impact message — Reads the localized impact message from Valkey (impact:messages key, 5-minute local cache). Each of the 10 impact types has a unique, pre-translated message in all 12 languages describing what the donation specifically funds.
4. Assemble and enqueue email — Builds the donation receipt from Valkey email frames + the impact-specific message. The email tells the donor exactly what their gift provides (e.g., "Your $510 gift provides clean water for 3 families through a well installation in rural Punjab").

Impact Types

Donation Refunds

When a donation charge is refunded, the Lambda identifies it as a donation (no API key found for the customer) and calls record_donation_refund(charge_id, refund_amount, refund_id). A localized refund confirmation email is sent to the donor. No API key revocation occurs (donors don't have API keys).

6. Stripe Webhook Events

Stripe sends webhook events to https://receipt.cpmp-site.org/webhook (Route 53 → API Gateway → Lambda). Events are verified using the Stripe webhook signing secret and deduplicated by event ID in ElastiCache.

flowchart TD
    S[Stripe Event] --> V{Verify Signature}
    V -->|Invalid| R400[400 Invalid]
    V -->|Valid| D{Duplicate Check}
    D -->|Already processed| R200D[200 Already processed]
    D -->|New event| Route{Event Type}
    Route -->|customer.subscription.updated| SU[handleSubscriptionUpdated]
    Route -->|customer.subscription.deleted| SD[handleSubscriptionDeleted]
    Route -->|invoice.payment_failed| PF[handlePaymentFailed]
    Route -->|invoice.paid| PR[handlePaymentRecovered]
    Route -->|charge.refunded| RF[handleChargeRefunded]
    Route -->|Other| Skip[Log & skip]
    SU --> Mark[Mark processed in ElastiCache]
    SD --> Mark
    PF --> Mark
    PR --> Mark
    RF --> Mark
    Mark --> R200[200 OK]

    style S fill:#1e3a5f,stroke:#0f172a,color:#ffffff,font-weight:bold
    style V fill:#7c3aed,stroke:#0f172a,color:#ffffff,font-weight:bold
    style D fill:#7c3aed,stroke:#0f172a,color:#ffffff,font-weight:bold
    style Route fill:#b45309,stroke:#0f172a,color:#ffffff,font-weight:bold
    style SU fill:#065f46,stroke:#0f172a,color:#ffffff,font-weight:bold
    style SD fill:#991b1b,stroke:#0f172a,color:#ffffff,font-weight:bold
    style PF fill:#991b1b,stroke:#0f172a,color:#ffffff,font-weight:bold
    style PR fill:#065f46,stroke:#0f172a,color:#ffffff,font-weight:bold
    style RF fill:#991b1b,stroke:#0f172a,color:#ffffff,font-weight:bold
    style Skip fill:#475569,stroke:#0f172a,color:#ffffff
    style Mark fill:#1e3a5f,stroke:#0f172a,color:#ffffff,font-weight:bold
    style R200 fill:#065f46,stroke:#0f172a,color:#ffffff,font-weight:bold
    style R200D fill:#475569,stroke:#0f172a,color:#ffffff
    style R400 fill:#991b1b,stroke:#0f172a,color:#ffffff,font-weight:bold
        

7. Tier Upgrades & Downgrades

Why We Built Our Own Orchestration

The Three Upgrade Paths

All plan changes are initiated from the Account Dashboard (/dashboard → Change Plan panel). The system determines which path to take based on the customer's current state:

Path 1: Free → Paid (Checkout Session)

Free-tier users have no Stripe subscription to update. The dashboard detects stripe_subscription_id = NULL and creates a new Stripe Checkout Session in subscription mode:

1. Customer clicks "Upgrade" on the Change Plan panel.
2. Dashboard calls POST /dashboard/api/change-plan with {"target_tier": "pro"}.
3. Handler detects no existing subscription → calls createUpgradeCheckout().
4. Returns a checkout_url — the frontend redirects the browser to Stripe.
5. Customer pays → Stripe redirects to /dashboard?upgrade=success.
6. Concurrently, the thank-you page calls the receipt Lambda (same as a new subscription).
7. Receipt Lambda: creates key with new tier limits, records transaction, sends receipt email, invalidates cache.

Path 2: Paid → Paid (Subscription Update)

When a subscriber already has a Stripe subscription (any paid tier), the system uses the Stripe Subscription Update API for seamless proration:

1. Customer selects a new tier on the Change Plan panel.
2. Dashboard calls POST /dashboard/api/change-plan with the target tier.
3. Handler validates:
   • Target tier exists in tier_catalog with a valid stripe_price_id
   • Not the same tier they're already on
   • Product family matches (cannot switch between REST and Webhook)
4. Handler retrieves the subscription from Stripe, extracts the subscription item ID.
5. Calls PATCH /v1/subscriptions/{id} with the new price, tier metadata, and proration_behavior: create_prorations.
6. Stripe fires customer.subscription.updated → receipt Lambda applies the new tier limits in Aurora.

Path 3: Any → Lifetime (One-Time Purchase with Credit)

Lifetime is a $3,000 one-time purchase that permanently unlocks unlimited access. The system credits the customer's current tier monthly price as a thank-you for their existing commitment:

1. Customer clicks "Go Lifetime" on the Change Plan panel (gold card).
2. Dashboard calls GET /dashboard/api/lifetime-quote to display the credit and net amount.
3. Credit = current tier's price_cents from tier_catalog (e.g., Enterprise = $100 credit).
4. Net = $3,000 − credit (e.g., $3,000 − $100 = $2,900).
5. Customer confirms → dashboard calls POST /dashboard/api/go-lifetime.
6. Handler creates a Stripe Checkout Session in payment mode (one-time) with unit_amount = net_cents.
7. Metadata carries: tier=lifetime, upgrade_from=enterprise, credit_cents=10000, source=dashboard-go-lifetime.
8. Customer pays → receipt Lambda handles the rest: creates Lifetime key (unlimited, no rate limiting), cancels existing subscription in Stripe, revokes old key, sends receipt email.
9. If the account also holds a separately-billed LRS add-on subscription (stripe_lrs_subscription_id), that subscription is cancelled too — Lifetime includes LRS free, so the addon becomes redundant the moment Lifetime is active.

Cleaning Up a Redundant LRS Add-On on Upgrade

Setting lrs_enabled = true by tier is not the same as stopping the bill for a separate addon subscription that the tier just made unnecessary. Both this Go Lifetime path and the ordinary Change Plan path (upgrading to Unlimited) call cancelSubscriptionWithProratedRefund() (trinity-beast-receipt-lambda/cmd/handler/main.go) against StripeLRSSubscriptionID whenever the destination tier already includes LRS. This does two things, not one:

1. Cancels the Stripe subscription immediately — not at period end, since the new tier already covers LRS from the moment it takes effect.
2. Refunds the unused portion of the customer's most recent LRS-addon charge, computed from that subscription item's own current_period_start/current_period_end — a clean cancellation still leaves the customer having pre-paid for time on the addon they will never use, and that time is owed back.

The same function is applied to the main plan's own subscription in the Go Lifetime path — a bare cancel with no refund credit only ever accounted for the current period's discount against the $3,000 price, not for unused time already paid for within that period.

Found live, not in review. This gap surfaced on 2026-08-04 when Cory upgraded his own account to Lifetime and found his separately-billed LRS addon subscription still active and billing afterward. The standing rule this establishes: any handler that flips an entitlement flag to true by tier, where a separately-billed subscription for that same capability might already exist, must also resolve that subscription — cancel it, and refund unused time. Setting the flag alone leaves a redundant charge running silently.

Product Family Enforcement

A customer cannot switch between product lines through the plan change flow:

• LPO ↔ LPO: Allowed (Free → Pro → Enterprise → Unlimited → Lifetime)
• Webhook ↔ Webhook: Allowed (Starter → Standard → Professional → Enterprise)
• LPO → Webhook or Webhook → LPO: Blocked with HTTP 400 — "Cannot switch between REST and Webhook products."

The handler detects webhook tiers by the webhook_ prefix on tier names. A customer who wants both products creates a separate subscription for each — they appear as separate product cards on the dashboard, billed independently.

The Checkout Guard (Duplicate Prevention)

Existing subscribers who visit the public subscription page (subscribe-listener.html or webhook.html) must not create duplicate subscriptions. A three-layer defense prevents this:

Webhook Processing (customer.subscription.updated)

When Stripe fires a customer.subscription.updated event (from a dashboard-initiated plan change or from the Stripe Customer Portal), the receipt Lambda processes it:

1. Reads metadata.tier from the subscription — this is the new tier (set by the dashboard handler when it updated the subscription).
2. Looks up the customer in Aurora by stripe_customer_id.
3. If the new tier differs from the current tier in Aurora:
   • LPO tiers: Applies new rate limits (query_limit, rate_limit_qps, burst_limit, minimum_wait_seconds) from rate_limit_template.
   • Webhook tiers: Updates webhook_subscriptions with new interval_seconds and max_assets.
4. Handles LRS transitions:
   • Upgrading TO Unlimited/Lifetime → sets lrs_enabled = true
   • Downgrading FROM Unlimited/Lifetime → sets lrs_enabled = false (unless they have a separate LRS add-on: stripe_lrs_subscription_id != '')
5. Invalidates the API key cache across all containers.
6. Sends a plan switch confirmation email.

If metadata.tier is unchanged but the subscription status changed (e.g., past_due → active), the handler updates only subscription_status.

Plan Switch Confirmation Email

Every tier change (upgrade or downgrade) sends a branded dark-theme confirmation email to the subscriber. The email includes:

• Old and new plan names with effective date
• Proration note (automatic, no subscriber action needed)
• A comparison table showing old vs new limits side-by-side: price, LPO queries/month, LRS reports/month, and rate limiting (if changed)
• Link to the account dashboard for self-service management

The comparison data is read from tier_catalog in Aurora (via admin API) at send time. Improvements in the new tier are highlighted in green. The email is fully assembled from pre-translated frame labels in the subscriber's preferred_lang — zero Bedrock cost, instant assembly, deterministic output. Enqueued to SQS for async delivery.

Non-Switchable Tiers

Translation Key Isolation

Every query that resolves the customer's "current" LPO or Webhook subscription explicitly excludes translation keys:

AND COALESCE(k.service_type, 'prices') != 'translation'
AND COALESCE(k.is_translation, false) = false

Translation is a completely independent product line with its own Stripe customer, its own API key, and its own billing lifecycle. It never participates in LPO/Webhook plan switching, credit calculations, or proration. This separation is enforced in every handler: ChangePlanHandler, AvailablePlansHandler, LifetimeQuoteHandler, GoLifetimeHandler, and resolveStripeCustomerID.

8. Cancellation Flow

When a subscription is cancelled (via Customer Portal or Stripe dashboard), Stripe sends a customer.subscription.deleted event.

LPO Subscription Cancelled

1. Tier is set to free with free-tier limits.
2. subscription_status set to canceled.
3. lrs_enabled set to false.
4. stripe_subscription_id and stripe_lrs_subscription_id cleared.
5. If an LRS add-on subscription exists, it is automatically cancelled in Stripe via the API.
6. API key cache invalidated on all containers.

LRS Add-On Cancelled (separately)

1. Identified by matching subscription.id to stripe_lrs_subscription_id.
2. lrs_enabled set to false.
3. stripe_lrs_subscription_id cleared.
4. The main LPO subscription remains active and unaffected.
5. API key cache invalidated.

8.1 Admin-Initiated Tier Change (Support Operations)

Not all tier transitions are self-service. Some require admin intervention — typically when a customer contacts support to cancel, request a refund, or when the admin needs to correct a tier that was set incorrectly.

When This Path Is Used

• Lifetime cancellation: Customer contacts support requesting to cancel their $3,000 one-time purchase. There is no Stripe subscription to cancel — only a charge to refund and a tier to reset.
• Support-initiated downgrade: Customer requests cancellation via support ticket (Rhema categorizes as billing). Admin reviews, processes refund if appropriate, and resets tier.
• Tier correction: A race condition or bug set the wrong tier, and the admin needs to restore the correct state with proper rate limits.
• Admin testing: Cycling through tiers to test the subscription flow end-to-end.

The Process

# Full command
bash scripts/kcc.sh admin-tier-reset <email> <target_tier> [--refund] [--refund-amount N.NN] [--key-id uuid]

# Example: Lifetime cancellation with full refund
bash scripts/kcc.sh admin-tier-reset customer@email.com free --refund --key-id bb1fdafb-...

The command performs these steps in order:

1. Looks up all non-revoked, non-translation keys by email.
2. Displays current state vs target state for confirmation.
3. If --refund: Issues Stripe refund of the most recent charge (via POST /admin/refund). The charge.refunded webhook event fires, and the receipt Lambda sends the customer a branded refund confirmation email automatically.
4. Records the tier transition in tier_change_history (source: admin-tier-reset).
5. Updates the key with rate_limit_template values for the target tier — query_limit, rate_limit_qps, burst_limit, burst_tokens, minimum_wait_seconds.
6. Sets appropriate flags: is_rate_limited, is_billing_exempt, subscription_status.
7. Resets current_usage to 0 (fresh start on new tier).
8. Invalidates the API key cache on all ECS nodes (immediate effect).

What Is Preserved

• stripe_customer_id — Dashboard login and future purchases continue to work.
• The API key string — No revoke/recreate. The customer's integrations keep working (with new rate limits).
• user_id — Account association stays intact.
• All historical data — Usage logs, transactions, giving history, support tickets.

Refund vs Subscription Cancellation

Audit Trail

Every admin-initiated tier change is fully auditable:

• tier_change_history — Records previous_tier, new_tier, source = 'admin-tier-reset', and timestamp.
• transactions — Records refund with type = 'admin_refund' and negative amount.
• Stripe refund metadata — Includes initiated_by: admin, key_id, and reason.

-- Query the admin tier change history for a customer
SELECT previous_tier, new_tier, source, changed_at, notes
FROM tier_change_history
WHERE api_key_id = '<uuid>'
ORDER BY changed_at DESC;

9. Payment Failure & Grace Period

stateDiagram-v2
    [*] --> Active: Subscription created
    Active --> PastDue: invoice.payment_failed
    PastDue --> Active: invoice.paid (recovered)
    PastDue --> Blocked: Grace period expired
    Blocked --> Active: invoice.paid (recovered)
    Active --> Canceled: customer.subscription.deleted
    PastDue --> Canceled: customer.subscription.deleted
    Canceled --> [*]: Downgraded to free

    classDef active fill:#065f46,stroke:#0f172a,color:#ffffff,font-weight:bold
    classDef pastdue fill:#b45309,stroke:#0f172a,color:#ffffff,font-weight:bold
    classDef blocked fill:#991b1b,stroke:#0f172a,color:#ffffff,font-weight:bold
    classDef canceled fill:#475569,stroke:#0f172a,color:#ffffff,font-weight:bold

    class Active active
    class PastDue pastdue
    class Blocked blocked
    class Canceled canceled
        

Payment Failure (invoice.payment_failed)

• subscription_status set to past_due.
• payment_failed_at set to current timestamp (only on first failure — uses COALESCE to preserve the original date).
• API key cache invalidated.

Grace Period

The LPO server checks the grace period on every price request for past_due subscribers:

• Grace period: payment_grace_period_days application parameter (default: 7 days).
• If time.Since(payment_failed_at) < grace_period, the subscriber continues to have full access.
• If the grace period expires, the server returns HTTP 402 (Payment Required) with a message to update their payment method.

Payment Recovery (invoice.paid)

• Only acts if current status is past_due.
• subscription_status restored to active.
• payment_failed_at cleared (set to NULL).
• API key cache invalidated — full access restored immediately.

10. Refund Processing

When a charge is refunded via the Stripe Dashboard or mobile app, Stripe sends a charge.refunded webhook event. The Lambda handles two scenarios: subscription refunds (API key revocation) and donation refunds (record-only).

Subscription Refund Flow

1. Stripe fires charge.refunded — triggered when you process a refund in the Stripe Dashboard or mobile app.
2. Look up customer — Uses the charge's customer ID to find the API key via lookupByStripeCustomer (admin API query).
3. Execute PostgreSQL function — Calls record_refund(api_key_id, charge_id, refund_amount, refund_id, customer_id, tier) via the admin API. The PG function revokes the API key, sets status to 'refunded', and records the refund transaction atomically.
4. Send refund email — Assembles a localized refund confirmation from Valkey frames (includes tier, refund amount, refund ID, API key) and enqueues to SQS.
5. Invalidate cache — Calls invalidateAPIKeyCache on all LPO/LRS servers so the revoked key stops working immediately.

Donation Refund Flow

1. No API key found — When lookupByStripeCustomer returns no result (the customer is a donor, not a subscriber).
2. Execute PostgreSQL function — Calls record_donation_refund(charge_id, refund_amount, refund_id) via the admin API. Records the refund against the original donation transaction.
3. Send refund email — Assembles a localized donation refund confirmation from Valkey frames and enqueues to SQS.

11. Cache Invalidation

Every lifecycle event that changes API key data triggers cache invalidation to ensure changes take effect immediately across all containers.

12. Email Pipeline

Every email in the subscription lifecycle is assembled from pre-translated frames and delivered asynchronously via SQS. Zero Bedrock calls, zero SES waits in the receipt Lambda's response path.

Architecture

Pre-Translated Frames (Valkey email:frames)

A single JSON blob in Valkey containing 12 languages × 45 keys. Every email label (subject, heading, subheading, field labels, footer, link text) is pre-translated and stored. The receipt Lambda reads this on startup (5-minute local cache) and assembles emails by combining frame labels with dynamic values (name, amount, API key, date).

Impact Messages (Valkey impact:messages)

A separate Valkey key containing 12 languages × 10 impact types. Each impact type has a unique, descriptive message explaining what the donor's gift specifically provides. Source of truth: s3://trinity-beast-website-east2/data/impact-messages.json.

SQS Message Format

The receipt Lambda enqueues a complete, ready-to-send message. The email-sender Lambda does zero processing — it just delivers what it receives:

{
  "to": "subscriber@example.com",
  "subject": "サブスクリプション確認",
  "html_body": "<html>...complete email...</html>",
  "lang": "ja",
  "timestamp": "2026-07-24T09:15:00Z"
}

Data Sources — Nightly Refresh

Both Valkey keys are refreshed nightly by the BeastReconciler sync job:

• email:frames ← s3://trinity-beast-website-east2/data/email-frames.json (via syncEmailFrames())
• impact:messages ← s3://trinity-beast-website-east2/data/impact-messages.json (via syncImpactMessages())

Edit the JSON on S3 → push to Valkey manually (or wait for nightly sync) → live without redeploy.

Fallback

If SQS itself is unavailable, the receipt Lambda falls back to direct SES delivery (sendEmailDirect). The customer always receives their receipt — the pipeline is belt and suspenders.

Server-Originated Mail — Valkey email:tpl:*

Not every lifecycle email originates from the receipt Lambda. Refund confirmations issued through /admin/refund, reactivation notices, and dashboard magic links are built by the LPO server, which uses a separate template registry: six per-template Valkey hashes under email:tpl:*, read through a shared EmailLoader with a 5-minute in-memory cache and English fallback.

Both stores are refreshed nightly from S3 by the BeastReconciler and can be pushed on demand with bash scripts/kcc.sh push-email-templates. Copy edits go live within five minutes without a redeploy. Full detail lives in the Multi-Lingual Communications guide.

13. PostgreSQL Functions

All database writes from the receipt Lambda go through dedicated PostgreSQL functions. Each function encapsulates a complete business operation (user upsert + key creation + transaction recording) in a single atomic call. The Lambda calls these via adminQuery(ctx, "SELECT * FROM function_name($1,$2,...)") over the LPO admin API.

14. Database Schema

api_keys — Subscription Lifecycle Columns

Indexes for Webhook Lookups

14.1 Nullable Columns — Scan Safety

Several api_keys columns are legitimately NULL for a freshly created key: name when the caller supplied no label, and last_used and last_success until the key makes its first request. Go's lib/pq driver cannot scan a SQL NULL into a non-pointer string or time.Time. The scan returns an error, and because API key validation treats any lookup error as a validation failure, a perfectly valid key returns 401 Invalid API key.

The Rule

Every nullable column read on the API key validation path must be made scan-safe at one of two levels:

Timestamps use sql.NullTime rather than COALESCE because the distinction matters downstream: a key that has never been used is semantically different from one used at the Unix epoch. The Valid flag preserves that difference; a COALESCE default would erase it.

// Nullable timestamps scanned safely, then hydrated
var lastUsed, lastSuccess sql.NullTime

err := row.Scan(
    &data.ID, &data.UserID, &data.Name,        // Name is COALESCE'd in SQL
    &data.Tier, &data.QueryLimit, &data.CurrentUsage,
    &lastUsed, &data.CreatedAt, &data.Revoked,
    // ...
    &lastSuccess,
)

if lastUsed.Valid {
    data.LastUsed = lastUsed.Time
}
if lastSuccess.Valid {
    data.LastSuccess = lastSuccess.Time
}

The same discipline applies when adding any new nullable column to api_keys. If the validation query selects it, wrap it or scan it as a null type before deploying — otherwise every key created after the migration authenticates correctly until the column is populated, and fails afterward.

15. Stripe Customer Portal

Each subscription receipt email includes a link to the Stripe Customer Portal, generated dynamically by the Lambda using billingportal.Session. The portal allows subscribers to:

• Update payment method
• View billing history and download invoices
• Change subscription plan (upgrade/downgrade)
• Cancel subscription

16. Account Dashboard

Every customer has access to a unified Account Dashboard at https://api.cpmp-site.org/dashboard. The dashboard is a single-page application with a flat sidebar — every customer sees the same panels regardless of what products they subscribe to. Empty states with CTAs enable product discovery through visibility.

Access & Authentication

• Magic Link: Passwordless login via email. Customer enters their email, receives a one-time link, clicks it to authenticate. No passwords stored.
• Session Token: Stored in localStorage (cpmp_site.token). Validated on every page load against the server.
• Multi-Product Model: One email = one account. The /dashboard/api/account endpoint returns a products array classifying all the customer's API keys by service type (LPO, Translation, Webhook, Partner).

Sidebar Panels (Flat — No Tabs)

• Overview: Multi-product summary with subtitle listing active products (e.g., "Pro API · Translation · Donor"). Product cards with tier badges, stats, and action buttons.
• Account: Profile, Billing (embedded Stripe portal), Change Plan, Support — universal items every customer needs.
• Giving: Complete donation history with impact types, amounts, dates, receipt links. Impact breakdown cards showing aggregate giving by category.
• API Access: API key reveal, live 30-day usage chart, rate limit info, code examples.
• Translation: Submit jobs, select AI agent (6 available: Qwen3 235B, Mistral Large, DeepSeek R1, Haiku, Sonnet, Opus), per-pair chip grouping with document headers, real-time progress, history, spend tracking.
• Webhook: Configure push delivery endpoints, select assets, set intervals, test delivery.
• Partner: Partner key management, PrivateLink status.
• Admin: Analytics + Person View (gated — operational tools, not products).

Empty States as Invitations

Panels for inactive products show friendly descriptions with secondary CTA buttons linking to the relevant product page. This replaces the old "No API key" error messages. Every product is always visible — the sidebar is a discovery surface, not a gated fortress.