docs: add Redis usage and caching architecture reference

[dhikbass]

Overview

Adds backend/docs/redis.md, a reference cataloguing every Redis consumer in the backend: the keys it owns, their TTLs, the commands used, and exactly what degrades when Redis is unavailable. It also documents the Redlock usage, the key-namespace convention for new features, the connection lifecycle, and a troubleshooting table.

While writing it against the source, two assumptions in older notes turned out to be wrong and are corrected in the doc: the Socket.IO message queue is an in-process Map (not Redis), and driver availability claims are atomic MongoDB findOneAndUpdate calls (not Redis keys).

Related Issue

Closes #270

Changes

• [ADD] backend/docs/redis.md — Redis usage and caching architecture reference.
  • Consumer inventory: ETA cache, idempotency store, Redlock escrow/assignment locks, driver-location dedup/last-seen, admin dashboard cache.
  • Redlock: settings, the two locked operations, TTL/retry semantics, and the single-node caveat.
  • Per-subsystem failure behaviour (fail-open caches/dedup, fail-closed locks, Mongo fallback for idempotency).
  • Key-namespace convention, config reference, troubleshooting table, and an "adding a new consumer" checklist.

Documentation-only change. No runtime behaviour is modified.

Verification Results

The change is a single new Markdown file; it is not read by ESLint, tsc, or Jest, so no runtime check is affected. Every source file cited in the doc was confirmed to exist, and every key/TTL/command was read from the implementation rather than inferred.

Baseline status of the repository at the time of writing (unchanged by this PR, reproduced on a clean clone before adding the file):

pnpm install --frozen-lockfile     # succeeds
pnpm run lint                      # 14 pre-existing errors, all in src/services/poolingService.ts, src/config/stellar.ts, src/controllers/poolingController.ts, src/routes/poolingRoutes.ts
pnpm run build                     # pre-existing failures: duplicate `env` imports (e.g. src/server.ts, src/services/etaCacheService.ts) and missing names (validateRequest, authService, TEST_UNLIMITED_MAX, SOROBAN_RPC_RETRY_JITTER_RATIO)
pnpm exec jest --ci                # 33/64 suites pass; integration suites that need Redis/Mongo time out

Reviewers should run the same commands; this PR does not change any of those results. I did not fix the unrelated baseline errors because the issue is scoped to documentation.

Acceptance criterion	Status	Evidence
Document every Redis consumer with key patterns and TTLs (cache, lock, queue keys)	✅	backend/docs/redis.md → "Consumer inventory" table
Document Redlock usage: operations, lock TTLs, retry behaviour when a lock is held	✅	"Redlock distributed locking" section (escrow:release:<id>, assignment:delivery:<id>)
Document failure behaviour per subsystem (idempotency→Mongo, no caching, fail-safe vs fail-open)	✅	"Failure behaviour per subsystem" section
Define a key-namespace convention (prefix:entity:id:field)	✅	"Key namespace convention" section
Document initializeRedis/disconnectRedis lifecycle and connection settings	✅	"Connection lifecycle and settings" section
Include a troubleshooting table (connection refused, lock timeout, memory eviction)	✅	"Troubleshooting" section
Strict layered architecture / DB-only data / env credentials / API versioning	N/A	Documentation-only; no controller, service, model, or endpoint is added or changed
PR content includes Closes #<issue_id> and a work summary	✅	This body

Template reference: stellarspend/stellarspend-contracts#1055

[drips-wave]

@dhikbass Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[Tybravo]

@dhikbass
Well-done job