ENGINEERING · CROSS-CUTTING SUBSYSTEM · 10-05-2026

Redis Architecture

Cross-cutting cache, coordination bus, and queue backbone — every namespace, TTL, pub/sub channel, Bull queue, lock pattern, and the cross-repo handoffs that bind the platform together.

1. At-a-glance

2. Purpose & boundaries

Redis serves four distinct responsibilities that share one ElastiCache instance:

1. L2 cache — write-through caches with TTLs from 5s (rate limits) to 365d (AI-generated SEO), backed by MySQL/OpenSearch source-of-truth.
2. Coordination bus — pub/sub channels carry trade-state events, bot commands, and item-reservation notifications between tradeit-backend, tradeit-socket-server, and the bot fleet.
3. Bull queue backbone — tradeitQueue (main work) and tradeitScreenshotQueue (image processing) persist job state in the bull:* keyspace.
4. Distributed coordination — atomic locks (SET NX), inventory mirrors (sinv:*/cinv:*), rate-limit counters.

3. Process / runtime model

3.3 Connection footprint at steady state

With ~400 bot workers + 4-8 backend PM2 workers + socket-server replicas, expect 500–700 client connections at peak.

4. Architecture

graph LR
  subgraph "tradeit-backend"
    BE_API["controllers / services
(70+ key namespaces)"]
    BE_CFG["configurationService.js
L1 60s + L2 180s"]
    BE_RES["reserveAssetRedis.js
list-based reservation"]
    BE_TRADE["tradeRedis.js
locks + pub/sub"]
    BE_BULL_MAIN["mainQueue.js
tradeitQueue (Bull)"]
    BE_BULL_SS["screenshotQueue.js
tradeitScreenshotQueue (Bull)"]
  end

  subgraph "Redis (ElastiCache)"
    R_KV[("KV namespaces
cinv:* sinv:* configuration:*
insight_* invsize* bot_acc_info ...")]
    R_LIST[("Lists
reserved-assets_*
reserved-assets_ttl_*")]
    R_PUBSUB[("Pub/Sub
tradestate · bot <id>
itemReserved · image · canceledtrades")]
    R_BULL[("Bull keyspace
bull:tradeitQueue:*
bull:tradebotQueue:*")]
  end

  subgraph "tradeit-socket-server"
    SOCK_SUB["sub.subscribe()
tradestate · canceledtrades
itemReserved"]
    SOCK_IO["io.to(steamId).emit(...)"]
  end

  subgraph "tradeit-tradebot-server (~400 bots)"
    BOT_KV["invsize* · pollData
botRefreshToken · inspectResult"]
    BOT_SUB["sub.subscribe('bot <id>')"]
    BOT_PUB["publish 'tradestate'
publish 'finishedtrades'
publish 'canceledtrades'"]
  end

  subgraph "tradeit-admin-backend"
    ADMIN_CFG["configurationService.ts
writes configuration:*
(no DEL on edit — gap)"]
  end

  subgraph "tradeit-inventory-parser"
    PARSE_LOCK["indexLaneLock:*
10-min alias-swap"]
  end

  BE_API --> R_KV
  BE_CFG --> R_KV
  BE_RES --> R_LIST
  BE_RES --> R_PUBSUB
  BE_TRADE --> R_KV
  BE_TRADE --> R_PUBSUB
  BE_BULL_MAIN --> R_BULL
  BE_BULL_SS --> R_BULL

  ADMIN_CFG -.->|"NO INVALIDATION"| R_KV
  PARSE_LOCK --> R_KV

  BOT_KV --> R_KV
  BOT_PUB --> R_PUBSUB
  BOT_SUB --> R_PUBSUB

  R_PUBSUB --> SOCK_SUB
  SOCK_SUB --> SOCK_IO

  classDef gap fill:#2a1218,stroke:#f43f5e,stroke-width:2px,color:#fecdd3
  class ADMIN_CFG gap

The dashed NO INVALIDATION edge is the single most damaging cache-coherency gap on the platform. tradeit-admin-backend writes configuration:<key> on admin edits but never publishes a DEL or pub/sub event, so tradeit-backend instances continue serving stale values for up to 180s (per-key TTL) or 360s worst-case for category-bundle reads. See Platform Configuration §6.

5. Inputs & outputs

5.1 Connection ingress

5.2 Egress (consumers)

• HTTP responses — every cache hit on getValueByKey, getCachedInventory, getInsightChart shaves a MySQL/OpenSearch round-trip from the request path.
• Socket.IO emits — tradeit-socket-server translates tradestate and itemReserved pub/sub messages into Socket.IO events scoped to the user's steamId room (src/socket.ts:164).
• Bot daemon — bot workers subscribe to bot <botId> and act on withdraw, sale, checkSteamGuard commands.

5.3 No HTTP control plane

There is no admin HTTP endpoint for invalidating Redis keys directly. Cache busting happens through service-level redis.del(key) calls embedded in write paths, Bull job removeReserve triggering lRem on the reservation lists, and the daily 01:00 UTC cron sweeping insight_keys:<gameId>.

6. Keyspace catalog

Grouped by namespace. TTLs are in seconds unless noted. Source paths rooted at tradeit-backend/ unless qualified.

6.1 Inventory & catalog

6.2 Bot fleet state cross-repo: backend reads, tradebot-server writes

6.3 Trades & reservations

6.4 Configuration cache owned by Configuration deep-dive

See Platform Configuration for the L1+L2 read path, the no-pub/sub-invalidation gap, and the 11 config categories.

6.5 Marketplace, billing, identity

6.6 Coupons, rate limits, server status

6.7 SEO & insights

6.8 Admin operations

6.9 Locks (cross-cutting pattern)

6.10 Bull keyspace

Bull stores its job state under the bull:<queueName>:* prefix automatically. Keys observed: id, wait, active, completed, failed, delayed, paused, priority, jobs:<id>, events, meta. No application code touches these directly; manage exclusively via the Bull API.

7. MySQL coupling

Redis keys most tightly coupled to MySQL:

Redis is always cache or coordination, never the source of truth, except for ephemeral state (locks, rate limits, pub/sub-driven flows).

8. OpenSearch coupling

Redis indirectly affects OpenSearch through the reservation flow:

• reserved-assets_${appId} list is read by tradeit-inventory-parser during the 10-min alias-swap to filter the inventory snapshot. The new design replaces this dependency with an indexed reservedUntil field on the inventory document itself (see 2026-05-10-reserved-assets-os-field-design.md), reducing the keyspace dependency.

No direct Redis ↔ OpenSearch sync. OpenSearch indexes are rebuilt from MySQL and Redis is consulted as an overlay during query construction.

9. Bull queues / cron / pub-sub continuations

9.1 Bull queues

Init guard (mainQueue + screenshotQueue): if (process.env.TI_ENV !== 'production' && Number(process.env.ENABLE_QUEUE) !== 1) return — production always enabled; non-prod is opt-in via ENABLE_QUEUE=1.

9.2 Cron handoffs that mutate Redis

9.3 Pub/sub channels (the coordination spine)

10. Configuration flags & guards

11. Failure modes & runbook

12. Observability

• Datadog APM — dd-trace v5.84.0 auto-instruments redis calls (server/lib/tracer.js, imported first in server/index.js). All GET/SET/PUBLISH show as redis.command spans on the request waterfall.
• Pino logger — redis.js:30 logs every connect/error event with the host context, tagged module: 'redis'. Search Datadog logs: service:tradeit-backend module:redis.
• No custom metrics — no Prometheus exporter or Datadog statsd metric for hit/miss ratios. Hit-rate is inferred from request-trace cache spans.
• ElastiCache CloudWatch — provider-level EngineCPUUtilization, DatabaseMemoryUsagePercentage, CurrConnections, Evictions. No alarms tracked in tradeit-infra.
• Bull dashboard — no Bull Arena/UI deployed; queue inspection requires bull CLI or ad-hoc Redis inspection.

13. Code map (file:line)

13.1 Connection lifecycle

13.2 Helpers (tradeit-backend/server/redis/)

13.3 Service / controller / queue / repo touch-points

13.4 Cross-repo

14. Open questions & known gaps

• OPEN itemsMeta writer — read by inventory-parser at src/modules/inventoryIndex/inventory.controller.ts:112, 477 but the writer was not located. Confirm whether legacy tradeit-scripts-java or tradeit-backend writes it.
• OPEN usercount writer — serverStatusService.js reads usercount but no SET/SETEX was found. Likely external (steam-pricing-scraper or stats-manager).
• OPEN finishedtrades / steamDown consumers — published by tradebot-server but no subscriber found in tradeit-socket-server or tradeit-backend. Possibly legacy.
• OPEN Inventory compression scheme — sinv:${botIndex}:compressed and cinv:*:compressed use compression; the scheme (zstd? gzip?) not located. Decompress cost not currently observed.
• OPEN Bull job retention — no removeOnComplete set. Need ticket: removeOnComplete: { age: 24h, count: 10000 }, removeOnFail: { age: 7d }.
• OPEN stats-manager TTL gap — configuration:* overwrites every 5 min with no TTL. If stats-manager dies mid-cycle, keys persist indefinitely with the last value. Cross-check with backend updateValueByKey DEL semantics.
• OPEN No graceful Redis-down mode — attachRedis returns HTTP 500. Consider read-only fallbacks (serve stale local state, queue writes).
• OPEN No Datadog dashboard for Redis. Hit-rate per namespace, pub/sub publish QPS, Bull throughput, eviction count, connection count.
• OPEN ElastiCache IaC — provisioning is not in tradeit-infra. Either import existing cluster into Terraform or document the manual setup.
• OPEN Reserved-asset list migration — reserved-assets_* and reserved-assets_ttl_* lists are slated for removal once the OS-field design ships. Track key cleanup as a step in that rollout.

Related deep-dives: Platform Configuration · OpenSearch Patterns · Trade Lifecycle