docs: add mkdocs, update links, add architecture documentation

docs/content/adr/0027-rate-limiting-strategy.md

@@ -0,0 +1,54 @@
+# ADR-0027: Rate Limiting Strategy
+
+## Status
+Accepted
+
+## Context
+The platform needs rate limiting to:
+- Prevent abuse and DoS attacks
+- Protect against brute-force attacks
+- Ensure fair resource usage
+- Comply with API usage policies
+
+Rate limiting strategies:
+1. **Per-user rate limiting** - Based on authenticated user
+2. **Per-IP rate limiting** - Based on client IP
+3. **Fixed rate limiting** - Global limits
+4. **Distributed rate limiting** - Shared state across instances
+
+## Decision
+Implement **multi-level rate limiting**:
+
+1. **Per-user rate limiting**: For authenticated requests (e.g., 100 req/min)
+2. **Per-IP rate limiting**: For all requests (e.g., 1000 req/min)
+3. **Storage**: Redis for distributed rate limiting
+4. **Algorithm**: Token bucket or sliding window
+
+**Rationale:**
+- Multi-level provides defense in depth
+- Per-user prevents abuse by authenticated users
+- Per-IP protects against unauthenticated abuse
+- Redis enables distributed rate limiting (multi-instance)
+- Token bucket provides smooth rate limiting
+
+## Consequences
+
+### Positive
+- Multi-layer protection
+- Works with multiple instances
+- Configurable per endpoint
+- Standard approach
+
+### Negative
+- Requires Redis (or shared state)
+- Additional latency (minimal)
+- Need to handle Redis failures gracefully
+
+### Implementation Notes
+- Use `github.com/ulule/limiter/v3` library
+- Configure limits in config file
+- Store rate limit state in Redis
+- Return `X-RateLimit-*` headers
+- Handle Redis failures gracefully (fail open or closed based on config)
+- Configure different limits for different endpoints
+