Architecture deep-dive · 2026-05-15

Inventory Search & Indexing

Three-service pipeline: bot aggregation → compressed parsing → OpenSearch blue/green indexing

1. At-a-glance

2. Purpose & boundaries

3. Process / runtime model

tradeit-inventory-server (sinvbot + cinvbot)

Container: Docker --network host · Max-memory restart: 10 GB · Staging: ec2-63-32-135-112

tradeit-inventory-parser

4. Architecture (data flow)

graph LR
  classDef gap fill:#2a1218,stroke:#f43f5e,stroke-width:2px,color:#fecdd3
  classDef warn fill:#2a1f0e,stroke:#f59e0b,stroke-width:2px,color:#fde68a
  classDef ok fill:#0e2a1e,stroke:#10b981,stroke-width:2px,color:#a7f3d0
  classDef hi fill:#1e2438,stroke:#a855f7,stroke-width:2px,color:#e9d5ff

  subgraph "tradeit-tradebot-server"
    BOT["~400 bots\nwrite loop"]
  end

  subgraph "tradeit-inventory-server"
    SINV["sinvbot\nport 3000"]
    CINV["cinvbot\nport 3001"]
  end

  subgraph "tradeit-inventory-parser"
    CTRL["InventoryController\nGET /index/:gameId"]
    SVC["InventoryService\nparseData()"]
    OS_SVC["OpenSearchService\nbulk + alias swap"]
  end

  subgraph "External marketplaces"
    HALO["HaloSkins API\ncs2dt.com /v2"]
    UU["Uuskins API\n/v1/market/items"]
  end

  REDIS[("Redis\nElastiCache")]
  MYSQL[("MySQL 8\nAurora")]
  OS[("OpenSearch\nalias: inventory_730...")]
  STEAM["Steam\nCommunity API"]
  SCRAPER["ScraperAPI\nproxy"]
  CF["Cloudflare\ncache purge"]
  SLACK["Slack\n#tradeit-builds"]

  BOT -- "sinv:{n}:compressed" --> REDIS
  REDIS -- "batch mGet sinvKeys" --> SINV
  MYSQL -- "items / item_prices\nsale_offers" --> SINV
  SINV -- "sinv, globalItemInfo\nupdatedPrices, stickerPrices" --> REDIS

  SINV -- "GET /sinv-merged/:gameId" --> CTRL
  HALO --> CTRL
  UU --> CTRL
  MYSQL -- "collections, item_types\nconfigurations, sale_offers" --> SVC
  REDIS -- "indexLaneLock:{gameId}\nstickerPrices, charmPrices" --> CTRL
  CTRL --> SVC
  SVC --> OS_SVC
  OS_SVC -- "bulk index + alias swap" --> OS
  OS_SVC --> CF
  OS_SVC --> SLACK

  STEAM --> CINV
  SCRAPER --> CINV
  MYSQL -- "bot_users, collections\nitem_types, configurations" --> CINV
  REDIS -- "updatedPrices\nrate-limit keys" --> CINV

  class OS_SVC ok
  class HALO,UU hi
  class CINV,STEAM,SCRAPER warn

5. Inputs & outputs

sinvbot

cinvbot

inventory-parser

6. Redis surface

7. MySQL surface

TypeORM synchronize: false in inventory-parser — migrations are manual. Driver: mysql2 3.12.0.

8. OpenSearch surface

Index naming

Generation strategy (blue/green)

Each alias points to one of two generations (incremental integer suffix, e.g., _0 / _1, colloquially called "rick/morty"). Per cycle:

1. Query current alias target → get generation N
2. Select generation N+1 as write target; create index if missing (openSearch.service.ts:398)
3. Disable refresh interval on N+1 (setRefreshInterval(-1), line 403)
4. Bulk-index all docs with exponential backoff
5. Restore refresh interval (line 408)
6. Atomically swap alias from N → N+1 (replaceAliasForIndex, line 414)
7. Delete old generation N index

Bulk pipeline parameters

Two OpenSearch clients

9. Async continuations

Indexing cron (external cron server → HTTP)

sinvbot internal timers

cinvbot internal timers

cinvbot Bull queues

Lane lock lifecycle

1. Acquire: SET indexLaneLock:{gameId}:{laneKey} {uuid} EX 900 (inventory.controller.ts:135)
2. Renewal: every 450 s (half TTL) while indexing
3. Release: EVAL compareAndDeleteScript — only deletes if UUID matches (prevents stale release)
4. Conflict → 409 CONFLICT; cron retries next tick

10. Configuration flags & guards

Database-backed (configurations table — ConfigurationKey enum)

Source: src/models/enums/ConfigurationKey.ts

Key env vars (static)

Hardcoded guards

• Lane lock TTL: 900 s — inventory.controller.ts:30
• Lock renewal interval: 450 s (half TTL)
• Bulk retry limit: 3 — openSearch.service.ts:20
• Halt on bulk failures: >30% permanent → Slack alert + halt — openSearch.service.ts:430
• Slow-run Slack alert: 3.5 min — inventory.controller.ts:98

11. Failure modes

12. Observability

• Logging: @zengamingx/logger (pino-based) in inventory-server; NestJS ClassWithLogger mixin in parser. no-console enforced; structured JSON to stdout.
• Slack #tradeit-builds: CircleCI build failures; slow-run alert (>3.5 min, inventory.controller.ts:98); bulk failure alert with stack (openSearch.service.ts:383); exception alert with instance info (inventory.controller.ts:105).
• PM2: Max-memory restart at 10 GB (sinvbot/cinvbot); 2.6 GB heap cap (parser).
• Cronitor: No monitor wired to inventory-parser cron endpoints — missed cycles only surfaced by Slack.
• Datadog / New Relic: Not confirmed wired to inventory-server or inventory-parser — verify with infra team.

13. Code map (file:line)

tradeit-inventory-server

tradeit-inventory-parser

14. Open questions

Generated 2026-05-15 · tradeit.gg engineering · repos: tradeit-inventory-server, tradeit-inventory-parser