docs: add comprehensive rate limiting documentation and decorator usage notes

- Create complete rate limiting documentation (docs/usage/rate-limiting.md)
  - Overview of rate limiting features and backends
  - Configuration guide for in-memory and Redis backends
  - Usage examples and best practices
  - Security considerations and troubleshooting
  - 541 lines of comprehensive documentation

- Add rate limiting feature to README.md and docs/index.md
  - Describe conservative limits for auth endpoints
  - Mention both in-memory and Redis backend support
  - Note HTTP 429 responses with Retry-After header
  - Highlight Prometheus metrics integration

- Add decorator ordering notes to both caching and rate limiting docs
  - Document correct order when using both decorators
  - Explain security rationale (rate limit before cache)
  - Provide code examples with both decorators
  - Cross-reference between documentation pages

- Update mkdocs.yml navigation
  - Add "Rate Limiting and Security" before Metrics section
  - Position logically in Usage section

All documentation follows existing style and format.

Author: seapagan

README.md

@@ -128,6 +128,12 @@ following advantages to starting your own from scratch :
   collection tracks HTTP performance (requests, latency, in-flight), business
   metrics (auth failures, API key usage, login attempts), and custom
   application metrics. Exposed via `/metrics` endpoint when enabled.
+- **Rate limiting** for authentication endpoints to protect against brute force
+  attacks, spam, and abuse. Disabled by default, supports both in-memory (for
+  single-instance) and Redis (for multi-instance) backends. Conservative limits
+  applied to login (5/15min), registration (3/hour), password recovery (3/hour),
+  and other auth routes. Returns HTTP 429 with `Retry-After` header when limits
+  exceeded. Violations tracked via Prometheus metrics when enabled.
 - **A command-line admin tool**. This allows to configure the project metadata
   very easily, add users (and make admin), and run a development server. This
   can easily be modified to add your own functionality (for example bulk add

docs/index.md

@@ -77,6 +77,12 @@ following advantages to starting your own from scratch :
   collection tracks HTTP performance (requests, latency, in-flight), business
   metrics (auth failures, API key usage, login attempts), and custom
   application metrics. Exposed via `/metrics` endpoint when enabled.
+- **Rate limiting** for authentication endpoints to protect against brute force
+  attacks, spam, and abuse. Disabled by default, supports both in-memory (for
+  single-instance) and Redis (for multi-instance) backends. Conservative limits
+  applied to login (5/15min), registration (3/hour), password recovery (3/hour),
+  and other auth routes. Returns HTTP 429 with `Retry-After` header when limits
+  exceeded. Violations tracked via Prometheus metrics when enabled.
 - **A command-line admin tool**. This allows to configure the project metadata
   very easily, add users (and make admin), and run a development server. This
   can easily be modified to add your own functionality (for example bulk add

docs/usage/caching.md

@@ -212,6 +212,24 @@ async def expensive_query(request: Request, response: Response):
     The `@cached()` decorator MUST be placed AFTER the route decorator
     (`@router.get()`, etc.) to work correctly.
 
+!!! tip "Using with Rate Limiting"
+    When using both `@cached()` and `@rate_limited()` decorators together,
+    place rate limiting first for security. Rate limits should be checked
+    before returning any response (including cached ones):
+
+    ```python
+    from app.cache import cached
+    from app.rate_limit.decorators import rate_limited
+
+    @router.get("/endpoint")
+    @rate_limited("10/minute")  # Check rate limit first
+    @cached(expire=300)         # Then check cache
+    async def handler(request: Request, response: Response):
+        return data
+    ```
+
+    This ensures rate-limited users don't bypass limits via cached responses.
+
 ### With Custom Key Builders
 
 For user-scoped caching, use built-in key builders: