The Trinity Beast — Unified Messaging Envelope (UME)

Executive Summary

The Unified Messaging Envelope (UME) is the architectural pattern that wraps every outbound communication from The Trinity Beast — API responses, error messages, emails, webhook deliveries, and UDP datagrams. It guarantees that every response self-identifies with its service, container, region, and timestamp. Two shared Go functions (WriteJSON and WriteError) enforce this pattern across 40+ endpoints, making consistency automatic rather than aspirational. The result: full observability, instant debuggability, and zero-effort extensibility for every new feature added to the system.

1. Design Philosophy
1b. Structural Consistency — The No-omitempty Rule
2. Envelope Anatomy
3. Success Envelope — Live Examples
4. Error Envelope — Live Examples
4b. Multi-Lingual Messaging — How It Works
5. Email Envelope — Outbound Communications
6. Webhook Push Envelope
7. The Identity Thread — How Email Unifies the Islands
8. Extensibility — Adding New Endpoints
9. Architecture — The Envelope Engulfs Everything
10. Complete Endpoint Catalog with Envelope Examples

List of Diagrams

Diagram 7.1 — Identity Thread Across All Tables
Diagram 9.1 — Unified Messaging Envelope Architecture

1. Design Philosophy

Every response tells the full story. Whether it's a price query, a support ticket submission, a health check, or a 404 error — the consumer always knows: what service handled it, which container processed it, what region it ran in, when it happened, and what the result was. No guessing. No ambiguity. No silent failures.

The Unified Messaging Envelope (UME) is not a table in the database. It is not a library you import. It is the architectural pattern that every outbound communication from The Trinity Beast follows — whether that communication is an HTTP response, an email, a UDP datagram, or a webhook push.

The envelope provides:

Observability — Every response identifies itself: service, node, region, timestamp
Consistency — Success and error responses follow the same structure across all 40+ endpoints
Debuggability — A developer can look at any response and know exactly where it came from and when
Extensibility — New endpoints inherit the envelope automatically through the shared WriteJSON and WriteError functions
Multi-lingual — The envelope carries two language preferences: preferred_lang for communications (emails, newsletters) and api_lang for messaging (API responses, error messages). Every response declares its language via the language field. A developer in Tokyo can receive API errors in Japanese while their billing emails arrive in English — or vice versa.

1b. Structural Consistency — The No-omitempty Rule

Architectural mandate: No omitempty JSON struct tag exists anywhere in this codebase. Not on the envelope. Not on nested data structs. Not on sub-fields. Not on "optional" fields. The tag is banned. This is not a guideline — it is a structural decision that eliminates an entire class of consumer bugs.

Why This Matters

When fields conditionally appear or disappear based on their value, every consumer must write defensive code: "Does this field exist? Is it null? Is it missing entirely? Is it an empty string or was it omitted?" This creates a combinatorial explosion of edge cases that grows with every new field added to the system.

UME eliminates this entirely. The shape of the response IS the contract. If a field is defined in the struct, it is present in every response. Period. Consumers parse with confidence — no nil checks, no "field exists?" guards, no version-dependent parsing logic.

The Rules

Rule	Rationale
No `omitempty` on any JSON struct tag	Fields are always present. Zero values are valid data.
Empty strings serialize as `""`	A string field with no value is `""`, not absent.
Zero numbers serialize as `0`	A numeric field with no value is `0`, not absent.
Empty slices serialize as `[]`	Initialize with `make([]T, 0)`. Never `null`.
Empty maps serialize as `{}`	Initialize with `make(map[K]V)`. Never `null`.
Booleans serialize as `false`	A boolean field is always `true` or `false`, never absent.
`data` is `null` on errors	The field is present (not omitted). `null` means "no payload" — distinct from missing.
`error` is `""` on success	The field is present (not omitted). Empty string means "no error" — distinct from missing.

Consistency Across All Response Types

Whether the response is a success, an error, an informational message, or a caution — the envelope shape is identical. All 12 fields are present in every response. Consumers never branch on response type to determine which fields exist. They parse the same struct every time.

// Go struct — no omitempty anywhere
type APIResponse struct {
    Status          string      `json:"status"`
    StatusCode      int         `json:"status_code"`
    Endpoint        string      `json:"endpoint"`
    ClusterNode     string      `json:"cluster_node"`
    Region          string      `json:"region"`
    Language        string      `json:"language"`
    APIKeyID        string      `json:"api_key_id"`
    IPAddress       string      `json:"ip_address"`
    AgentProfileARN string      `json:"agent_profile_arn"`
    Timestamp       string      `json:"timestamp"`
    Data            interface{} `json:"data"`
    Error           string      `json:"error"`
}

This struct produces the same 12 keys in every JSON response. On success, error is "". On error, data is null. Both fields are always present. No conditional coding. No exceptions.

The 12 Fields Tell the Whole Story

Who called — api_key_id (the caller's API key, "" for unauthenticated paths)
From where — ip_address (inbound: client IP. Outbound: our container's ENI IP — see Inbound vs Outbound below)
Who answered — agent_profile_arn (the addressable identity of the actor that produced this response — never empty)
Where they live — cluster_node + region
What was asked, what happened — endpoint + status + status_code + error
Content, payload, time — language + data + timestamp

Inbound vs Outbound IP Semantics

ip_address means different things depending on direction. The field shape is identical; the identity is contextually correct.

Inbound (TCP HTTP, UDP, partner WebSocket subscribe responses): the client's source IP we observed.
Outbound (webhook delivery, partner WS broadcast): our container's ENI private IP — the Beast machine that pushed the update. Each Fargate task has its own ENI; partners can use this to identify which container served them when debugging timing or missed deliveries. New container = new IP, surfaced automatically.

The `agent_profile_arn` Field

Every response is signed by an actor. Format: arn:tbi:{region}:{account}:agent-profile/{name}/{version}. The arn:tbi: partition is our own — we mint these ARNs. AgentCore-backed agents (when AI agent profiles are migrated to real AWS-managed profiles) naturally use arn:aws:bedrock-agentcore:..., and the field accepts both — it is just a string identifier.

The default identity is set per container at startup (CLUSTER_NODE → ARN mapping). Per-handler overrides flow through context: when Raima drafts a support reply, her handler stamps WithAgentProfileARN(ctx, ARNFor(AgentRaima)) and the envelope writer picks it up. When the Translation Service produces a response, it signs as tbts/v1. Translated content itself can be signed by the worker variant that ran it: tbts-haiku/v1, tbts-opus/v1, tbts-sonnet-4-6/v1.

The v1 roster includes tbi (platform default), tbi-dashboard, tbts (translation service orchestrator) and its model variants, webhook-engine, partner-ws-hub, sync-job, raima, threat-analyzer, digest-daily, digest-weekly, honeypot-processor, self-heal, and kiro. Phase 2 will migrate the roster to a database-backed agent_profiles table with versioning, model bindings, task contracts, and policies.

What This Means for Consumers

Parse once, use everywhere. One struct definition handles every response from every endpoint.
No defensive coding. You will never receive a response where error is missing on success or data is missing on error. They are always there.
Predictable debugging. When something goes wrong, the full context is always present — you never have to wonder "was this field omitted or was it genuinely empty?"
Forward-compatible. New fields added to the envelope will always be present from day one. No versioning headaches.

The principle: UME is consistent whether it is success or error or informational or caution. Messages are consistent always — especially externally, but also internally. No conditional coding around omitempty exceptions. The shape is the contract.

2. Envelope Anatomy

Success Envelope

{
  "status":            "✅ [SERVICE] [REGION] [NODE] [ENDPOINT] [CODE]",
  "status_code":       200,
  "endpoint":          "/path/to/resource",
  "cluster_node":      "BeastMain",
  "region":            "us-east-2",
  "language":          "en",
  "api_key_id":        "ak_abc123",
  "ip_address":        "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbi/v1",
  "timestamp":         "2026-05-29T18:00:00Z",
  "data":              { ...payload specific to the endpoint... },
  "error":             ""
}

Error Envelope

{
  "status":            "🛑 [SERVICE] [REGION] [NODE] [ENDPOINT] [CODE]",
  "status_code":       404,
  "endpoint":          "/path/to/resource",
  "cluster_node":      "BeastMain",
  "region":            "us-east-2",
  "language":          "en",
  "api_key_id":        "",
  "ip_address":        "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbi/v1",
  "timestamp":         "2026-05-29T18:00:00Z",
  "data":              null,
  "error":             "🛑 [SERVICE] [REGION] [NODE] [ENDPOINT] [CODE] Human-readable message"
}

Same shape. Always. Both envelopes have exactly 12 fields. On success, error is an empty string. On error, data is null. Neither field is ever omitted. Consumers parse with one struct definition — no branching on response type.

Envelope Fields

Field	Present In	Purpose
`status`	Always	Human-readable status line with service context. ✅ on success, 🛑 on error, ⚠️ on warning.
`status_code`	Always	HTTP status code (`200`, `201`, `400`, `404`, `500`, etc.)
`endpoint`	Always	The API path that was called
`cluster_node`	Always	Which ECS container handled the request (BeastMain, BeastMirror, BeastLRS, BeastWebhook)
`region`	Always	AWS region (always us-east-2)
`language`	Always	ISO 639-1 language code declaring the language of human-readable content. Determined by the subscriber's `api_lang` preference (default: `en`). Envelope metadata stays English always.
`api_key_id`	Always	The API key the call used. `""` for unauthenticated paths (health checks, public endpoints, 404s on missing routes).
`ip_address`	Always	Inbound: the client's source IP. Outbound (webhook push, WS broadcast): our container's ENI private IP — names which Beast machine pushed the update.
`agent_profile_arn`	Always	Addressable identity of the actor that produced this response. Never empty — every response is signed.
`timestamp`	Always	ISO 8601 UTC timestamp of when the response was generated
`data`	Always	The payload on success (object, array, or primitive). `null` on error — but always present.
`error`	Always	Descriptive error message on failure. Empty string `""` on success — but always present.

All 12 fields are present in every response. No field is ever conditionally omitted. Success responses carry "error": "". Error responses carry "data": null. This is the structural consistency guarantee — consumers parse one shape, always.

Implementation — Two Functions

The entire envelope is produced by two Go functions in internal/handlers/core_response.go:

func (h *HandlerDeps) WriteJSON(w http.ResponseWriter, r *http.Request, statusCode int, data interface{})
func (h *HandlerDeps) WriteError(w http.ResponseWriter, r *http.Request, statusCode int, message string)

Every handler in the system calls one of these two functions. No handler constructs its own response format. This is how consistency is enforced — not by convention, but by architecture.

3. Success Envelope — Live Examples

GET /health

{
  "status": "✅ [LPO] [us-east-2] [BeastMain] [/health] [200]",
  "status_code": 200,
  "endpoint": "/health",
  "cluster_node": "BeastMain",
  "region": "us-east-2",
  "language": "en",
  "api_key_id": "",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbi/v1",
  "timestamp": "2026-05-30T17:29:07Z",
  "data": { "message": "Health Check - OK" },
  "error": ""
}

GET /exchanges

{
  "status": "✅ [LPO] [us-east-2] [BeastLRS] [/exchanges] [200]",
  "status_code": 200,
  "endpoint": "/exchanges",
  "cluster_node": "BeastLRS",
  "region": "us-east-2",
  "language": "en",
  "api_key_id": "",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbi/v1",
  "timestamp": "2026-05-30T17:29:07Z",
  "data": {
    "exchanges": [
      { "name": "coinbase", "display_name": "Coinbase", "assets": [...] },
      { "name": "gemini", "display_name": "Gemini", "assets": [...] },
      ...
    ]
  },
  "error": ""
}

POST /support/submit

{
  "status": "✅ [LPO] [us-east-2] [BeastLRS] [/support/submit] [201]",
  "status_code": 201,
  "endpoint": "/support/submit",
  "cluster_node": "BeastLRS",
  "region": "us-east-2",
  "language": "en",
  "api_key_id": "",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbi/v1",
  "timestamp": "2026-05-06T20:27:18Z",
  "data": {
    "id": "f79c4a21-e99c-4d69-b808-df490befcacf",
    "status": "created",
    "ticket_number": "CPMP-20260506-62cc"
  },
  "error": ""
}

POST /translate

{
  "status": "✅ [LPO] [us-east-2] [BeastMain] [/translate] [200]",
  "status_code": 200,
  "endpoint": "/translate",
  "cluster_node": "BeastMain",
  "region": "us-east-2",
  "language": "ur",
  "api_key_id": "",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbi/v1",
  "timestamp": "2026-05-06T22:52:41Z",
  "data": {
    "translated": "فیملی فریڈ - لیجر ہمیشہ کے لئے عبور ہوگیا"
  },
  "error": ""
}

GET /price (Authenticated — The Price Envelope)

The price endpoint returns prices nested per-asset under data.prices — the same shape as POST /prices, so a single asset and a batch parse identically. Every field tells the developer something actionable:

{
  "status": "✅ [LPO] [us-east-2] [BeastMirror] [/price] [200]",
  "status_code": 200,
  "endpoint": "/price",
  "cluster_node": "BeastMirror",
  "region": "us-east-2",
  "language": "en",
  "api_key_id": "demo-public-2026-03-01-abc123",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbi/v1",
  "timestamp": "2026-05-30T17:29:07Z",
  "data": {
    "prices": {
      "BTC": {
        "exchange": "coinbase-ws",
        "cached": true,
        "cache_age_seconds": 0.08,
        "timestamp": 1780162147,
        "readable_timestamp": "2026-05-30T17:29:07Z",
        "latency_ms": 0,
        "price": "73835.99"
      }
    },
    "asset_count": 1,
    "resolved_count": 1,
    "failed": [],
    "latency_ms": 0,
    "duration_ms": 0,
    "monthly_usage": 27813,
    "monthly_limit": 999999999,
    "usage_pct": 0.003,
    "usage_warning": "",
    "usage_status": "✅"
  },
  "error": ""
}

Full UME Compliance: The price endpoint uses the standard 12-field envelope. Price data is nested inside data.prices, keyed by asset symbol — identical to POST /prices, so one parser handles both. The envelope provides routing metadata (who called via api_key_id, from where via ip_address, who answered via agent_profile_arn, which node, which region); the data payload carries the prices and usage accounting. Every response from the server — success or error — uses this same shape.

POST /prices (Batch Price Lookup — NEW)

The batch price endpoint returns multiple asset prices in a single request. Same UME envelope, same consistency guarantees — just more data in one call. The entire batch counts as 1 request against rate limits.

{
  "status": "✅ [LPO] [us-east-2] [BeastMain] [/prices] [200]",
  "status_code": 200,
  "endpoint": "/prices",
  "cluster_node": "BeastMain",
  "region": "us-east-2",
  "language": "en",
  "api_key_id": "ak_abc123",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbi/v1",
  "timestamp": "2026-05-28T20:32:08Z",
  "data": {
    "prices": {
      "BTC": {
        "exchange": "coinbase-ws",
        "cached": true,
        "cache_age_seconds": 0.082,
        "timestamp": 1780000328,
        "price": "73551.36"
      },
      "ETH": {
        "exchange": "coinbase-ws",
        "cached": true,
        "cache_age_seconds": 0.081,
        "timestamp": 1780000328,
        "price": "2016.48"
      },
      "SOL": {
        "exchange": "coinbase-ws",
        "cached": true,
        "cache_age_seconds": 0.217,
        "timestamp": 1780000328,
        "price": "82.36"
      }
    },
    "asset_count": 3,
    "resolved_count": 3,
    "failed": [],
    "latency_ms": 0,
    "duration_ms": 12,
    "monthly_usage": 4521,
    "monthly_limit": 100000,
    "usage_pct": 4.52,
    "usage_warning": "",
    "usage_status": "✅"
  },
  "error": ""
}

Efficiency Incentive: A POST /prices call with 30 assets counts as 1 request — not 30. The failed array is always present (empty array [] on full success, never omitted). The prices map is always an object (empty {} if all assets fail, never null). Same structural consistency as every other UME response.

4. Error Envelope — Live Examples

401 — Missing API Key

{
  "status": "🛑 [LPO] [us-east-2] [BeastLRS] [/price] [401]",
  "status_code": 401,
  "endpoint": "/price",
  "cluster_node": "BeastLRS",
  "region": "us-east-2",
  "language": "en",
  "api_key_id": "",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbi/v1",
  "timestamp": "2026-05-30T17:29:14Z",
  "data": null,
  "error": "🛑 [LPO] [us-east-2] [BeastLRS] [/price] [401] Missing API key"
}

404 — Route Not Found

{
  "status": "🛑 [LPO] [us-east-2] [BeastMain] [/admin/health] [404]",
  "status_code": 404,
  "endpoint": "/admin/health",
  "cluster_node": "BeastMain",
  "region": "us-east-2",
  "language": "en",
  "api_key_id": "",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbi/v1",
  "timestamp": "2026-05-17T14:40:00Z",
  "data": null,
  "error": "🛑 [LPO] [us-east-2] [BeastMain] [/admin/health] [404] Route not found"
}

Even 404s are UME-wrapped. The router's NotFound handler uses WriteError — no bare JSON strings ever leave the server. Every response, including unregistered routes, carries the full 12-field envelope. A consumer hitting a wrong path gets the same structured response they'd get from any other endpoint.

404 — Asset Not Found (Multi-lingual)

{
  "status": "🛑 [LPO] [us-east-2] [BeastMain] [/price] [404]",
  "status_code": 404,
  "endpoint": "/price",
  "cluster_node": "BeastMain",
  "region": "us-east-2",
  "language": "ja",
  "api_key_id": "demo-public-2026-03-01-abc123",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbi/v1",
  "timestamp": "2026-05-07T02:03:17Z",
  "data": null,
  "error": "🛑 [LPO] [us-east-2] [BeastMain] [/price] [404] シンボルFAKECOINは、当社のどの取引所（Coinbase、Gemini、Kraken、Gate.io、Crypto.com、OKX）にも見つかりませんでした。シンボルを確認して再試行してください。"
}

429 — Rate Limited

{
  "status": "🛑 [LPO] [us-east-2] [BeastMirror] [/price] [429]",
  "status_code": 429,
  "endpoint": "/price",
  "cluster_node": "BeastMirror",
  "region": "us-east-2",
  "language": "en",
  "api_key_id": "ak_abc123",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbi/v1",
  "timestamp": "2026-05-07T02:04:00Z",
  "data": null,
  "error": "🛑 [LPO] [us-east-2] [BeastMirror] [/price] [429] Rate limit exceeded. Your tier allows 10 QPS. Upgrade for higher limits."
}

Key Design Decision: Error messages are human-readable and delivered in the subscriber's messaging language (api_lang). The bracket prefix stays English (machine-readable), but the message after the brackets speaks their language. The language field declares which language the human-readable content is in — so consumers can route, display, or log accordingly.

4b. Multi-Lingual Messaging — How It Works

Every subscriber has a messaging language preference (api_lang) stored in the api_keys table. When a subscriber sets their language to Japanese, their error messages arrive in Japanese. The bracket metadata stays English (machine-parseable), but the human-readable content speaks their language.

Setting the Language

PUT /account/language
Headers: X-API-Key: your-api-key
Body: { "language": "ja" }

Response:
{
  "status": "✅ [LPO] [us-east-2] [BeastMain] [/account/language] [200]",
  "language": "ja",
  "data": {
    "api_lang": "ja",
    "message": "Language preference updated"
  }
}

Supported languages: en, es, pt, fr, de, ru, hi, ur, pa, ar, ja, zh

Architecture — Zero-Latency Translated Errors

Layer	What	How
Aurora	`error_messages` table	252 rows (21 message keys × 12 languages). Source of truth.
ElastiCache (Valkey)	`errmsg:{lang}:{key}`	Pre-built lookup. Synced nightly + on deploy. Zero network hop from ECS.
LPO Server	`GetErrorMessage()`	Reads from Valkey with 50ms timeout. Falls back to English, then hardcoded string.
Sync Job	`syncErrorMessages()`	Runs nightly at 1 AM EST. Loads all rows from Aurora → Valkey pipeline SET.

Fallback Chain

Look up errmsg:{api_lang}:{message_key} in Valkey
If miss → look up errmsg:en:{message_key} (English fallback)
If miss → use hardcoded English string (graceful degradation)

This means the system never fails to return an error message — even if Valkey is down, even if the translation is missing. It just falls back gracefully.

Message Keys with Placeholders

Some messages contain dynamic values using {placeholder} syntax. These are substituted at runtime:

Message Key	Placeholders	Example (Japanese)
`monthly_limit_reached`	`{usage}`, `{limit}`	月間クエリ制限に達しました。今月1000件中950件の許可されたクエリを使用しました。
`rate_limit_exceeded`	`{qps}`, `{burst}`	レート制限を超過しました。再試行する前にお待ちください。

Dual Language Preferences

Two languages, one person. A developer in Lahore might want API errors in Urdu (api_lang: ur) but billing emails in English (preferred_lang: en). Or a Japanese team might want everything in Japanese. The system respects both preferences independently.

Preference	Column	Controls	Set Via
Communications Language	`users.preferred_lang`	Emails, newsletters, support replies	Subscription form, support form
Messaging Language	`api_keys.api_lang`	API responses, error messages, price envelope	`PUT /account/language`

What Gets Translated vs. What Stays English

Always English (Machine-Readable)	Translated (Human-Readable)
Status brackets: `✅ [LPO] [us-east-2] [BeastMain]`	Error message text after the brackets
Field names: `status`, `endpoint`, `region`	Informational `data.message` strings
Status indicators: ✅ 🛑 ⚠️	Usage warnings, limit messages
Technical values: asset names, prices, timestamps	Payment and subscription notifications

5. Email Envelope — Outbound Communications

Every outbound email follows the same envelope pattern — adapted for the email channel:

Envelope Field	Email Equivalent	Example
`status`	Subject line	"Caso de Suporte Recebido — CPMP-20260506-5a32"
`cluster_node`	Sender identity	"CPMP Support <Support@CPMP-Site.org>"
`region`	Implicit (SES us-east-2)	—
`timestamp`	Email Date header	RFC 2822 date
`data`	HTML body	Translated content in recipient's language
`preferred_lang`	Content language	All chrome rendered in pt, ur, ar, etc.

Email Types in the Envelope

Trigger Table	Email Type	Language Source	Translation Method
`support_tickets`	Ticket confirmation	`preferred_lang`	`getSupportEmailStrings(lang)`
`support_replies`	Reply notification	`support_tickets.preferred_lang`	AWS Translate (body) + Go strings (chrome)
`newsletter_subscribers`	Welcome email	`preferred_lang`	SES Template + `email_translations` table
`transactions`	Receipt email	`users.preferred_lang`	Lambda receipt processor
`demo_leads`	Demo welcome	`preferred_lang`	SES Template
`partner_applications`	Application confirmation	English (technical audience)	Static template

6. Webhook Push Envelope

The Webhook Push service delivers prices to Associates using the same 12-field UME envelope as every other TBI response. The delivery-specific content (subscription, sequence, prices) lives inside the data field. The status line uses the [WEBHOOK] service tag, and the response is signed by the webhook-engine agent:

{
  "status": "✅ [WEBHOOK] [us-east-2] [BeastWebhook] [PUSH]",
  "status_code": 200,
  "endpoint": "/webhook/push",
  "cluster_node": "BeastWebhook",
  "region": "us-east-2",
  "language": "en",
  "api_key_id": "ak_assoc_7f3a",
  "ip_address": "10.0.3.214",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/webhook-engine/v1",
  "timestamp": "2026-05-07T02:05:00Z",
  "data": {
    "subscription_id": "ws-abc123",
    "delivery_id": "dlv-9f2c41a8",
    "sequence": 48213,
    "asset_count": 1,
    "tier": "standard",
    "prices": [
      {
        "asset": "BTC",
        "price": 81114.83,
        "source": "coinbase-ws",
        "updated_at": "2026-05-07T02:05:00Z"
      }
    ]
  },
  "error": ""
}

For HTTPS delivery the payload is signed with HMAC-SHA256 using the subscriber's signing secret; the signature travels in the X-Webhook-Signature header (alongside X-Webhook-Delivery-ID, X-Webhook-Subscription-ID, and X-Webhook-Timestamp) — not in the body, so the JSON stays a clean UME envelope. Outbound, ip_address is the pushing container's ENI IP and cluster_node is always BeastWebhook — the subscriber always knows which Beast pushed the update and when. The same single payload is sent over HTTPS and/or UDP.

7. The Identity Thread — How Email Unifies the Islands

The email field is the universal identifier. A single person may appear across 6+ tables — but they are one person, receiving one unified communication experience. The envelope doesn't need foreign keys to connect the islands. It connects them through identity.

Table	Email Field	Language Field	Communication Triggered
`users`	`email`	`preferred_lang`	Subscription receipt, tier change notifications
`api_keys`	via `users`	`api_lang`	API responses, error messages (Messaging Language)
`newsletter_subscribers`	`email`	`preferred_lang`	Welcome email, newsletter broadcasts
`support_tickets`	`email`	`preferred_lang`	Ticket confirmation, reply notifications
`demo_leads`	`email`	`preferred_lang`	Demo welcome email
`transactions`	`email`	via `users`	Payment receipt
`partner_applications`	`email`	—	Application confirmation
`webhook_subscriptions`	via `api_keys`	—	Webhook push deliveries

Diagram 7.1 — Identity Thread Across All Tables

flowchart LR
    subgraph Identity["🧑 One Person (email + preferred_lang)"]
        E["email@example.com
preferred_lang: ur"]
    end

    subgraph Tables["Database Tables (Islands)"]
        U[users]
        NS[newsletter_subscribers]
        ST[support_tickets]
        DL[demo_leads]
        TX[transactions]
        PA[partner_applications]
    end

    subgraph Envelope["Unified Messaging Envelope"]
        SES["📧 SES Email
(in user's language)"]
        WH["📡 Webhook Push
(signed delivery)"]
        API["🔌 API Response
(TBC envelope)"]
    end

    E --> U
    E --> NS
    E --> ST
    E --> DL
    E --> TX
    E --> PA

    U --> SES
    NS --> SES
    ST --> SES
    DL --> SES
    TX --> SES
    PA --> SES
    U --> WH
    U --> API

    style E fill:#FF9900,stroke:#cc7a00,color:#fff
    style SES fill:#a855f7,stroke:#7c3aed,color:#fff
    style WH fill:#ef4444,stroke:#dc2626,color:#fff
    style API fill:#10b981,stroke:#059669,color:#fff
    style U fill:#1e293b,stroke:#FF9900,color:#e2e8f0
    style NS fill:#1e293b,stroke:#a855f7,color:#e2e8f0
    style ST fill:#1e293b,stroke:#f97316,color:#e2e8f0
    style DL fill:#1e293b,stroke:#64748b,color:#e2e8f0
    style TX fill:#1e293b,stroke:#22c55e,color:#e2e8f0
    style PA fill:#1e293b,stroke:#64748b,color:#e2e8f0

8. Extensibility — Adding New Endpoints

Adding a new endpoint to The Trinity Beast automatically inherits the Unified Messaging Envelope. Here's why:

Step 1: Write Your Handler

func (h *HandlerDeps) MyNewHandler(w http.ResponseWriter, r *http.Request) {
    // ... your logic ...

    // Success — automatically wrapped in the envelope
    h.WriteJSON(w, r, http.StatusOK, map[string]interface{}{
        "result": "your data here",
    })

    // Error — automatically wrapped in the error envelope
    h.WriteError(w, r, http.StatusBadRequest, "Something went wrong")
}

Step 2: Register the Route

lpoRouter.HandleFunc("/my-new-endpoint", handlerDeps.MyNewHandler).Methods("GET", "OPTIONS")

That's It.

No envelope construction. No manual JSON marshaling. No remembering to add cluster_node or region. The WriteJSON function reads the node name, region, endpoint path, and timestamp from the handler's shared dependencies and wraps your payload automatically.

Extensibility by design: The envelope is not opt-in. It is the only way to send a response. Every new endpoint, every new feature, every new handler — they all speak the same language from day one. This is what makes the system feel unified even as it grows.

Adding a New Email Communication

Store preferred_lang in the relevant table (or read it from an existing table via email lookup)
Call getSupportEmailStrings(lang) or load from email_translations table
If dynamic content needs translation: call translateText(text, "en", lang, logger)
Send via sendSupportEmail() or SES SendTemplatedEmail

The pattern is the same every time. Language is incidental. The envelope handles it.

9. Architecture — The Envelope Engulfs Everything

Every table, every endpoint, every outbound channel — wrapped in the same envelope. This diagram shows how the UME sits as the outermost layer around the entire system.

Diagram 9.1 — Unified Messaging Envelope Architecture

flowchart TD
    subgraph UME["🔶 UNIFIED MESSAGING ENVELOPE"]
        direction TB

        subgraph Inbound["Inbound Channels"]
            HTTP["HTTPS API
(40+ endpoints)"]
            UDP["UDP Protocol
(LPO + LRS)"]
            FORM["Web Forms
(Support, Subscribe, Give)"]
        end

        subgraph Processing["Processing Layer"]
            WJ["WriteJSON()
Success Envelope"]
            WE["WriteError()
Error Envelope"]
            TR["translateText()
AWS Translate"]
            ES["Email Strings
12 languages"]
        end

        subgraph DataLayer["Data Layer (37 Tables)"]
            CORE["Core
users · api_keys"]
            USAGE["Usage
usage_logs · reports"]
            EXCHANGE["Exchange
feeds · asset_map"]
            EMAIL["Email
newsletters · templates"]
            SUPPORT["Support
tickets · replies"]
            WEBHOOK["Webhook
subscriptions · delivery"]
            ANALYTICS["Analytics
page_views · events"]
        end

        subgraph Outbound["Outbound Channels"]
            API_OUT["📡 API Response
(TBC Envelope)"]
            EMAIL_OUT["📧 SES Email
(Multi-lingual)"]
            PUSH_OUT["🔔 Webhook Push
(HMAC signed)"]
            UDP_OUT["⚡ UDP Datagram
(Zero-alloc)"]
        end

        HTTP --> WJ
        HTTP --> WE
        UDP --> WJ
        FORM --> WJ
        FORM --> TR

        WJ --> API_OUT
        WE --> API_OUT
        WJ --> UDP_OUT

        CORE --> WJ
        USAGE --> WJ
        EXCHANGE --> WJ
        SUPPORT --> WJ
        SUPPORT --> TR
        EMAIL --> ES
        WEBHOOK --> PUSH_OUT

        TR --> EMAIL_OUT
        ES --> EMAIL_OUT
    end

    style UME fill:#0f172a,stroke:#FF9900,stroke-width:3,color:#FF9900
    style HTTP fill:#1e293b,stroke:#60a5fa,color:#e2e8f0
    style UDP fill:#1e293b,stroke:#60a5fa,color:#e2e8f0
    style FORM fill:#1e293b,stroke:#60a5fa,color:#e2e8f0
    style WJ fill:#10b981,stroke:#059669,color:#fff
    style WE fill:#ef4444,stroke:#dc2626,color:#fff
    style TR fill:#635bff,stroke:#4b44cc,color:#fff
    style ES fill:#a855f7,stroke:#7c3aed,color:#fff
    style API_OUT fill:#FF9900,stroke:#cc7a00,color:#0f172a
    style EMAIL_OUT fill:#FF9900,stroke:#cc7a00,color:#0f172a
    style PUSH_OUT fill:#FF9900,stroke:#cc7a00,color:#0f172a
    style UDP_OUT fill:#FF9900,stroke:#cc7a00,color:#0f172a
    style CORE fill:#1e293b,stroke:#FF9900,color:#e2e8f0
    style USAGE fill:#1e293b,stroke:#3b82f6,color:#e2e8f0
    style EXCHANGE fill:#1e293b,stroke:#06b6d4,color:#e2e8f0
    style EMAIL fill:#1e293b,stroke:#a855f7,color:#e2e8f0
    style SUPPORT fill:#1e293b,stroke:#f97316,color:#e2e8f0
    style WEBHOOK fill:#1e293b,stroke:#ef4444,color:#e2e8f0
    style ANALYTICS fill:#1e293b,stroke:#14b8a6,color:#e2e8f0

10. Complete Endpoint Catalog with Envelope Examples

Every endpoint in the system, grouped by category, showing which envelope fields are present in each response.

Public Endpoints (No Auth)

Method	Endpoint	Envelope Type	Key Data Fields
`GET`	`/health`	Success	`message`
`GET`	`/exchanges`	Success	`exchanges[]` with assets
`GET`	`/asset-categories`	Success	`categories[]`
`GET`	`/public/infrastructure`	Success	`cloudfront`, `waf`, `sqs`, `lambda`, `sync`, `guardduty`, `alarms`, `honeypot`, `autoops`, `cache`, `services`, `translation` — cached 60s
`GET`	`/public/cluster`	Success	Per-node ECS telemetry, Valkey stats, Aurora stats — cached 30s
`GET`	`/public/site-assets`	Success	`pages`, `docs`, `images`, `videos`, `total_files` — cached 1hr
`GET`	`/search`	Success	`results[]` with title, snippet, url — multi-lingual via `?lang=`
`GET`	`/map/pins`	Success	`pins[]` with lat/lng/type/media
`POST`	`/translate`	Success	`translated`
`POST`	`/support/submit`	Success (`201`)	`ticket_number`, `id`
`GET`	`/support/tickets`	Success	`tickets[]`
`GET`	`/support/ticket/{num}`	Success	Full ticket + replies
`POST`	`/newsletter/subscribe`	Success (`201`)	`status`, `email`
`GET`	`/newsletter/unsubscribe`	Success	`status`
`POST`	`/demo/register`	Success (`201`)	`id`
`POST`	`/partner/apply`	Success (`201`)	`id`, `status`
`GET`	`/checkout`	Redirect (`302`)	Stripe Payment Link URL

Dashboard Endpoints (Bearer Token — localStorage)

The customer dashboard uses a separate Bearer token auth pattern (not the API key system). Tokens are stored in localStorage and sent via Authorization: Bearer. These endpoints return plain JSON without the standard UME envelope — they are SPA data endpoints, not public API endpoints.

Method	Endpoint	Key Data Fields
`POST`	`/dashboard/api/request-link`	Magic link email trigger — always returns 200
`GET`	`/dashboard/authenticate`	HTML bridge page — writes session token to localStorage, redirects to SPA
`GET`	`/dashboard/api/session`	`email`, `roles`, `created_at`, `last_seen`
`GET`	`/dashboard/api/account`	Full account — all facets (donor, api_key, webhook, partner), roles, is_admin
`POST`	`/dashboard/api/billing/portal`	`url` — Stripe portal session URL
`GET`	`/dashboard/api/api-key/reveal`	`api_key` — full unmasked key (audit-logged)
`GET`	`/dashboard/api/usage`	`this_month`, `quota`, `daily_breakdown[]`
`GET`	`/dashboard/api/giving/history`	`charges[]` — date, amount_usd, receipt_url
`POST`	`/dashboard/api/admin/impersonate`	`session_token`, `email`, `roles` — admin only
`POST`	`/dashboard/api/logout`	Clears session from Valkey

Authenticated Endpoints (Bearer Token)

Method	Endpoint	Envelope Type	Key Data Fields
`GET`	`/price`	Price (flat)	`price`, `source`, `latency_ms`, `cached`
`PUT`	`/account/language`	Success	`api_lang`, `message`
`GET`	`/reports/usage`	Success	`logs[]`, `total`, pagination
`GET`	`/reports/summary`	Success	Aggregated stats
`GET`	`/reports/assets`	Success	Per-asset breakdown
`GET`	`/reports/report`	Success	Report-on-report meta

Admin Endpoints (X-Admin-Key)

Method	Endpoint	Envelope Type	Key Data Fields
`POST`	`/admin/sql`	Success	`columns`, `rows[]`, `row_count`, `duration_ms`
`POST`	`/admin/sql-batch`	Success	`results[]`, `total_duration_ms`
`POST`	`/admin/valkey`	Success	`result` (raw Redis response)
`POST`	`/admin/invalidate-key`	Success	`status`
`GET`	`/admin/cluster-stats`	Success	`per_node[]`, `aggregated`
`GET`	`/admin/feed-status`	Success	WebSocket feed health per exchange

Webhook Push (Outbound)

Method	Delivery	Envelope Type	Key Data Fields
`POST`	HTTPS to subscriber endpoint	Webhook	`event`, `data.price`, `hmac`
UDP	Datagram to subscriber IP:port	Compact	Binary price payload