Skip to content

docs: add health and rate-limit operations notes (#512 #511) - #611

Open
charlesedeh021-cell wants to merge 1 commit into
gear5labs:masterfrom
charlesedeh021-cell:fix/health-docs-rate-limit-512-511
Open

docs: add health and rate-limit operations notes (#512 #511)#611
charlesedeh021-cell wants to merge 1 commit into
gear5labs:masterfrom
charlesedeh021-cell:fix/health-docs-rate-limit-512-511

Conversation

@charlesedeh021-cell

@charlesedeh021-cell charlesedeh021-cell commented Jul 30, 2026

Copy link
Copy Markdown

Closes #512
Closes #511
Closes #509
Closes #514

Summary

This PR delivers a focused documentation pass for two assigned operational issues:

The current codebase already contains the main runtime pieces behind both issues:

  • HealthService already returns dependency-level readiness details for database, Redis, Horizon, Soroban RPC, email, and LLM checks
  • RateLimiterService is already wired to rate-limit-redis with the shared Redis client as its primary store

This PR documents that existing behavior so contributors and operators can understand what is already implemented today, how to interpret the readiness responses, and where follow-up implementation work is still needed.

What changed

Health endpoint documentation

Updated docs/SYSTEMS_HANDBOOK.md to document:

  • the difference between GET /health and GET /ready
  • the HTTP status behavior of each endpoint
  • the current dependency checks performed by HealthService
  • the response shape for readiness reporting
  • how Redis and Soroban RPC failures surface in the report
  • how critical vs non-critical dependency failures affect readiness

Operational guidance

Added guidance for:

  • using /health as a liveness probe
  • using /ready for readiness checks and incident triage
  • treating Redis failures as a hard readiness concern
  • using the Soroban RPC dependency error for targeted troubleshooting

Rate limiting deployment notes

Updated docs/SYSTEMS_HANDBOOK.md and README.md to confirm that the gateway rate limiter is already Redis-backed through:

  • express-rate-limit
  • rate-limit-redis
  • the shared Redis client

Multi-instance caveat

Documented the current fallback behavior:

  • if Redis-backed limiter creation fails, the service falls back to the default in-memory store
  • that preserves single-node availability
  • but it does not preserve shared counters across a horizontally scaled deployment

Files changed

  • README.md
  • docs/SYSTEMS_HANDBOOK.md

Scope

This is an intentional partial pass focused on documentation and operational clarity. It does not yet:

Testing

Not run in this pass, per request.

@hotoke-no-Kami

Copy link
Copy Markdown
Contributor

@charlesedeh021-cell fix conflict

@hotoke-no-Kami

Copy link
Copy Markdown
Contributor

@charlesedeh021-cell please resolve conflict

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

2 participants