Complete folder structure, file descriptions, and integration guide for all three Go applications
The Trinity Beast platform consists of three independent Go applications, each with its own repository, Docker image, and deployment pipeline. All three follow the standard Go project layout conventions and share a common infrastructure on AWS (Aurora PostgreSQL, ElastiCache, Secrets Manager).
| Application | Purpose | Runtime | Docker Image |
|---|---|---|---|
trinity-beast-lpo-server |
Listener Price Oracle + Listener Reporting Service — the main application serving TCP/UDP price queries and usage reports | ECS Fargate (4 services) | trinity-beast-lpo-server:latest |
trinity-beast-sync-job |
Nightly sync job — reads usage_logs from Aurora, writes to ElastiCache for LRS reporting. 93-day rolling retention. |
ECS Fargate (standalone task) | trinity-beast-sync-job:latest |
trinity-beast-receipt-lambda |
Post-checkout receipt processor — reads Stripe sessions, records transactions in Aurora, generates API keys, sends SES email receipts | AWS Lambda (provided.al2023) | N/A (zip deployment) |
The main application powering the Listener Price Oracle and Listener Reporting Service. Runs as three ECS Fargate services (BeastMain, BeastMirror, BeastLRS) from a single Docker image. Handles real-time crypto price queries via TCP and UDP, usage reporting, rate limiting, caching, and CloudWatch metrics.
trinity-beast-lpo-server/ ├── go.mod, go.sum ├── Makefile ├── README.md ├── .dockerignore │ ├── bin/ — Compiled binaries │ ├── price-server — Local server build │ ├── trinity-beast-demo-linux — Demo client (Linux) │ ├── trinity-beast-demo-mac — Demo client (macOS) │ ├── trinity-beast-demo.exe — Demo client (Windows) │ ├── trinity-stress — Stress test client (macOS) │ └── trinity-stress-linux — Stress test client (Linux) │ ├── cmd/ — Application entry points (15 binaries) │ ├── server/ │ │ ├── main.go — LPO + LRS server (2554 lines) │ │ └── metrics.go — CloudWatch metrics publisher │ ├── demo/ │ │ └── main.go — Interactive demo client for API testing │ ├── receipt/ │ │ └── main.go — Receipt handler (legacy, see receipt-lambda) │ ├── stress/ │ │ └── main.go — Go stress test client for load testing │ ├── queued-writer/ │ │ └── main.go — SQS usage log consumer Lambda (Go, VPC) │ └── autoops/ — AutoOps + Translation Engine Lambdas (10 binaries) │ ├── notify/ │ │ └── main.go — tbi-ops-notify: formatted SES notifications │ ├── self-heal/ │ │ └── main.go — tbi-ops-self-heal: ECS restart, force-deploy │ ├── waf-action/ │ │ └── main.go — tbi-ops-waf-action: WAF IP set management │ ├── honeypot-processor/ │ │ └── main.go — tbi-ops-honeypot-processor: drain queue → WAF block │ ├── bedrock-analyze/ │ │ └── main.go — tbi-ops-bedrock-analyze: AI threat analysis │ ├── bedrock-support/ │ │ └── main.go — tbi-rhema-support: ticket categorization + draft │ ├── digest/ │ │ └── main.go — tbi-ops-digest: daily/weekly operational digests + newsletter │ ├── email-sender/ │ │ └── main.go — trinity-beast-email-sender: SQS consumer, sends pre-built emails via SES │ ├── support-inbound/ │ │ └── main.go — tbi-support-inbound: parses inbound email replies into support threads │ └── refresh-mv/ │ └── main.go — tbi-ops-refresh-mv: RETIRED 2026-05-31 — replaced by pg_cron job tbi-mv-usage-daily-refresh inside Aurora │ ├── deployments/ │ ├── autoops/ │ │ ├── autoops-policy.json — IAM policy for tbi-autonomous-ops-role │ │ ├── trust-policy.json — Trust policy (Lambda assume role) │ │ └── state-machines/ — Step Function ASL definitions │ ├── cloudformation/ │ │ ├── trinity-beast-stack.yaml — Complete infrastructure template (170+ resources) │ │ └── inventory/ — 70+ JSON snapshots of every AWS resource │ ├── docker/ │ │ ├── Dockerfile — LPO server multi-stage build │ │ ├── Dockerfile.receipt — Receipt Lambda build │ │ ├── Dockerfile.queued-writer — Queued-writer Lambda build │ │ └── Dockerfile.sync — Sync job build │ ├── iam/ │ │ ├── secrets-db-policy.json — Secrets Manager + DB access policy │ │ ├── sqs-consume-policy.json — SQS receive/delete policy (queued-writer) │ │ └── sqs-send-policy.json — SQS send policy (ECS tasks) │ ├── ses/ │ │ ├── DemoWelcome.json — Demo welcome email template │ │ ├── donation-receipt.json — Donation receipt template │ │ └── subscription-receipt.json — Subscription receipt template │ ├── task-definitions/ — ECS task definition JSON files (15 files) │ │ ├── main-service-config.json │ │ ├── mirror-service-config.json │ │ ├── lrs-service-config.json │ │ └── ... (versioned task defs) │ └── webhook-task-def.json — Webhook service task definition │ ├── docs/ — Technical documentation (mirrors cpmp-redesign/docs/ — all project artifacts together) │ ├── index.html — Document Library landing page │ ├── css/docs-common.css — Shared docs stylesheet │ ├── analytics-dashboard.html — Website Analytics dashboard │ ├── dashboard.html — KCC Live Dashboard │ ├── Trinity-Beast-*.html — 44 technical documents (full set) │ ├── profile-tuning-analysis.md — Session notes: profile tuning │ ├── race-day-plan.md — Session notes: stress test race day │ ├── stress-test-v4-session-notes.md — Session notes: v4 stress test │ └── stripe-payment-links-setup.md — Session notes: Stripe setup │
internal/ — Core Packages├── internal/ — Private application packages (16 packages) │ ├── agentprofiles/ │ │ └── store.go — Agent-profile registry: the actor identities that sign every UME response (agent_profiles table, refreshed every 5 min) │ ├── apikeys/ │ │ └── apikeys.go — API key store: load, cache, validate, refresh │ ├── cache/ │ │ └── redis.go — ElastiCache connection, price cache read/write │ ├── config/ │ │ ├── params.go — Application parameter loader (Aurora → ElastiCache → runtime) │ │ └── secrets.go — AWS Secrets Manager reader │ ├── database/ │ │ ├── postgres.go — Aurora connection pool, reader/writer endpoints │ │ ├── shutdown.go — Graceful shutdown: drain connections, flush buffers │ │ ├── sqs_producer.go — SQS message producer for queued usage log pipeline │ │ └── dbx/ — Prepared-statement registry (hot-path queries) │ │ ├── dbx.go — PreparedSet: nil-safe, fail-soft named prepared statements │ │ └── queries.go — 5 hot-path query definitions + RegisterHotPath() │ ├── handlers/ │ │ ├── account.go — Account management: magic link auth, profile, billing portal │ │ ├── admin.go — Admin endpoints: /admin/invalidate-key, /admin/system-mode, /admin/feed-status │ │ ├── adminsql.go — /admin/sql: read/write SQL with DDL blocking │ │ ├── adminsqlbatch.go — /admin/sql-batch: unrestricted DDL + multi-statement SQL │ │ ├── adminstressreport.go — /admin/seed-stress-report: stress test result seeding │ │ ├── adminvalkey.go — /admin/valkey: direct ElastiCache command execution │ │ ├── analytics.go — Page analytics: /analytics/pageview, /analytics/event, /admin/page-analytics │ │ ├── checkout.go — /checkout: Stripe Payment Link redirect with locale passthrough │ │ ├── demo_leads.go — Demo lead capture + SES welcome email │ │ ├── deps.go — HandlerDeps struct: shared dependencies for all handlers │ │ ├── email.go — SES email sending helper + email admin CRUD │ │ ├── errmsg.go — Multi-lingual error message system (Aurora-backed, cached) │ │ ├── errors.go — Standardized error response formatting (TBC + plain) │ │ ├── exchangefeeds.go — Exchange Manager: CRUD for exchange_feeds + exchange_asset_map │ │ ├── honeypot.go — Honeypot trap system: 12 decoy endpoints, auto-block queue │ │ ├── i18n.go — Valkey-backed i18n: GET /public/lang/{code}, POST /admin/lang/set │ │ ├── mappins.go — Map pin data endpoint for impact map │ │ ├── newsletter.go — Newsletter subscribe/unsubscribe/send/admin endpoints │ │ ├── partner_ws.go — Partner WebSocket: real-time price feed over persistent WS connections │ │ ├── partners.go — Partner application: submit, status check, admin review │ │ ├── pipeline.go — Background pipeline: batch Aurora writes, SQS integration │ │ ├── price.go — /price endpoint: fetch, cache, rate-limit, respond │ │ ├── admin_profiles.go — Application parameter profiles: migration, seed, list │ │ ├── admin_agent_profiles.go — Agent-profile registry admin: list, upsert, event history │ │ ├── public_cluster.go — /public/cluster: ECS telemetry, Valkey stats, Aurora stats (no auth) │ │ ├── public_infrastructure.go — /public/infrastructure: CloudFront, WAF, SQS, Lambda, GuardDuty, Alarms, ECS Services (no auth) │ │ ├── public_site_assets.go — /public/site-assets: S3 bucket file counts by type (no auth) │ │ ├── public_status.go — /public/status: public infrastructure dashboard (no auth) │ │ ├── refund_email.go — Localized refund confirmation emails: 12 languages, translation + subscription refunds, test endpoint │ │ ├── response.go — Unified JSON response writer (UME 12-field envelope) │ │ ├── search.go — Full-text search: GET /search + POST /admin/build-search-index (12 languages) │ │ ├── stressstats.go — /admin/stress-stats, /admin/cluster-stats (24 atomic counters) │ │ ├── support.go — Support tickets: submit, list, reply, status (customer + admin) │ │ ├── translate.go — Translation engine admin: submit, status, queue, history, cancel, retry │ │ ├── translate_*.go — 24 more translation files. October 2026 added accept, accept_batch, accept_stage (staging, fingerprint re-check, requote), customer_status (status and task), download_links, failed_refund and failed_refund_sweep (retry, refund machine, 15-min sweeper), fingerprint, limits, seams, source_lang and ssrf (private-address guard on document fetches) │ │ ├── udp.go — UDP v8: SO_REUSEPORT, recvmmsg batch reads, pre-serialized responses │ │ ├── webhook.go — Webhook Push management: /webhook/configure, /verify, /status, /assets │ │ ├── webhook_delivery.go — Webhook delivery engine: table-driven push via UDP + HTTPS │ │ └── dashboard/ — Customer Account Dashboard (17 files) │ │ ├── admin_analytics.go — Admin analytics panel data (GROUPING SETS summary + percentiles) │ │ ├── admin_support.go — Admin support ticket management │ │ ├── auth.go — Magic link authentication flow │ │ ├── customer_support.go — Customer support ticket submission │ │ ├── daily_rollup.go — /dashboard/api/admin/daily-rollup: serves mv_usage_daily materialized view │ │ ├── dashboard.go — Dashboard router and initialization │ │ ├── handler.go — HTTP handler registration │ │ ├── middleware.go — Session validation middleware │ │ ├── models.go — Dashboard data models │ │ ├── panels.go — Panel data resolvers (billing, usage, keys) │ │ ├── render.go — HTML template rendering │ │ ├── reports.go — Usage report generation │ │ ├── resolver.go — Data resolver: Aurora + Valkey + Stripe │ │ ├── session.go — Session management (Valkey-backed) │ │ ├── spa_script.go — Embedded SPA JavaScript │ │ └── spa.go — Single-page app shell renderer │
internal/ — Service, Model and Support Packages│ ├── lrs/ │ │ ├── counter.go — LRS report counter: per-key monthly limit tracking │ │ ├── errors.go — LRS-specific error types │ │ ├── handlers.go — /reports/usage, /reports/summary endpoints │ │ ├── middleware.go — LRS authentication and rate limiting middleware │ │ ├── params.go — LRS configuration parameters │ │ ├── pipeline.go — LRS background pipeline: batch writes, aggregation │ │ ├── response.go — LRS UME response writer (12-field envelope, [LRS] service tag) │ │ ├── types.go — LRS data types: UsageReport, SummaryReport │ │ └── usagelogger.go — LRS usage log writer for report-on-report tracking │ ├── bedrock/ │ │ ├── invoke.go — Amazon Bedrock InvokeModel wrapper with retry on transient errors (503, 429, timeouts) │ │ └── formats.go — Per-model request/response shaping (model family detection) │ ├── email/ │ │ └── loader.go — Shared loader for centralized email templates (Valkey email:tpl:{name}, S3-sourced, 5-min cache, English fallback) │ ├── txlangs/ — The 127-language catalog │ │ ├── txlangs.go — Catalog loader: Aurora → Valkey tx:lang_catalog → tx:supported_langs → empty, refreshed in place every 15 minutes │ │ ├── resolve.go — Alias and regional-form resolution (nb → no, ar-XX → ar) │ │ ├── shape.go — Input and canonical code shape checks (2–12 characters) │ │ ├── aliases_gen.go — Generated from migrations/data/translation_language_aliases.tsv (36 aliases) │ │ └── definitive_gen.go — Generated: the definitive-detection tables (en, ja kana, ko, th) │ ├── txlimits/ │ │ └── txlimits.go — Shared translation limits: 12 languages, 42 documents, 300 KB, 9 quotes per batch (no imports) │ ├── txpgtest/ │ │ └── txpgtest.go — Test-only real-Postgres harness: baseline schema + release migrations │ ├── txparams/ │ │ └── txparams.go — Translation Engine parameter store (Aurora translation_parameters → Valkey tx:params, separate from app:config) │ ├── middleware/ │ │ ├── adaptive.go — Distributed Adaptive Governor: cross-node rate coordination │ │ ├── adminauth.go — Admin endpoint authentication middleware │ │ ├── cors.go — CORS middleware for browser requests │ │ ├── ratelimit.go — Token bucket rate limiter with ElastiCache backing │ │ └── ratelimit_test.go — Rate limiter unit tests │ ├── models/ │ │ ├── config.go — Config struct: all application parameters │ │ ├── lpo.go — LPO-specific models: PriceResponse, SourceHealth │ │ ├── models.go — Shared models: APIKeyData, UsageLog, Secret │ │ └── timer.go — TimerManager: periodic task scheduling │ ├── pricing/ │ │ ├── cache.go — Three-tier price cache: sync.Map → ElastiCache → REST │ │ ├── cache_flush.go — FlushToElastiCache: batch pipeline write from local WS cache │ │ ├── cache_test.go — Cache unit tests │ │ ├── engine.go — PriceEngine: orchestrates source selection and fallback │ │ ├── exchange_manager.go — Generic table-driven Exchange Manager: loads configs from Aurora │ │ ├── health.go — Source health tracking: staleness detection, failover │ │ ├── prewarm.go — Asset prewarming: Kraken batch + exchange_asset_map translation │ │ ├── sources.go — Price sources: 6 WebSocket + 6 REST fallbacks (one per exchange) │ │ ├── websocket_bitstamp.go — Bitstamp WebSocket feed (replaced Gemini, June 2026) │ │ ├── websocket_coinbase.go — Coinbase WebSocket feed │ │ ├── websocket_cryptocom.go — Crypto.com WebSocket feed │ │ ├── websocket_gateio.go — Gate.io WebSocket v4 feed │ │ ├── websocket_helpers.go — Shared helpers: parseFloat, parseInt64 │ │ ├── websocket_kraken.go — Kraken WebSocket v2 feed │ │ └── websocket_okx.go — OKX WebSocket v5 feed │ ├── metrics/ │ │ └── runtime.go — RuntimeMetrics: 24 atomic counters for stress test observability │ └── ratelimit/ — (empty, rate limiting in middleware/ratelimit.go) │
├── pkg/ │ └── logger/ │ └── logger.go — Structured logger: module-tagged, level-filtered, JSON-ready │ ├── scripts/ │ ├── migrate_database.sql — Aurora schema migration │ ├── perf-test-suite.sh — Performance test automation │ ├── run_migration.sh — Migration runner │ ├── seed-templates.sh — SES template seeder │ ├── tbmcstart — Start TBCC (The Trinity Beast Command Center) │ ├── tbmcstop — Stop TBCC │ ├── integration-test.sh — Integration suite runner (containers up → test → down) │ ├── terminal-relay.py — Python terminal relay for TBCC │ ├── test.sh — Go test runner │ ├── udp-stress-test.py — Python UDP load tester │ ├── v4-setup-test-instance.sh — EC2 stress test instance setup │ └── v4-stress-test.py — Python v4 stress test client │ ├── tests/integration/ — End-to-end suite (real Postgres + Valkey) │ ├── docker-compose.yml — Postgres 17 + Valkey 9 test containers │ ├── harness_test.go — TestMain, schema/data seed, server builder, HTTP helpers │ └── integration_test.go — Request-path tests (health, price, search, admin, support) │ ├── migrations/ — Versioned SQL with a .statements.json twin per file │ ├── 2026-10-09-01a / 01b — Language catalog columns and the 52 new catalog rows (127 in all) │ ├── 2026-10-09-02 — Profiles for every catalog language; lang columns widened to 12 characters │ ├── 2026-10-09-03 / 03b — Refund, requote and retry columns, job → quote link, refund parameters; deploy stamp │ └── data/ — translation_language_catalog.tsv (127 rows, the single source), translation_language_aliases.tsv, a live snapshot of 2026-10-09 │ ├── tests/stress/ — Compiled stress test binaries │ ├── stress.go — Basic stress test │ ├── stress_direct.go — Direct (ALB bypass) stress test │ └── stress_full.go — Full ALB stress test │ └── test-results/ — Stress test result documentation ├── run14-stress-results.md — Run 14 results └── v33-alb-bypass-rationale.md — ALB bypass testing rationale
The registry of who answered. Every UME response carries an agent_profile_arn naming the actor that produced it, and this is where those identities live. store.go loads the agent roster from Aurora's agent_profiles table at startup and refreshes it every 5 minutes — the same load-and-refresh shape as the application-parameter loader. Phase 1 kept the roster as constants in code; Phase 2 moved it here so identities can be versioned and audited through agent_profile_events without a redeploy.
store.go — Agent-profile registry: load + 5-min refresh from agent_profiles
API key store with in-memory sync.Map cache. Loads keys from Aurora on startup, refreshes periodically. Validates keys, checks tier limits, tracks current usage.
apikeys.go — API key store: load, cache, validate, refresh
ElastiCache (Valkey 9.0) connection management. Handles TLS connections, price cache read/write, app config hash, and connection health checks.
redis.go — ElastiCache connection, price cache read/write
Application parameter loading pipeline: Aurora → ElastiCache → runtime config struct. params.go loads the 87 parameters from the app:config hash (fast path) or Aurora (fallback). secrets.go reads credentials from AWS Secrets Manager.
params.go — Application parameter loader (Aurora → ElastiCache → runtime) secrets.go — AWS Secrets Manager reader
Aurora PostgreSQL connection management. postgres.go manages dual connection pools (writer + reader endpoints). sqs_producer.go implements the channel-buffered SQS message producer that queues usage logs for the Lambda consumer. shutdown.go handles graceful connection draining. The dbx/ subpackage is a thin seam over database/sql that registers the five fixed-shape hot-path queries (API-key lookup, API-key touch, params load, report-count check, report-count upsert) as named prepared statements at startup — nil-safe and fail-soft, falling back to ad-hoc queries if preparation fails so it never blocks startup.
postgres.go — Aurora connection pool, reader/writer endpoints shutdown.go — Graceful shutdown: drain connections, flush buffers sqs_producer.go — SQS message producer for queued usage log pipeline dbx/dbx.go — PreparedSet registry: nil-safe, fail-soft named prepared statements dbx/queries.go — The 5 hot-path query definitions + RegisterHotPath()
All HTTP and UDP request handlers. deps.go defines the shared HandlerDeps struct. price.go is the core /price endpoint. udp.go runs dual UDP v6 servers with multi-socket zero-alloc architecture. exchangefeeds.go provides full CRUD for the table-driven Exchange Manager. webhook.go handles Webhook Push management (configure, verify, status, assets). webhook_delivery.go is the table-driven delivery engine that pushes prices to Associates via UDP + HTTPS. partner_ws.go provides real-time WebSocket price feeds for Partners. public_status.go powers the public Infrastructure Live dashboard. public_cluster.go, public_infrastructure.go, and public_site_assets.go provide live telemetry for the observability page. checkout.go handles Stripe checkout redirects with locale passthrough. analytics.go provides privacy-first page analytics. support.go integrates AWS Translate for bi-directional translation of support correspondence and exposes a public /translate endpoint with ElastiCache caching for map caption translation. refund_email.go provides localized refund confirmation emails in 12 languages for both translation and subscription refunds, plus a test endpoint for email rendering verification.
admin.go — Admin endpoints: /admin/invalidate-key, /admin/system-mode, /admin/feed-status adminsql.go — /admin/sql: read/write SQL with DDL blocking adminsqlbatch.go — /admin/sql-batch: unrestricted DDL + multi-statement SQL adminstressreport.go — /admin/seed-stress-report: stress test result seeding adminvalkey.go — /admin/valkey: direct ElastiCache command execution analytics.go — Page analytics: /analytics/pageview, /analytics/event, /admin/page-analytics checkout.go — /checkout: Stripe Payment Link redirect with locale passthrough demo_leads.go — Demo lead capture + SES welcome email deps.go — HandlerDeps struct: shared dependencies for all handlers email.go — SES email sending helper + email admin CRUD errors.go — Standardized error response formatting (TBC + plain) exchangefeeds.go — Exchange Manager: CRUD for exchange_feeds + exchange_asset_map + public /exchanges mappins.go — Map pin data endpoint for impact map newsletter.go — Newsletter subscribe/unsubscribe/send/admin endpoints partner_ws.go — Partner WebSocket: real-time price feed over persistent WS connections partners.go — Partner application: submit, status check, admin review, SES confirmation pipeline.go — Background pipeline: batch Aurora writes, SQS integration price.go — /price endpoint: fetch, cache, rate-limit, respond + background housekeeping admin_profiles.go — Application parameter profiles: migration, seed (16 profiles), list endpoint public_cluster.go — /public/cluster: ECS telemetry, Valkey stats, Aurora stats (no auth) public_infrastructure.go — /public/infrastructure: CloudFront, WAF, SQS, Lambda, GuardDuty, Alarms, ECS Services (no auth) public_site_assets.go — /public/site-assets: S3 bucket file counts by type, cached 1hr in Valkey (no auth) public_status.go — /public/status: public infrastructure dashboard (no auth, powers Infrastructure Live page) response.go — Unified JSON response writer (TBC envelope format) stressstats.go — /admin/stress-stats, /admin/stress-reset, /admin/cluster-stats (24 atomic counters) support.go — Support tickets, AWS Translate integration, /translate endpoint, multi-lingual SES emails udp.go — UDP v6: multi-socket, zero-alloc response builder, per-socket worker pools webhook.go — Webhook Push management: /webhook/configure, /verify, /status, /assets + tier template migration webhook_delivery.go — Webhook delivery engine: table-driven push via UDP fire-and-forget + HTTPS signed POST
Complete Listener Reporting Service implementation. handlers.go serves /reports/usage and /reports/summary with JSON, CSV, TSV, and text output formats. counter.go tracks per-key monthly report limits in ElastiCache. middleware.go handles LRS-specific auth and rate limiting. usagelogger.go implements report-on-report tracking (LRS queries generate their own usage logs). pipeline.go batches report-usage writes, and response.go writes the LRS UME envelope with its [LRS] service tag. types.go and params.go define data structures and configuration. errors.go provides LRS-specific error types.
counter.go — LRS report counter: per-key monthly limit tracking errors.go — LRS-specific error types handlers.go — /reports/usage, /reports/summary endpoints middleware.go — LRS authentication and rate limiting middleware params.go — LRS configuration parameters pipeline.go — LRS background pipeline: batch writes, aggregation response.go — LRS UME response writer (12-field envelope, [LRS] service tag) types.go — LRS data types: UsageReport, SummaryReport usagelogger.go — LRS usage log writer for report-on-report tracking
Request processing middleware. adaptive.go implements the Distributed Adaptive Governor — cross-node rate coordination via ElastiCache counters. ratelimit.go is the per-key token bucket rate limiter backed by ElastiCache. adminauth.go authenticates admin endpoints. cors.go handles CORS headers for browser requests.
adaptive.go — Distributed Adaptive Governor: cross-node rate coordination adminauth.go — Admin endpoint authentication middleware cors.go — CORS middleware for browser requests ratelimit.go — Token bucket rate limiter with ElastiCache backing ratelimit_test.go — Rate limiter unit tests
All data structures. config.go defines the Config struct with all 87 application parameters and their defaults. models.go has APIKeyData, UsageLog, Secret, and other shared types. lpo.go has PriceResponse, SourceHealth, WSPrice. timer.go provides the TimerManager for periodic task scheduling.
config.go — Config struct: all application parameters lpo.go — LPO-specific models: PriceResponse, SourceHealth models.go — Shared models: APIKeyData, UsageLog, Secret timer.go — TimerManager: periodic task scheduling
Price fetching engine. engine.go orchestrates source selection with automatic failover. Six per-exchange WebSocket files (websocket_coinbase.go, websocket_bitstamp.go, websocket_kraken.go, websocket_gateio.go, websocket_cryptocom.go, websocket_okx.go) provide real-time feeds from 6 exchanges — 360 prewarmed assets with zero REST polling. Binance and Bybit were removed (permanently geo-blocked from US), replaced by Gate.io and Crypto.com respectively; Gemini was removed after its feed went stale and replaced by Bitstamp. exchange_manager.go is the table-driven generic Exchange Manager that loads configurations from Aurora's exchange_feeds and exchange_asset_map tables. prewarm.go uses exchange_asset_map for Kraken symbol translation. cache_flush.go batch-writes local WebSocket prices to ElastiCache every 30 seconds.
cache.go — Three-tier price cache: sync.Map → ElastiCache → REST cache_flush.go — FlushToElastiCache: batch pipeline write from local WS cache websocket_bitstamp.go — Bitstamp WebSocket feed (replaced Gemini, June 2026) engine.go — PriceEngine: orchestrates source selection and fallback exchange_manager.go — Generic table-driven Exchange Manager: loads configs from Aurora health.go — Source health tracking: staleness detection, failover prewarm.go — Asset prewarming: Kraken batch + exchange_asset_map translation sources.go — Price sources: 6 WebSocket + 6 REST fallbacks (one per exchange) websocket_coinbase.go — Coinbase WebSocket feed websocket_cryptocom.go — Crypto.com WebSocket feed websocket_gateio.go — Gate.io WebSocket v4 feed websocket_helpers.go — Shared helpers: parseFloat, parseInt64 websocket_kraken.go — Kraken WebSocket v2 feed websocket_okx.go — OKX WebSocket v5 feed
Runtime observability for stress testing. runtime.go defines 24 atomic counters (lock-free, ~1ns per increment) covering throughput, cache performance, UDP health, background pool saturation, batch pipeline pressure, and DB connection utilization. The /admin/stress-stats endpoint reads all counters in ~50ns and computes derived metrics (RPS, hit percentages, drop rates). Zero overhead on the hot path.
runtime.go — RuntimeMetrics: 24 atomic counters, TakeSnapshot(), Reset()
The single doorway to Amazon Bedrock. invoke.go wraps InvokeModel with retry logic for the transient failures every model call eventually meets — 503s, 429 throttles, and timeouts — so no caller has to hand-roll its own backoff. formats.go shapes the request and response per model family, which is what lets the same wrapper serve Qwen, Claude, and others without the caller knowing the difference.
invoke.go — InvokeModel wrapper with retry on 503/429/timeout formats.go — Per-model request/response shaping (model family detection)
One place to read a localized email template, so no handler ever hardcodes copy. loader.go reads templates from Valkey hashes (email:tpl:{name}, one field per language), caches them in memory for five minutes, and falls back to English when a language is missing. The templates originate as S3 JSON — the source of truth — and reach Valkey through the nightly BeastReconciler sync, so editing customer-facing copy never means touching Go code.
loader.go — Centralized email template loader (Valkey → 5-min cache → English fallback)
The Translation Engine's language catalog, and the reason a customer is never charged for a language we cannot actually deliver. Before it existed, /translate/quote checked only the shape of a language code — two or three lowercase letters — so any well-formed string got quoted, charged, and queued to Bedrock even when it named a language the model had never meaningfully learned. txlangs.go validates each code against the supported set, turning "looks like a language" into "is a language we support."
Since October 2026 it is the whole 127-language catalog rather than a list: every code is resolved through it (aliases converted quietly, regional forms kept), and each container refreshes it in place every 15 minutes, so a language change needs no deploy. If the catalog is ever empty, quotes answer 503 and nobody is charged.
txlangs.go — Catalog loader and 15-minute refresh resolve.go — Alias and region resolution shape.go — Code shape checks aliases_gen.go — Generated from the alias TSV definitive_gen.go — Generated definitive-detection tables
One small file that every translation path agrees on: 12 languages per quote, 42 documents, 300 KB per document and 9 quotes per batch. It imports nothing, so the quote, accept, admin submit and dashboard code can all share it without a cycle, and a limit can never drift between two of them.
txlimits.go — Shared translation limits
A real-Postgres test harness, imported only by tests: it creates a throwaway database, applies the live baseline schema and every release migration, and drops it afterwards, so migration and money-path tests run against real SQL instead of mocks. Skipped when TX_PG_DSN is unset.
txpgtest.go — Open, OpenMigrated, ApplyMigrations
The Translation Engine's own parameter store, kept deliberately separate from application config. txparams.go loads translation cost, pricing, and operational parameters from Aurora's translation_parameters table into the Valkey tx:params hash. Translation is a standalone service with its own cost model and pricing tiers, so mixing its controls into app:config would blur two things that change for entirely different reasons.
txparams.go — Translation Engine parameter store (Aurora → Valkey tx:params)
Rate limiting logic lives in middleware/ratelimit.go and middleware/adaptive.go. This directory is reserved but currently unused.
Main LPO+LRS+Webhook server (production). Contains main.go which is the single-file server implementing all LPO, LRS, and Webhook Push functionality. The SERVER_TYPE environment variable controls which services start: APP_SERVER (LPO only), REPORT_SERVER (LRS only), APP_REPORT_SERVER (both LPO + LRS), or WEBHOOK_SERVER (outbound price push delivery). Also contains metrics.go for CloudWatch metric publishing to the TrinityBeast/LPO and TrinityBeast/LRS namespaces.
Interactive demo client for API testing. A command-line tool that exercises the LPO and LRS endpoints, useful for verifying deployments and demonstrating API capabilities to potential subscribers.
Receipt handler — legacy copy. The production version of this code lives in the trinity-beast-receipt-lambda repository. This copy is kept for reference but is not deployed from here.
Go stress test client used for load testing. Compiles to platform-specific binaries in bin/ (trinity-stress for macOS, trinity-stress-linux for Linux). Used during Run 17 performance testing to achieve 487,900 UDP and 369,600 TCP requests per second. The v5.0 distributed client drove 746,374 combined RPS across 3 stress clients.
Purpose-built Go Lambda that drains the trinity-beast-queued-usage-logs SQS queue and batch-inserts usage log entries into Aurora. Routes on a message type field for extensibility — currently handles usage_log type. Replaces the legacy in-process UsageWriter that shed logs under extreme load. Folds each batch's per-key increments into a single set-based UPDATE (N → 1 round-trips).
Ten standalone Go Lambdas for AutoOps and the Translation Engine, each in its own subdirectory with a main.go: notify, self-heal, waf-action, honeypot-processor, bedrock-analyze, bedrock-support (Rhema), digest, email-sender, support-inbound, and refresh-mv (retired). email-sender is a deliberately brainless SQS consumer that sends pre-built emails via SES — the receipt Lambda assembles the full message in the right language and enqueues it, and this Lambda just delivers it. support-inbound parses inbound email replies at reply.cpmp-site.org back into their support threads. The refresh-mv subdirectory is retained for reference — the Lambda (tbi-ops-refresh-mv) was deleted 2026-05-31 when pg_cron was installed in Aurora. The earlier translate-deploy, translate-finalize, and translate-init Lambdas were removed on 2026-06-27 when translation finalization moved in-process to the LPO server endpoint /admin/translate/complete.
A standalone Go application that runs as a scheduled ECS Fargate task. Triggered nightly at 1 AM EST by EventBridge rule trinity-beast-nightly-sync. Reads usage_logs from Aurora PostgreSQL and writes them to ElastiCache as Redis hashes and sorted set indexes for fast LRS reporting. Maintains 93 days (~3 months) of rolling data.
trinity-beast-sync-job/ ├── go.mod — Go module definition and dependencies ├── go.sum — Dependency checksums (auto-generated) ├── Dockerfile — Multi-stage build: Go 1.26 builder → Alpine 3.19 runtime (linux/amd64) ├── README.md — Project overview and usage │ ├── cmd/ — Application entry point │ └── sync/ — Sync job application │ ├── main.go — The nightly pipeline: Aurora → ElastiCache (historical + incremental + prune) and every reconciler step │ └── bedrock_rates.go — Nightly Bedrock rate refresh: AWS Price List → Aurora translation_parameters, then verified in tx:params │ ├── internal/ — Private packages (reserved for future refactoring) │ ├── models/ — Data structures: UsageLog (reserved) │ └── sync/ — Sync logic: batch storage, pruning (reserved) │ └── sync/ — Legacy directory (deprecated)
main.go implements the sync pipeline, and since October 2026 bedrock_rates.go keeps the translation engine's token rates honest: each night it reads every model's rates from the public AWS Price List, writes any change to Aurora before the parameters are copied to tx:params, and holds a model's old rates if the new ones look wrong (SYNC_ONLY=bedrock-rates runs just that part). On first run (ElastiCache empty), loads 93 days of historical data. On subsequent runs, loads yesterday through current moment and prunes records older than 93 days. Stores each usage log as a Redis hash with 18 fields, plus sorted set indexes by timestamp, API key, and asset. All Redis keys have 93-day TTLs.
Unlike the LPO server, the Dockerfile lives at the project root. Same multi-stage pattern: Go 1.26 Alpine builder compiles a static linux/amd64 binary, then copies it into a minimal Alpine 3.19 runtime image. Runs as non-root appuser.
CACHE_URL, DB_SECRET_NAME, AWS_REGION. Optional: FORCE_FULL_SYNC=true to reload all 93 days.
A Go Lambda function that handles post-checkout processing for donations, subscriptions, and LRS add-on purchases. Called by the thank-you pages via API Gateway after Stripe redirects. Reads the Stripe checkout session, records transactions in Aurora, generates API keys for subscribers, and sends branded SES email receipts.
trinity-beast-receipt-lambda/ ├── go.mod — Go module definition and dependencies ├── go.sum — Dependency checksums (auto-generated) ├── bootstrap — Compiled Linux binary (Lambda runtime expects this name) ├── function.zip — Packaged zip for Lambda deployment (contains bootstrap) │ ├── cmd/ — Application entry point │ └── handler/ — Lambda handler │ └── main.go — Handler: Stripe session reader, Aurora inserts, SES email sender │ └── handler/ — Legacy directory (deprecated)
Contains main.go implementing three flows: donation (transaction → SES receipt), subscription (users → api_keys → transaction → SES receipt with API key), and lrs-addon (validate subscriber → enable LRS → transaction → SES receipt). Uses direct HTTP calls to the Stripe API (no SDK). Reads secrets from AWS Secrets Manager. Tier configuration is read from the rate_limit_template table in Aurora — rate limits, burst limits, and query limits per tier are data-driven, not hardcoded.
Lambda on provided.al2023 runtime expects the binary to be named bootstrap. The function.zip contains just this binary. Built with GOOS=linux GOARCH=amd64 CGO_ENABLED=0 and stripped with -ldflags="-w -s" for minimal size.
DB_SECRET_NAME=trinity-beast-secrets, SES_FROM=No-Reply@CPMP-Site.org. AWS_REGION is provided automatically by Lambda.
The public-facing website for Cross Power Ministries of Pakistan. Contains 26 public HTML pages, 4 admin pages, 44 technical documents, shared CSS/JS, newsletter templates, and media assets. Deployed to S3 bucket trinity-beast-website-east2 and served via CloudFront distribution E110PRKEIYQVLL.
cpmp-redesign/ — Live website (S3 → CloudFront) ├── index.html — Homepage ├── give.html — Give page with impact cards ├── give.html — Alternative giving page ├── subscribe-listener.html — LPO subscription page with code examples ├── thank-you.html — Donation thank-you page ├── thank-you-listener.html — Subscription/LRS addon thank-you page ├── map.html — Impact map (Leaflet + marker clusters) ├── medical-camps.html — Medical camps impact page ├── freedom-moments.html — Freedom moments impact page ├── provisions.html — Provisions impact page ├── training.html — Education/training impact page ├── word-of-life.html — Bible distribution impact page ├── wheelchairs.html — Wheelchair impact page ├── clean-water.html — Clean water impact page ├── team.html — Team page ├── support.html — Support/contact page ├── newsletters.html — Newsletter archive page ├── newsletter-optout-cpmp.html — CPMP newsletter unsubscribe ├── newsletter-optout-lpo.html — LPO newsletter unsubscribe ├── authority.html — Statement of authority ├── privacy.html — Privacy policy ├── terms.html — Terms of service ├── copyright.html — Copyright notice │ ├── admin/ — Admin console pages │ ├── trinity-beast-command-center.html — TBCC dashboard │ ├── newsletteradmin.html — Newsletter administration │ ├── emailadmin.html — Email administration │ └── supportadmin.html — Support ticket administration │ ├── css/ │ └── style.css — Shared stylesheet │ ├── js/ │ ├── i18n.js — Multi-lingual engine v4: 12 languages, browser detection, RTL support │ ├── analytics.js — Privacy-first page analytics beacon │ └── theme.js — Day/night theme switching │ ├── lang/ — 12 JSON translation files (1,000+ keys each) │ ├── en.json, es.json, pt.json — English, Spanish, Portuguese │ ├── fr.json, de.json, ru.json — French, German, Russian │ ├── hi.json, ur.json, it.json — Hindi, Urdu, Italian │ └── ar.json, ja.json, zh.json — Arabic, Japanese, Chinese (Simplified) │ ├── includes/ │ ├── header.html — Shared navigation header │ └── footer.html — Shared footer │ ├── docs/ — Technical documentation (Document Library + dashboards + index) │ ├── index.html — Document Library landing page (grouped by category) │ ├── css/docs-common.css — Shared docs stylesheet (header, footer, meta) │ ├── analytics-dashboard.html — Website Analytics dashboard (interactive) │ ├── dashboard.html — KCC Live Dashboard (Valkey-powered) │ ├── Trinity-Beast-Ad-Setup-Guide.html │ ├── Trinity-Beast-API-Reference.html │ ├── Trinity-Beast-Application-Parameters.html │ ├── Trinity-Beast-Architecture-Guide.html │ ├── Trinity-Beast-Associate-Onboarding.html │ ├── Trinity-Beast-Aurora-Data-Dictionary.html │ ├── Trinity-Beast-CloudFormation-Guide.html │ ├── Trinity-Beast-CloudWatch-Guide.html │ ├── Trinity-Beast-Command-Center-Guide.html │ ├── Trinity-Beast-Disaster-Recovery-Runbook.html │ ├── Trinity-Beast-Docker-Setup-Guide.html │ ├── Trinity-Beast-ElastiCache-Definitions.html │ ├── Trinity-Beast-Go-Application-Features.html │ ├── Trinity-Beast-Infrastructure-Live.html │ ├── Trinity-Beast-Infrastructure-Resource-Costs.html │ ├── Trinity-Beast-Infrastructure-Resource-Inventory.html │ ├── Trinity-Beast-Infrastructure-Specification.html │ ├── Trinity-Beast-Kiro-Command-Center.html │ ├── Trinity-Beast-Kiro-Expert-Assessment.html │ ├── Trinity-Beast-LRS-Report-Management.html │ ├── Trinity-Beast-Message-Queue-Configuration.html │ ├── Trinity-Beast-Page-Analytics.html │ ├── Trinity-Beast-Partner-Onboarding.html │ ├── Trinity-Beast-Performance-Report.html │ ├── Trinity-Beast-Project-Structure.html │ ├── Trinity-Beast-Quick-Reference.html │ ├── Trinity-Beast-Stress-Test-Plan.html │ ├── Trinity-Beast-Stripe-Implementation.html │ └── Trinity-Beast-Subscription-Lifecycle.html │ ├── templates/ │ ├── newsletter-template-cpmp.html — CPMP newsletter template │ └── newsletter-template-lpo.html — LPO newsletter template │ ├── images/ — 55+ image assets (photos, favicons, QR codes) ├── icons/ — 16 SVGs: 12 language flags + 4 crypto token icons ├── videos/ — 6 MP4 impact videos └── originals/ — Pre-redesign pages (reference only, NOT deployed)
The root directory contains all public-facing pages. The homepage (index.html), giving flow (give.html, thank-you.html), subscription flow (subscribe-listener.html, thank-you-listener.html), seven impact category pages, the interactive impact map (map.html using Leaflet + marker clusters), team page, support page, newsletter archive, two newsletter opt-out pages, and four legal/policy pages.
Four admin console pages. The Trinity Beast Command Center (trinity-beast-command-center.html) provides a real-time dashboard for monitoring the LPO server. newsletteradmin.html, emailadmin.html, and supportadmin.html provide administration interfaces for newsletters, email, and support tickets respectively.
The complete Trinity Beast Documentation Library — 44 technical documents, interactive dashboards (analytics + KCC live + translation), and an index page. The index page groups documents by category (Core Reference, Architecture & Infrastructure, Data & Reports, Operations & Lifecycle, Performance). All documents follow the same dark-theme HTML convention with shared docs-common.css and are accessible at cpmp-site.org/docs/.
images/ contains 55+ assets including impact photos, favicons, and QR codes. icons/ has 4 SVG crypto token icons used on the subscription page. videos/ contains 6 MP4 impact videos embedded on category pages. originals/ holds pre-redesign pages for reference only — these are NOT deployed to S3.
Kiro steering files provide persistent project knowledge that is auto-loaded into AI context. Spec files capture iterative feature design with requirements, design documents, and task lists.
.kiro/ ├── steering/ — Persistent project knowledge (auto-loaded into AI context) │ ├── architecture.md — Canonical AWS resource names, infrastructure decisions │ ├── conventions.md — Coding standards, branding, workflow rules │ ├── deployment.md — Exact deployment commands for each component │ └── project-structure.md — File locations and key files to watch │ ├── specs/ — Feature specifications (iterative design docs) │ ├── lrs-report-limit-enforcement/ │ │ ├── requirements.md, design.md, tasks.md │ └── subscription-lifecycle-management/ │ ├── requirements.md, design.md, tasks.md │ └── settings/ └── mcp.json — MCP server configuration
Four markdown files that define the canonical project knowledge. architecture.md lists every AWS resource name, ARN pattern, and infrastructure decision. conventions.md captures coding standards, branding rules, and workflow preferences. deployment.md contains the exact commands for deploying each component. project-structure.md maps file locations and key files to watch across all repositories.
Feature specifications follow a three-document pattern: requirements.md (acceptance criteria), design.md (technical approach), and tasks.md (implementation checklist). Each spec lives in its own directory named after the feature.
All three applications share the same Aurora PostgreSQL database and ElastiCache cluster, accessed via credentials stored in AWS Secrets Manager (trinity-beast-secrets).
LPO Server (main.go) │ ├── Receives price queries (TCP :8080, UDP :2679) ├── WebSocket feeds from 6 exchanges (Coinbase, Bitstamp, Kraken, Gate.io, Crypto.com, OKX) ├── Caches prices in sync.Map (zero-network hot path) + ElastiCache (REST fallback) ├── Writes usage_logs to SQS (fire-and-forget, Lambda consumer writes to Aurora) │ ├── Serves LRS reports (TCP :9090, UDP :2680) ├── Reads usage data from ElastiCache │ ├── Support tickets: stores in Aurora, translates via AWS Translate ├── Emails: multi-lingual SES (12 languages) for support + newsletter welcome ├── /translate endpoint: real-time translation with ElastiCache caching (30-day TTL) │ ├── Webhook Push: outbound price delivery to Associates (UDP + HTTPS) ├── Partner WebSocket: real-time price feed over persistent WS connections └── Publishes 24 runtime telemetry counters to ElastiCache (cluster-wide aggregation) Sync Job (cmd/sync/main.go) │ ├── Triggered nightly by EventBridge at 1 AM EST ├── Reads usage_logs from Aurora ├── Writes to ElastiCache (hashes + sorted sets) ├── Refreshes API keys + app params in ElastiCache └── Prunes data older than 93 days Receipt Lambda (cmd/handler/main.go) │ ├── Called by thank-you pages via API Gateway ├── Reads Stripe checkout session (HTTP) ├── Inserts into Aurora (users, api_keys, transactions) ├── Sends email via SES templates └── Calls LPO Server /admin/invalidate-key for cache busting Queued Writer Lambda (cmd/queued-writer/main.go) │ ├── Triggered by SQS (batch size 100, 5s window) ├── Reads usage log messages from SQS └── Batch inserts into Aurora (usage_logs table)
| Shared Resource | LPO Server | Sync Job | Receipt Lambda |
|---|---|---|---|
| Aurora PostgreSQL | Read/Write (api_keys, usage_logs, application_parameters) |
Read (usage_logs) |
Write (users, api_keys, transactions) |
| ElastiCache (Valkey) | Read/Write (price cache + LRS queries) | Write (usage log hashes + indexes) | — |
| Secrets Manager | Read (trinity-beast-secrets) | Read (trinity-beast-secrets) | Read (trinity-beast-secrets + STRIPE_SECRET_KEY) |
| CloudWatch | Write (TrinityBeast/LPO + TrinityBeast/LRS metrics) | Write (logs only) | Write (logs only) |
SES |
Send (newsletters, support, demo welcome) | — | Send (DonationReceipt, SubscriptionReceipt, DemoWelcome templates) |
| LPO Server API | — | — | POST /admin/invalidate-key (cache busting after new subscriptions) |
Engineering techniques and architectural patterns used across the Trinity Beast platform.
Persistent WebSocket connections to all 6 exchanges provide zero-network-hop price updates. Prices land in a local sync.Map (zero-latency read). REST APIs (Coinbase, Kraken, Bitstamp) serve as fallbacks only when all WS feeds go stale. This eliminates per-request HTTP overhead for the hot path.
Layer 1: sync.Map (in-process, zero-latency). Layer 2: ElastiCache (cross-node, sub-millisecond). Layer 3: REST API call (network, ~50–200ms). Each layer falls through to the next only on miss or staleness. WebSocket feeds continuously populate Layer 1.
Cross-node rate coordination using ElastiCache atomic counters. Each ECS container tracks its own request rate and reads the cluster-wide counter to make local admission decisions. Prevents any single node from consuming disproportionate capacity. Implemented in middleware/adaptive.go.
Price responses are sent to the client immediately after cache/source lookup. Background goroutines then handle usage logging, metrics publishing, cache updates, and rate limit accounting. This minimizes perceived latency — the client gets their price before any bookkeeping happens.
Usage logs are buffered in memory and flushed to Aurora in configurable batches (default 100 rows per INSERT). A background goroutine flushes on batch-full or timer expiry (whichever comes first). This reduces Aurora write IOPS by 100x compared to per-request INSERTs.
The same server binary serves both TCP (HTTP via ALB) and UDP (raw datagrams via NLB) on separate port pairs. LPO: TCP :8080 + UDP :2679. LRS: TCP :9090 + UDP :2680. UDP provides lower latency for high-frequency price consumers.
One Docker image runs all 3 ECS services. The SERVER_TYPE environment variable (APP_SERVER, REPORT_SERVER, APP_REPORT_SERVER) controls which listeners start. This simplifies builds, reduces ECR storage, and ensures all nodes run identical code.
Each subsystem gets its own named logger (e.g., logger.New("CoinbaseWS"), logger.New("Pricing")). All log output includes region, cluster node, module name, and level. Enables precise CloudWatch Logs Insights filtering by module.
GOGC=300 (3x default) trades memory for throughput by reducing garbage collection frequency. Under high load, fewer GC pauses mean more consistent latency. Configurable via environment variable at container level.
SIGTERM triggers an ordered shutdown: stop accepting new connections → drain in-flight requests → flush usage log buffer to Aurora → close database connections → close ElastiCache connections. Prevents data loss during ECS rolling deployments.
The receipt Lambda runs outside the VPC to avoid NAT Gateway costs ($32/month). It calls the LPO server's public /admin/invalidate-key endpoint to bust cached API keys after creating new subscriptions. This saves infrastructure cost while maintaining cache consistency.
The nightly sync job tracks the last-synced timestamp in ElastiCache. On each run, it queries Aurora for only records newer than the high-water mark, avoiding full-table scans. First run (empty cache) loads 93 days of historical data.
LRS report queries generate their own usage logs, enabling meta-analytics: how often each API key queries reports, which report types are most popular, and report generation latency. Implemented in lrs/usagelogger.go.
The LPO server maintains two connection pools: one for the Aurora writer endpoint (INSERTs, UPDATEs) and one for the reader endpoint (SELECTs). This distributes load across Aurora's read replicas and prevents read queries from competing with writes.
The 33 application parameters are cached in ElastiCache as a single hash (app:config). On startup, the server reads from ElastiCache first (fast path). If unavailable, it falls back to Aurora. Parameters are refreshed every 60 seconds. This provides sub-millisecond config reads without hitting the database.
All three projects follow the standard Go project layout:
| Directory | Convention |
|---|---|
cmd/ |
Application entry points. Each subdirectory is a separate binary. The main.go in each is the entry point that gets compiled. |
internal/ |
Private packages. Go enforces that internal/ packages cannot be imported by code outside the parent module. Used for application-specific logic that shouldn't be shared. |
pkg/ |
Public packages. Code here can be imported by other projects. Reserved for shared utilities. |
deployments/ |
Infrastructure-as-code: Dockerfiles, CloudFormation templates, ECS task definitions, SES templates. |
scripts/ |
Operational scripts: database migrations, test runners, load testers. |
configs/ |
Configuration files (YAML, JSON, TOML). Currently application parameters are stored in Aurora's application_parameters table instead. |
tests/integration/ |
End-to-end test suite. Test-only package (no non-test Go files) that boots the real HTTP server against containerized Postgres and Valkey. See 9.1 below. |
test-results/ |
Stress test result documentation and analysis. Contains markdown files documenting performance test runs and rationale. |
go.mod / go.sum |
Go module files. go.mod declares the module path and dependencies. go.sum contains cryptographic checksums for reproducible builds. Never edit go.sum manually. |
The codebase carries three distinct test tiers, each answering a different question. They are complementary, not redundant: a unit test proves a function is correct, an integration test proves the wiring is correct, and a stress test proves the system holds under load.
| Tier | Location | Count | Dependencies | Question It Answers |
|---|---|---|---|---|
| Unit | *_test.go beside each package | 878 across 34 packages | None — pure Go, sqlmock where a DB is implied | Is this function's logic correct? |
| Integration | tests/integration/ | 17 (1 skipped) | Real Postgres 17 + Valkey 9 via Docker | Is the full request path wired correctly? |
| Stress | tests/stress/, cmd/stress/ | Scenario-driven | Live deployed cluster | Does it hold at 746K RPS? |
Every package in the module has a test file. Pure functions and data structures get real logic tests. Integration-heavy packages (database initialization, SQS producers, Stripe handlers) get structural and panic-boundary tests — proving they compile, wire, and fail safely without requiring live infrastructure. No mocking frameworks are used; sqlmock covers the SQL boundary and hand-written fakes cover the rest.
The integration suite starts Postgres and Valkey in Docker, seeds a schema and fixture data, boots the actual gorilla/mux router with a real HandlerDeps, and issues real HTTP requests against it. Nothing is stubbed — the API key travels through Aurora-equivalent validation, the rate limiter allocates a real token bucket, prices resolve from the live L1 sync.Map, and admin queries execute against a real database.
harness_test.go| Responsibility | Implementation |
|---|---|
| Container readiness | TestMain pings Postgres and Valkey with a 15-second retry budget. If either is unreachable it exits 0 with a SKIP notice rather than failing — the suite never breaks a build on a machine without Docker. |
| Schema seed | seedSchema() creates the baseline tables (users, api_keys, application_parameters, usage_logs, exchange_asset_map) then invokes the production handlers.Migrate*() functions — the same idempotent migrations the live server runs at startup. |
| Fixture data | seedTestData() inserts a test user, a free-tier API key, the admin key parameter, EAM rows, and price hashes in Valkey. |
| Server boot | buildTestServer() wires HandlerDeps with the real DB and cache clients, a real RateLimiter, a seeded L1 price cache, and registers public plus admin routes behind the production AdminAuth middleware. Returns an httptest.Server. |
| Request helpers | get(), post(), adminGet(), adminPost() issue real HTTP calls and return a parsed UMEResponse — the 12-field envelope, unwrapped and ready to assert against. |
| Domain | Coverage |
|---|---|
| Health | Envelope structure, all 12 fields present including empty-but-serialized values |
| Price | Missing key → 401, invalid key → 401, missing asset → 400, valid cached asset → 200 with resolved price, multi-asset parsing |
| Search | Short query, empty query, envelope conformance on the Valkey-indexed path |
| Admin | No key → 401, wrong key → 403, config read, /admin/sql executing a real SELECT, /admin/valkey executing a real HGET |
| Support | Ticket creation → 201 with generated ticket number persisted to the database, validation failure → 400 |
| UME contract | Table-driven sweep across four endpoints asserting every envelope field is present and correctly typed |
# Unit tier — no external dependencies, runs anywhere
go test ./...
# Integration tier — containers up, test, containers down
bash scripts/integration-test.sh
bash scripts/integration-test.sh -v # verbose
bash scripts/integration-test.sh -run Health # filter by name
bash scripts/integration-test.sh --keep # leave containers up for debugging
# Integration tier — against already-running containers
go test ./tests/integration/ -v -count=1Container isolation: The test containers bind Postgres to port 5433 and Valkey to 6380 — deliberately off the standard 5432 and 6379 so they never collide with a local development instance. Data lives on tmpfs, so every run starts clean and nothing touches disk.
Connection overrides: The harness reads TEST_PG_HOST, TEST_PG_PORT, TEST_PG_USER, TEST_PG_PASSWORD, TEST_PG_DB, and TEST_VALKEY_ADDR from the environment, falling back to the docker-compose.yml defaults. A CI runner with managed service containers only needs to set those variables — no code change.
Step-by-step instructions for building and deploying each application to its AWS runtime.
The LPO server image is shared by all four ECS services (BeastMain, BeastMirror, BeastLRS, BeastWebhook). One build and push updates all four.
aws ecr get-login-password --region us-east-2 | docker login --username AWS --password-stdin 211998422884.dkr.ecr.us-east-2.amazonaws.comdocker buildx build --platform linux/amd64 --no-cache \
-f trinity-beast-lpo-server/deployments/docker/Dockerfile \
-t 211998422884.dkr.ecr.us-east-2.amazonaws.com/trinity-beast-lpo-server:latest \
--push --provenance=false \
trinity-beast-lpo-server/Key flags: --platform linux/amd64 ensures the image runs on Fargate (even when building on Apple Silicon). --provenance=false prevents multi-arch manifest issues. --no-cache ensures a clean build with latest code changes.
aws ecs update-service --cluster trinity-beast-fargate-cluster \
--service trinity-beast-main-service --force-new-deployment --region us-east-2
aws ecs update-service --cluster trinity-beast-fargate-cluster \
--service trinity-beast-mirror-service --force-new-deployment --region us-east-2
aws ecs update-service --cluster trinity-beast-fargate-cluster \
--service trinity-beast-lrs-service --force-new-deployment --region us-east-2
aws ecs update-service --cluster trinity-beast-fargate-cluster \
--service trinity-beast-webhook-service --force-new-deployment --region us-east-2Each service pulls the :latest image from ECR. The rolling deployment starts a new task, waits for it to pass health checks, then drains the old task. Typically completes in 2–3 minutes per service.
aws ecs describe-services --cluster trinity-beast-fargate-cluster \
--services trinity-beast-main-service trinity-beast-mirror-service trinity-beast-lrs-service \
--region us-east-2 \
--query 'services[*].{name:serviceName,running:runningCount,deployments:length(deployments)}'All three should show running: 1 and deployments: 1 when complete. If deployments: 2, the rollout is still in progress.
curl https://api.cpmp-site.org/health — LPO healthcurl https://api.cpmp-site.org/reports/usage?page_size=1 — LRS health
The sync job runs as a one-off Fargate task, not a persistent service. It's triggered nightly by EventBridge but can also be run manually.
aws ecr get-login-password --region us-east-2 | docker login --username AWS --password-stdin 211998422884.dkr.ecr.us-east-2.amazonaws.comdocker buildx build --platform linux/amd64 --no-cache \
-t 211998422884.dkr.ecr.us-east-2.amazonaws.com/trinity-beast-sync-job:latest \
--push --provenance=false \
trinity-beast-sync-job/The Dockerfile is at the project root (not in a deployments/ subfolder).
aws ecs run-task \
--cluster trinity-beast-fargate-cluster \
--task-definition trinity-beast-sync-job:1 \
--launch-type FARGATE \
--network-configuration '{
"awsvpcConfiguration": {
"subnets": ["subnet-06781ce7266a4b870"],
"securityGroups": ["sg-050b617f93b2388f6"],
"assignPublicIp": "ENABLED"
}
}' \
--region us-east-2No force-new-deployment needed — the task definition points to :latest and pulls fresh on each run.
aws logs tail /aws/ecs/trinity-beast --filter-pattern "Sync" --region us-east-2 --since 5mLook for: Incremental sync complete: N logs loaded and Sync complete in Xms - N logs in ElastiCache.
The Lambda is deployed as a zip file containing a single Go binary named bootstrap.
cd ~/trinity-beast-receipt-lambda
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build \
-ldflags="-w -s" -o bootstrap ./cmd/handler/CGO_ENABLED=0 produces a static binary. -ldflags="-w -s" strips debug info for smaller size. The output must be named bootstrap for the provided.al2023 runtime.
zip -j function.zip bootstrapThe -j flag strips directory paths so bootstrap is at the zip root.
aws lambda update-function-code \
--function-name trinity-beast-receipt \
--zip-file fileb://function.zip \
--region us-east-2Takes effect immediately — no rolling deployment. The next invocation uses the new code.
curl -X POST https://6vz2eswz55.execute-api.us-east-2.amazonaws.com/receipt \
-H "Content-Type: application/json" \
-d '{"session_id":"test","type":"donation"}'Expected response: {"success":false,"message":"Failed to read payment session"} — confirms the Lambda is running and reachable. A real Stripe session_id is needed for a full test.