docs: add mkdocs, update links, add architecture documentation

docs/content/adr/0028-testing-strategy.md

@@ -0,0 +1,67 @@
+# ADR-0028: Testing Strategy
+
+## Status
+Accepted
+
+## Context
+The platform needs a comprehensive testing strategy:
+- Unit tests for individual components
+- Integration tests for full flows
+- Contract tests for API compatibility
+- Load tests for performance
+
+Testing tools and approaches vary in complexity and coverage.
+
+## Decision
+Adopt a **multi-layered testing approach**:
+
+1. **Unit tests**:
+   - Tool: Standard `testing` package + `testify`
+   - Coverage: >80% for core modules
+   - Mocks: `mockery` or `mockgen`
+   - Fast execution (< 1 second)
+
+2. **Integration tests**:
+   - Tool: `testcontainers-go` for Docker-based services
+   - Coverage: End-to-end flows (auth, modules, etc.)
+   - Infrastructure: PostgreSQL, Redis, Kafka via testcontainers
+   - Tagged: `//go:build integration`
+
+3. **Contract tests**:
+   - Tool: OpenAPI validator (`kin-openapi`)
+   - Coverage: API request/response validation
+   - Optional: Pact for service contracts
+
+4. **Load tests**:
+   - Tool: k6 or vegeta
+   - Coverage: Critical endpoints (auth, API)
+   - Performance benchmarks
+
+**Rationale:**
+- Comprehensive coverage across layers
+- Fast feedback with unit tests
+- Realistic testing with integration tests
+- API compatibility with contract tests
+- Performance validation with load tests
+
+## Consequences
+
+### Positive
+- High confidence in code quality
+- Fast unit tests for quick feedback
+- Realistic integration tests
+- API compatibility guaranteed
+
+### Negative
+- Integration tests are slower
+- Requires Docker for testcontainers
+- More complex CI setup
+
+### Implementation Notes
+- Use `testify` for assertions: `require` and `assert`
+- Generate mocks with `mockery` or `mockgen`
+- Create test helpers in `internal/testutil/`
+- Use test tags: `go test -tags=integration ./...`
+- Run integration tests in separate CI job
+- Document testing approach in `CONTRIBUTING.md`
+