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

Platform Configuration

Runtime configuration system — the configurations table, its caches, every consumer service, the admin edit flow, and the canonical key registry.

§1 At-a-glance

§2 Purpose & boundaries

The line between "platform config" and "feature flag" is fuzzy — this table holds both. Anything an admin/ops user can flip without a deploy lands here.

§3 Process / runtime model

There are two independent service implementations that read/write the same MySQL table and share the same Redis key namespace:

Both services therefore share the L2 cache key namespace but have no coordinated invalidation. See §9 and §11.

3.3 Where the services run

• tradeit-backend runs on every backend EC2 instance — multiple Node.js processes per host, each with its own L1.
• tradeit-admin-backend runs as a single deployment fronting the Vue admin SPA.

§4 Architecture

graph LR
  AdminUI["tradeit-admin Vue / Configuration.vue"] -->|"PATCH /configurations/:id"| AdminBE["tradeit-admin-backend / controllers/configuration.ts"]
  AdminBE -->|"prisma.configurations.update"| MySQL[("MySQL steamarbitrage.configurations")]
  AdminBE -->|"emit updated -> activityListeners"| ActivityLog[("admin_activities")]
  AdminBE -.->|"NO INVALIDATION"| Redis[("Redis configuration:key + configurationCategory:cat:flag")]

  Backend["tradeit-backend ConfigurationService"] -->|"L1 miss -> GET configuration:key"| Redis
  Redis -.->|"L2 miss after 180s TTL"| Backend
  Backend -->|"SELECT * FROM configurations"| MySQL
  Backend -->|"SETEX configuration:key 180"| Redis

  Bootstrap["GET /api/v2/configuration"] -->|"getGlobalConfigs useHashKey=true"| Backend
  Consumers["20+ consumer modules"] -->|"getValueByKey / getValuesByKeys"| Backend

  Breaker["userLimitationService.js / tradeOutSummaryService.js"] -->|"updateValueByKey on anomaly"| Backend
  Backend -->|"DEL configuration:key + UPDATE row"| MySQL
  Backend -->|"DEL configuration:key"| Redis

§5 Inputs & outputs

5.1 HTTP — tradeit-backend (public/frontend)

Source: server/routes/configuration.js + server/controllers/configuration.js.

5.2 HTTP — tradeit-admin-backend (admin CRUD)

All four guarded by [isLoggedIn, isAdmin]. Source: routes/configurations.ts:11-14, mounted at routes/index.ts:75.

5.3 Internal writes — circuit breakers

Two services in tradeit-backend write to configurations via updateValueByKey without an admin in the loop:

• server/service/userLimitationService.js:357 — sets tradesDisabled=1 when limit anomalies trip
• server/service/userLimitationService.js:377 — sets disableOtherGames=1 for non-CSGO surges
• server/service/userLimitationService.js:398 — sets largeTradesDisabled=1 for large-trade anomalies
• server/service/tradeOutSummaryService.js:70 — sets tradesDisabled=1 from outflow summary checks

These are self-flipping kill switches: code disables a feature, ops admin manually re-enables it after investigation. They DO correctly invalidate L1 and L2 (DEL configuration:<key>) — but the category cache configurationCategory:GLOBAL:* is not invalidated.

§6 Redis surface

§7 MySQL surface

7.1 Table

CREATE TABLE steamarbitrage.configurations (
  id INT UNSIGNED NOT NULL AUTO_INCREMENT,
  category VARCHAR(15) NULL,
  `key` VARCHAR(255) NULL,
  value VARCHAR(2000) NULL,
  type VARCHAR(100) NULL,        -- 'string' | 'int' | 'tinyint'
  key_hash VARCHAR(10) NULL,     -- short hash alias for compact frontend payloads
  created_at DATETIME NOT NULL,
  updated_at DATETIME NOT NULL,
  PRIMARY KEY (id)
);

7.2 Indexes

SHOW INDEX FROM steamarbitrage.configurations returns only the PRIMARY KEY on id. Despite the unique-by-name read pattern (getByKey, getByKeyAndCategory), there is no MySQL-enforced UNIQUE on key or (category, key). App-layer uniqueness is enforced by tradeit-admin-backend/repositories/configurationRepo.ts:36.

7.3 Categories (live, 222 rows)

7.4 key_hash column

key_hash is a 6-8 char hex string stored alongside each row, used by getConfigsByCategory(category, useHashKey=true) to produce a compact response (frontend never sees the full key name). Some rows have key_hash = NULL (e.g., all of LIMITS, instantSellPriceAdjustPercent) — those rows will not surface in hash-keyed payloads. Hash is stored, not computed at runtime; admin-backend does not auto-fill it on insert/update — must be set manually or via SQL seed.

§8 OpenSearch surface

N/A — reason: Configuration values are not indexed in OpenSearch. The configurations table is the source of truth and Redis is the only secondary store. There is no full-text search requirement; admin UI does in-memory filtering on the full getAll response.

§9 Async continuations

The cache invalidation gap is the only async behavior worth calling out — and it is itself the absence of an async path.

• Admin update in tradeit-admin-backend writes MySQL, emits an in-process MainService.emit('updated', ...) for admin_activities audit logging, then returns. No Redis DEL. No pub/sub publish. No HTTP callback to tradeit-backend.
• tradeit-backend has no subscriber for config invalidation messages. Each process drains its L1 on the 60s timer and re-reads from L2 (which is also stale until 180s TTL expires).

Worst case for a GLOBAL admin edit landing on a logged-in user's screen:

1. Admin clicks save at T+0.
2. MySQL row updates immediately.
3. Per-key configuration:<key> cache stays stale until T+180s (no DEL).
4. Category cache configurationCategory:GLOBAL:1 stays stale until its own T+180s window expires.
5. Each backend process's L1 is at most 60s stale relative to its own L2 view.

End-to-end visibility of an admin edit on the /api/v2/configuration bootstrap response: up to 180s in the typical case, longer if the category cache was warmed just before the edit.

The internal circuit-breaker writes (updateValueByKey from userLimitationService / tradeOutSummaryService) DO correctly DEL the per-key cache, so a self-flip propagates to other backend instances within 60s — but the category cache remains stale up to 180s here too.

§10 Configuration registry

Every key in the live configurations table grouped by category. Sensitive values are marked REDACTED. Live values pulled from analytics replica snapshot 2026-04-29. Most numeric currency values are stored in cents (the platform's internal money unit).

ANOMALY (12)

CRYPTO (1)

GLOBAL (77) — surfaced via GET /api/v2/configuration

Two-column listing for compactness. Type column shows the stored type field; (null) = type is NULL in DB (admin-backend skips type-cast for these).

Note: a handful of GLOBAL rows have type = NULL (e.g., enableBundle, enableGeoIpLangCurrencyAuto, qaAllowedUserIds). The TS update validation in tradeit-admin-backend/controllers/configuration.ts will pass any value through for these rows because the type-cast switch falls to default.

ITEMS (1)

LIMITS (3) — hard hourly outflow caps

PRICING (15)

SALE (3)

STRIPE (2)

SYSTEM (98) — backend runtime toggles, kill switches, fleet sizing

Two-column listing for compactness.

TRADEBOT (1)

USER (9) — tier limits

Total registered keys: 12 + 1 + 77 + 1 + 3 + 15 + 3 + 2 + 98 + 1 + 9 = 222 (matches SELECT COUNT(*) FROM configurations).

§11 Failure modes

§12 Observability

There is no metric on cache hit rate, TTL miss rate, or per-key read frequency. A consumer reading tradesDisabled 1000x/sec hits L1 99%+ of the time, but this is invisible without bespoke logging.

§13 Code map

All file:line citations validated against current HEAD on 2026-05-10.

Repo SHAs (current HEAD): tradeit-backend a99bf216 · tradeit-admin-backend 6df567ed · tradeit-admin a2e94cff

Schema / repository

Service layer

Routes / controllers

Admin UI

Consumer modules (selected)

Full list (40+ citations) in the wiki source. Highlights below.

Canonical key enum

§14 Open questions

The Task 5 spelunk left 7 open questions; Task 6 resolved 6 of them. The remaining one is tracked.

Generated 10-05-2026 · tradeit.gg engineering