The Trinity Beast — Go Application Features

1. At a Glance

The Trinity Beast is a single Go binary that serves real-time cryptocurrency prices from 6 exchanges, reports usage analytics in 4 formats, manages subscriptions via Stripe, processes partner applications, and publishes 30+ CloudWatch metrics — all from one main.go controlled by a SERVER_TYPE environment variable.

2. Table-Driven Exchange Manager

Adding a new exchange to The Trinity Beast requires zero code changes. The Exchange Manager reads its configuration from two Aurora tables and launches WebSocket connections dynamically.

graph TD
    TBCC[TBCC Exchange Manager] -->|"CRUD API"| EF[(exchange_feeds
19 columns)]
    TBCC -->|"CRUD API"| EAM[(exchange_asset_map
150 rows)]
    EF -->|"on startup"| EM[Exchange Manager
Go Engine]
    EAM -->|"symbol lookup"| EM
    EM -->|"launches"| WS1[Coinbase WS]
    EM -->|"launches"| WS2[Gemini WS]
    EM -->|"launches"| WS3[Kraken WS]
    EM -->|"launches"| WS4[Gate.io WS]
    EM -->|"launches"| WS5[Crypto.com WS]
    EM -->|"launches"| WS6[OKX WS]
    WS1 -->|"prices"| PC[sync.Map
Price Cache]
    WS2 -->|"prices"| PC
    WS3 -->|"prices"| PC
    WS4 -->|"prices"| PC
    WS5 -->|"prices"| PC
    WS6 -->|"prices"| PC
    PC --> API["price API
prices API"]
    EF -->|"public"| DD["Demo Dropdown
exchanges endpoint"]

    style TBCC fill:#4a5568,stroke:#718096,color:#e2e8f0
    style EF fill:#2d4a6f,stroke:#4a7ab5,color:#cbd5e1
    style EAM fill:#2d4a6f,stroke:#4a7ab5,color:#cbd5e1
    style EM fill:#2d5a4a,stroke:#4a9a7a,color:#cbd5e1
    style PC fill:#2d5a4a,stroke:#4a9a7a,color:#cbd5e1
    style API fill:#4a5568,stroke:#718096,color:#e2e8f0
    style DD fill:#3d3a5c,stroke:#6b6399,color:#cbd5e1
    style WS1 fill:#334155,stroke:#64748b,color:#94a3b8
    style WS2 fill:#334155,stroke:#64748b,color:#94a3b8
    style WS3 fill:#334155,stroke:#64748b,color:#94a3b8
    style WS4 fill:#334155,stroke:#64748b,color:#94a3b8
    style WS5 fill:#334155,stroke:#64748b,color:#94a3b8
    style WS6 fill:#334155,stroke:#64748b,color:#94a3b8
        

exchange_feeds — 19 Columns

Each row defines a complete WebSocket connection: endpoint URL, subscribe message template with {SYMBOLS} placeholder, JSON paths for extracting price/symbol/timestamp from trade messages, timestamp format (RFC3339, unix_ms, unix_ns), ping keepalive interval and payload, and an enabled flag to disable an exchange without a deploy.

exchange_asset_map — Symbol Translation

Every exchange uses a different symbol format for the same asset. BTC is BTC-USD on Coinbase, btcusd on Gemini, BTC/USD on Kraken, BTC_USDT on Gate.io, BTCUSDT on Crypto.com, and BTC-USDT on OKX. The translation table maps each normalized asset (BTC) to its exchange-specific symbol. 161 rows across 6 active exchanges, zero overlap, all data-driven. Each row carries three control flags: enabled (appears in the subscriber dropdown), prewarm (gets a live WebSocket subscription), and category (dropdown group). The EAM Admin Panel provides a visual interface for managing all rows without writing SQL.

CRUD API

3. Six-Exchange WebSocket Engine

Every price in The Trinity Beast arrives via a persistent WebSocket connection — no REST polling, no scheduled fetches, no stale data. Each container maintains 6 independent WebSocket connections, one per exchange.

Each feed auto-reconnects with exponential backoff (1s → 60s max), respects the shutdown signal for graceful termination, and stores prices in both the per-exchange WsPriceCache and the main PriceCache via CachePriceLocal. The source exchange is tracked in every API response and every usage log — total transparency.

4. Three-Tier Price Cache

graph LR
    REQ[Price Request] --> T1
    T1[Tier 1
sync.Map
Zero Network] -->|"HIT ~0ms"| RESP[Response]
    T1 -->|"MISS"| T2
    T2[Tier 2
ElastiCache
Sub-ms Network] -->|"HIT ~1ms"| RESP
    T2 -->|"MISS"| T3
    T3[Tier 3
REST Fallback
Exchange API] -->|"50-200ms"| RESP

    WS[6 WebSocket Feeds] -->|"every trade"| T1

    style REQ fill:#4a5568,stroke:#718096,color:#e2e8f0
    style T1 fill:#2d5a4a,stroke:#4a9a7a,color:#cbd5e1
    style T2 fill:#2d4a6f,stroke:#4a7ab5,color:#cbd5e1
    style T3 fill:#5a4a2d,stroke:#9a7a4a,color:#cbd5e1
    style RESP fill:#2d5a4a,stroke:#4a9a7a,color:#cbd5e1
    style WS fill:#3d3a5c,stroke:#6b6399,color:#cbd5e1
        

The cache TTL is configurable per profile — 13 seconds in production (fresh-price), 300 seconds during stress testing. WebSocket-fed assets stay sub-second fresh regardless of TTL because every trade pushes a new price into Tier 1.

5. UDP v8 — SO_REUSEPORT, recvmmsg, Pre-Serialized Responses

Three generations of UDP optimizations, each targeting a specific bottleneck. The progression from v6 to v8 transformed UDP from a protocol that failed above 1,500 concurrent into one that achieves 100% success at 21,000 concurrent — the first perfect run in Trinity Beast history.

6. Runtime Telemetry — 24 Atomic Counters

Every container runs 24 atomic.Int64 counters that track the complete request lifecycle in real-time. The overhead is approximately 1 nanosecond per increment — invisible at any throughput level.

Access via GET /admin/stress-stats — returns all 24 counters plus derived metrics (RPS, hit percentages, drop rates) in a single JSON response. Reset with GET /admin/stress-reset before each test run. Six key metrics are also published to CloudWatch for dashboard visibility.

7. Cluster-Wide Aggregation via ElastiCache

Each container publishes its 24-counter metrics snapshot to ElastiCache every 3 seconds. The /admin/cluster-stats endpoint reads all 4 snapshots in a single ElastiCache pipeline call — one round-trip, sub-millisecond, guaranteed all 4 containers.

How It Works

graph LR
    subgraph Containers
        M[BeastMain
24 counters] -->|"every 3s"| EC
        Mi[BeastMirror
24 counters] -->|"every 3s"| EC
        L[BeastLRS
24 counters] -->|"every 3s"| EC
    end
    EC[(ElastiCache
cluster:stats:*
TTL 30s)]
    EC -->|"1 pipeline read"| CS[/admin/cluster-stats/]
    CS --> TBCC[Command Center
Cluster Health Widget]
    CS --> CW[CloudWatch
6 Runtime Metrics]

    style M fill:#334155,stroke:#64748b,color:#94a3b8
    style Mi fill:#334155,stroke:#64748b,color:#94a3b8
    style L fill:#334155,stroke:#64748b,color:#94a3b8
    style EC fill:#5a3a3a,stroke:#8a5a5a,color:#e2c8c8
    style CS fill:#2d5a4a,stroke:#4a9a7a,color:#cbd5e1
    style TBCC fill:#2d4a6f,stroke:#4a7ab5,color:#cbd5e1
    style CW fill:#3d3a5c,stroke:#6b6399,color:#cbd5e1
        

ElastiCache Keys

If a container hasn't published in 30 seconds, its key expires and it shows as missing in the cluster view — an immediate signal that something is wrong. The publish interval (3 seconds) and TTL (30 seconds) are candidates for future application parameters.

Response Structure

GET /admin/cluster-stats returns per-node snapshots and aggregated totals:

• per_node — array of 4 snapshots, each with cluster_node, region, published_at, and all 24 counters
• aggregated — summed counters across all 4 containers with recomputed percentages
• nodes_found / nodes_expected — instant health indicator
• region — AWS region (us-east-2)

8. Partner Tier — Zero Friction Access

AWS Partners connect via PrivateLink (TCP) or VPC Peering (UDP) directly to containers. Partner API keys bypass all rate limiting, monthly caps, and billing checks — in both the TCP and UDP handlers.

The exchanges we depend on — Coinbase, Gemini, Kraken, Gate.io, Crypto.com, OKX — share their data with us at no cost. We pass that forward. If your AWS application needs live crypto prices, we provide them free. We receive freely, we give freely.

Partners apply through a public form at /partner-apply.html, receive a professional SES confirmation email, and can check their application status at /partner-status.html. Applications are reviewed in the TBCC Partner Management widget.

9. Application Parameter Profiles

16 named profiles stored in Aurora's application_parameter_profiles table. Each profile defines a complete set of tuning parameters — rate limits, cache TTLs, connection pool sizes, batch settings, and logging levels. Applied instantly via GET /admin/system-mode?mode=<name>.

Key tuning rule: db_max_idle always equals db_max_open — the fix that dropped p99 latency from 1,266ms to 8.9ms. All cache pool sizes are multiples of 3 (one pool per container).

10. SQS Queued Write Pipeline

Usage logs are never written synchronously — and never written directly to Aurora from the hot path. Every price request fires a message to SQS via a channel-buffered producer. A purpose-built Go Lambda (trinity-beast-queued-writer) consumes batches from the queue and batch-inserts into Aurora. Zero logs shed. Zero latency added to the price response.

• sqs_batch_size — messages per SQS SendMessageBatch call (default 10, max 10)
• sqs_flush_ms — flush interval in milliseconds (default 100, stress: 50)
• sqs_buffer_size — channel buffer capacity (default 50,000, stress: 100,000)
• sqs_timeout_ms — per-batch SQS API call timeout (default 3,000ms)

Messages use a type-routed envelope format ({"type":"usage_log","payload":{...}}) — extensible to any future write type without changing queue or Lambda infrastructure. During Run 17 at 746,374 combined RPS, every usage log was delivered to Aurora via SQS with zero shedding — solving the data integrity gap discovered in earlier stress tests where only ~12K of 1.34B requests produced Aurora rows.

The consumer Lambda folds each batch's per-key usage increments into a single set-based UPDATE rather than one statement per key: UPDATE api_keys SET current_usage = current_usage + data.increment FROM (SELECT unnest($1::text[]) AS api_key, unnest($2::int[]) AS increment) AS data WHERE api_keys.api_key = data.api_key. A 100-message batch touching N distinct keys becomes N → 1 round-trips to Aurora.

11. Distributed Adaptive Governor

A cluster-wide TCP connection throttle coordinated via ElastiCache. Each container tracks its success rate over a rolling window. When the rate drops below the threshold, the governor introduces a configurable delay to shed load gracefully — preventing cascade failures under extreme concurrency.

Disabled during direct-to-container stress tests (where we want to find the raw ceiling). Enabled during ALB/NLB tests (where we want production-like behavior).

12. Single Binary, Four Modes

One Docker image. One Go binary. Four operational modes controlled by the SERVER_TYPE environment variable:

All 4 ECS services run the same image. The only difference is the environment variable. This means one build, one push, one image — deployed to 4 services with different configurations. The Webhook service is outbound-only (no ALB) — it pushes prices to Associates via UDP + HTTPS on a configurable schedule.

13. Secrets-Driven Configuration

Zero hardcoded credentials or email addresses. Everything sensitive is loaded from AWS Secrets Manager at startup and injected into the Config struct. 16 keys covering database credentials, Stripe API key, SMTP settings, and all SES sender addresses.

To change a sender email address, update it in Secrets Manager and restart the container. No code deploy, no binary rebuild.

14. Multi-Lingual Translation Engine

The infrastructure uses two translation systems: AWS Translate for real-time API responses (support tickets, map captions), and a custom Bedrock-powered engine for document translation. Both use ElastiCache as a persistent cache. Language is not a barrier — the system handles it transparently.

Two Translation Systems

Real-Time Translation Components

Localized Refund Emails

Refund confirmation emails are sent in the customer's preferred_lang (stored in the users table). Both translation purchase refunds and subscription refunds are localized across 12 languages using the same hardcoded-struct pattern as support emails.

Document Translation Engine

Technical documentation requires more than neural machine translation — code blocks, diagrams, brand names, and version numbers must survive intact. The custom Bedrock-powered engine uses sentinel preprocessing to protect technical content, multi-layer validation to ensure structural integrity, and Step Functions orchestration for fire-and-forget operation.

Full documentation: AutoOps Translation Engine

Translation Flow

• Support Inbound: Customer submits in their language → translateText(message, lang, "en") → stored in message_en
• Support Outbound: Admin replies in English → translateText(reply, "en", lang) → stored in message_translated, sent via SES
• Map Captions: POST /translate → check ElastiCache → on miss, call AWS Translate → cache result for 30 days
• Documents: POST /admin/translate → SQS → Step Functions → Bedrock worker → S3 deploy → CloudFront invalidation. Use options.delta = true to skip language pairs where the translated file is already newer than the source — saves up to 90% on incremental updates.

Caching Strategy

Supported Languages

Internal website (12 languages): English, Spanish, Portuguese, French, German, Russian, Hindi, Urdu, Italian, Arabic, Japanese, Chinese (Simplified). All documentation and UI is translated into these 12 languages.

Service API (21+ languages): The translation service exposes all languages supported by Amazon Bedrock Claude — customers can translate to any language the model handles reliably, including Italian, Korean, Indonesian, Bengali, Turkish, Vietnamese, Thai, Polish, Dutch, and more.

IAM Configuration

The ECS task role (ecsTaskRole) has an inline policy TranslateAccess granting translate:TranslateText permission. The translation worker task role has bedrock:InvokeModel permission for Claude Sonnet. No VPC endpoint required — both APIs are accessed via public AWS endpoints.

15. Honoring the PostgreSQL Engine

A round of PostgreSQL optimization pushed aggregation and frequent-query work down into Aurora and removed per-query overhead on the hot paths. The principle: let the database do what databases are good at, prepare the queries that run constantly, and measure every change against the live engine before keeping it.

Prepared-Statement Registry (dbx)

A thin seam over database/sql registers the five fixed-shape, high-frequency queries as named prepared statements at startup: API-key lookup, API-key last-used touch, application-parameters load, report-count check, and report-count upsert. It is deliberately not an ORM or query builder — handlers issuing dynamic SQL keep calling *sql.DB directly. The registry is nil-safe and fail-soft: if a statement fails to prepare, it transparently falls back to an ad-hoc query, so a registration problem can never block server startup. Startup logs dbx: registered 5 hot-path prepared statements.

Single-Round-Trip Consolidations

• Report-counter upsert — the LRS counter collapsed a read-then-insert two-step into one INSERT … ON CONFLICT DO UPDATE with month/day rollover logic, removing a round-trip on every report request.
• Set-based usage updates — the queued-writer Lambda folds a batch's per-key increments into a single UPDATE … FROM (unnest(...)) (see section 10), turning N round-trips into 1 per batch.
• Account resolver — eliminated an N+1 query pattern at dashboard login by batching webhook-subscription lookups with ANY($1).

GROUPING SETS Analytics + Server-Side Percentiles

The admin analytics summary replaced six separate aggregation queries with a single GROUPING SETS pass that also computes latency percentiles (percentile_cont p50/p95/p99) inside the engine. Measured 2.1× faster against live Aurora — 87 ms to 41 ms, six round-trips to one.

Composite Indexes + Daily-Rollup Materialized View

Database self-observability (the /admin/db-insights endpoint) showed usage_logs doing sequential scans on filtered analytics queries. Four (timestamp, dimension) composite indexes — on asset, API key, source, and cluster node — let the planner use index scans instead (6–8 ms execution). Per-day rollups (totals, latency percentiles, cache-hit rate, cardinality) are precomputed by the mv_usage_daily materialized view, served via /dashboard/api/admin/daily-rollup. The view is refreshed every 5 minutes by the pg_cron job tbi-mv-usage-daily-refresh running inside Aurora, using REFRESH MATERIALIZED VIEW CONCURRENTLY so readers never block.

Self-Observability

The /admin/db-insights endpoint surfaces the buffer-cache hit ratio (currently ~99%), the top queries by total execution time and call count from pg_stat_statements, and per-table sequential-vs-index scan health — the same evidence that justified the composite indexes above. A companion /admin/db-insights/reset clears the pg_stat_statements baseline for clean before/after measurement windows.

16. Every Query Funds Freedom

This is not a feature of the Go application. It is the reason the Go application exists.