docs: add mkdocs, update links, add architecture documentation

docs/content/adr/0005-logging-framework.md

@@ -0,0 +1,50 @@
+# ADR-0005: Logging Framework
+
+## Status
+Accepted
+
+## Context
+The platform requires structured logging that:
+- Supports multiple log levels
+- Provides structured output (JSON for production)
+- Allows adding contextual fields
+- Performs well under load
+- Integrates with observability tools
+
+Options considered:
+1. **go.uber.org/zap** - High-performance structured logging
+2. **rs/zerolog** - Zero-allocation logger
+3. **sirupsen/logrus** - Structured logger (maintenance mode)
+4. **Standard library log** - Basic logging (insufficient)
+
+## Decision
+Use **go.uber.org/zap** (v1.26.0+) as the logging framework.
+
+**Rationale:**
+- Industry standard for high-performance Go applications
+- Excellent structured logging with field support
+- Very low overhead (designed for high-throughput systems)
+- JSON output for production, human-readable for development
+- Strong ecosystem integration
+- Actively maintained by Uber
+
+## Consequences
+
+### Positive
+- High performance (low latency, high throughput)
+- Rich structured logging with fields
+- Easy integration with observability tools
+- Configurable output formats (JSON/console)
+
+### Negative
+- Slightly more verbose API than standard library
+- Requires wrapping for common use cases (we'll abstract via interface)
+
+### Implementation Notes
+- Install: `go get go.uber.org/zap@v1.26.0`
+- Create `pkg/logger/logger.go` interface to abstract zap
+- Implement `internal/logger/zap_logger.go` as concrete implementation
+- Use JSON encoder for production, console encoder for development
+- Support request-scoped fields via context
+- Export global logger via `pkg/logger` package
+