feat: reword phase to epic, update mkdocs

docs/content/stories/epic1/1.5-http-server.md

@@ -0,0 +1,122 @@
+# Story 1.5: HTTP Server Foundation with Middleware Stack
+
+## Metadata
+- **Story ID**: 1.5
+- **Title**: HTTP Server Foundation with Middleware Stack
+- **Epic**: 1 - Core Kernel & Infrastructure
+- **Status**: Pending
+- **Priority**: High
+- **Estimated Time**: 6-8 hours
+- **Dependencies**: 1.1, 1.3, 1.4
+
+## Goal
+Create a production-ready HTTP server with comprehensive middleware for security, observability, and error handling.
+
+## Description
+This story implements a complete HTTP server using Gin with a comprehensive middleware stack including request ID generation, structured logging, panic recovery, metrics collection, CORS, and graceful shutdown.
+
+## Deliverables
+
+### 1. HTTP Server (`internal/server/server.go`)
+- Gin router initialization
+- Server configuration (port, host, timeouts)
+- Graceful shutdown handling
+
+### 2. Comprehensive Middleware Stack
+- **Request ID Generator**: Unique ID per request
+- **Structured Logging**: Log all requests with context
+- **Panic Recovery**: Recover panics → error bus
+- **Prometheus Metrics**: Collect request metrics
+- **CORS Support**: Configurable CORS headers
+- **Request Timeout**: Handle request timeouts
+- **Response Compression**: Gzip compression for responses
+
+### 3. Core Route Registration
+- `GET /healthz` - Liveness probe
+- `GET /ready` - Readiness probe
+- `GET /metrics` - Prometheus metrics
+
+### 4. FX Lifecycle Integration
+- HTTP server starts on `OnStart` hook
+- Graceful shutdown on `OnStop` hook (drains connections)
+- Port configuration from config system
+
+### 5. Integration
+- Integration with main application entry point
+- Integration with all middleware systems
+
+## Implementation Steps
+
+1. **Install Dependencies**
+   ```bash
+   go get github.com/gin-gonic/gin
+   ```
+
+2. **Create HTTP Server**
+   - Create `internal/server/server.go`
+   - Initialize Gin router
+   - Configure server settings
+
+3. **Implement Middleware**
+   - Request ID middleware
+   - Logging middleware
+   - Panic recovery middleware
+   - Metrics middleware
+   - CORS middleware
+   - Timeout middleware
+   - Compression middleware
+
+4. **Register Core Routes**
+   - Health endpoints
+   - Metrics endpoint
+
+5. **Integrate with FX**
+   - Add lifecycle hooks
+   - Handle graceful shutdown
+
+6. **Test Server**
+   - Verify server starts
+   - Test all endpoints
+   - Test graceful shutdown
+
+## Acceptance Criteria
+- [ ] HTTP server starts successfully
+- [ ] All middleware executes in correct order
+- [ ] Request IDs are generated and logged
+- [ ] Metrics are collected for all requests
+- [ ] Panics are recovered and handled
+- [ ] Graceful shutdown works correctly
+- [ ] Server is configurable via config system
+- [ ] CORS is configurable per environment
+- [ ] All core endpoints work correctly
+
+## Related ADRs
+- [ADR-0006: HTTP Framework](../../adr/0006-http-framework.md)
+
+## Implementation Notes
+- Use Gin for HTTP routing
+- Middleware order is important
+- Support graceful shutdown with connection draining
+- CORS should be configurable per environment
+- Consider adding rate limiting in future (Epic 6)
+
+## Testing
+```bash
+# Test server startup
+go run cmd/platform/main.go
+
+# Test endpoints
+curl http://localhost:8080/healthz
+curl http://localhost:8080/ready
+curl http://localhost:8080/metrics
+
+# Test graceful shutdown
+# Send SIGTERM and verify graceful shutdown
+```
+
+## Files to Create/Modify
+- `internal/server/server.go` - HTTP server
+- `internal/server/middleware.go` - Middleware functions
+- `internal/di/providers.go` - Add server provider
+- `config/default.yaml` - Add server configuration
+