Skip to content

2001105254-netizen/RacePulsePH / .agents/skills/racepulse-resilience-patterns

racepulse-resilience-patterns

Verified

Design and verify RacePulsePH timeouts, retries, idempotency keys, webhook deduplication, offline scan queues and backpressure across Cloud Functions, PayMongo, SMTP and the LAN server. Use when editing network calls, webhooks, background queues or RFID event ingestion.

RacePulse resilience and fault-tolerance patterns

Keep registrations, payments, emails and race-day timing splits reliable when external networks slow down, retry or drop out. Covers functions/index.js, functions/auth-api.js, functions/account-security.js, server.ts and src/lib/offlineScanQueue.ts.

Load with: racepulse-access. Rules upheld: C-2, C-4, C-5, R-02, R-35, R-36. Detail: resilience patterns and repo mapping.

Checklist

CheckReasonEvidence
Enforce rate limits and Retry-After headers on code and auth endpoints (functions/account-security.js, functions/auth-api.js)Stops retry storms and abuse while telling the client exactly how long to waitInspect AccountError retryAfter handling in functions/account-security.js and functions/auth-api.js
Set explicit timeouts on outbound network and SMTP calls (AbortSignal.timeout(8000) in server.ts, 15000ms/30000ms in functions/auth-api.js)Prevents hung sockets from exhausting Function or LAN server concurrencyInspect fetch timeout in server.ts line 182 and nodemailer.createTransport timeouts in functions/auth-api.js line 30
Make checkout creation and webhook processing idempotent (Idempotency-Key: paymentId, 30-minute pending session reuse, payment.status === 'paid' guard)Duplicate clicks or PayMongo webhook retries must never double-charge or issue two bibsInspect createCheckout lines 170 to 209 and handleWebhook lines 268 to 308 in functions/index.js
Invalidate failed outbound deliveries safely without clobbering newer requests (functions/account-security.js lines 76 to 79)If SMTP fails, the user must be able to retry without a stale challenge blocking themInspect the compensation transaction in functions/account-security.js
Buffer offline timing scans in src/lib/offlineScanQueue.ts and re-verify permissions before replaying on reconnect (online, focus, 12s interval)Race-course checkpoints often lose mobile signal; scans must persist locally and replay safelyInspect useOfflineScanQueue in src/lib/offlineScanQueue.ts
Retain raw RFID bridge events in server.ts (local_rfid_events.json) across a 12-hour recovery window without dropping high-volume finish burstsPack finishes generate rapid EPC bursts that must survive browser refreshes or server restartsInspect pruneRfidEvents and saveRfidEventsDB in server.ts lines 132 to 150

Stack mapping

  • Message queues and Dead Letter Queues map to useOfflineScanQueue (localStorage key racepulse_pending_chip_reads_v2:${uid}:${raceId} with queueError hold-for-review state) and local_rfid_events.json in server.ts.
  • Webhooks map to POST /webhooks/paymongo in functions/index.js.

Not covered

  • Firestore transaction locking and bib counter serialization belong to racepulse-data-integrity.
  • Multi-hour disaster recovery and clock precision belong to racepulse-reliability-dr.

Verify

  1. Run npm run lint and npm run verify:rbac (which exercises duplicate requests and offline replay checks).
  2. Output the PASS/FAIL report with evidence for every network boundary touched.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall