middleware/codemap.md

# backend/middleware/

## Responsibility
Provides role-adjusted request rate limiting for the FastAPI backend through `rate_limiter.py` and its package-level exports.

## Design
- `MathPulseLimiter` wraps SlowAPI `Limiter` using in-memory storage and Firebase UID keys; unauthenticated requests key by client IP.
- RPM defaults are environment-configurable by category; `ROLE_MULTIPLIERS` scales limits for `admin` and `teacher`, with students/default roles at 1x.
- Decorator factories expose AI, quiz generation/submission, auth, leaderboard, and default limit policies.
- `setup_rate_limiting(app)` attaches the limiter to `app.state` and registers a JSON 429 handler with `Retry-After`.

## Flow
Request identity and role come from `request.state.user`; each category method computes base RPM × role multiplier and returns SlowAPI's `N/minute` policy. SlowAPI applies the policy and dispatches violations to `_rate_limit_exceeded_handler`.

## Integration
`backend/main.py` calls `setup_rate_limiting(app)` when available and adds authentication middleware that populates request user state. `middleware.__init__` exports `rate_limiter`, `setup_rate_limiting`, and `RateLimitExceeded`; route handlers can use `ai_rate_limit`, `quiz_generate_rate_limit`, `quiz_submit_rate_limit`, `auth_rate_limit`, `leaderboard_rate_limit`, or `default_rate_limit`.