feat: reword phase to epic, update mkdocs

docs/content/stories/epic3/3.5-service-registry.md

@@ -0,0 +1,138 @@
+# Story 3.5: Service Registry and Discovery
+
+## Metadata
+- **Story ID**: 3.5
+- **Title**: Service Registry and Discovery
+- **Epic**: 3 - Module Framework
+- **Status**: Pending
+- **Priority**: High
+- **Estimated Time**: 5-6 hours
+- **Dependencies**: 1.7, 3.1
+
+## Goal
+Implement a service registry that enables service discovery for microservices, allowing services to locate and communicate with each other.
+
+## Description
+This story creates a service registry system supporting Consul and Kubernetes service discovery. The registry enables service discovery, health checking, and automatic service registration.
+
+## Deliverables
+
+### 1. Service Registry Interface (`pkg/services/registry.go`)
+- `ServiceRegistry` interface with:
+  - `Register(service ServiceInfo) error` - Register a service
+  - `Deregister(serviceID string) error` - Deregister a service
+  - `Discover(serviceName string) ([]ServiceInfo, error)` - Discover services
+  - `GetService(serviceName string) (ServiceInfo, error)` - Get specific service
+  - `ListServices() ([]ServiceInfo, error)` - List all services
+  - `HealthCheck(serviceID string) error` - Check service health
+
+### 2. Service Info Structure
+- `ServiceInfo` struct with:
+  - ID, Name, Version
+  - Address (host:port)
+  - Protocol (local, grpc, http)
+  - Health status
+  - Metadata
+
+### 3. Consul Registry (`internal/services/registry/consul.go`)
+- Consul integration (primary for production)
+- Service registration and discovery
+- Health checking
+- Automatic service registration
+
+### 4. Kubernetes Service Discovery (`internal/services/registry/kubernetes.go`)
+- Kubernetes service discovery
+- Service health checking
+- Automatic service registration via K8s services
+
+### 5. Service Registration
+- Auto-register services on startup
+- Health check endpoints
+- Graceful deregistration on shutdown
+
+### 6. Configuration
+- Registry configuration in `config/default.yaml`:
+  ```yaml
+  service_registry:
+    type: consul  # consul, kubernetes, etcd
+    consul:
+      address: localhost:8500
+    kubernetes:
+      namespace: default
+    etcd:
+      endpoints:
+        - localhost:2379
+  ```
+
+### 7. Integration
+- Integrate with service factory
+- Auto-register core services
+- Support module service registration
+
+## Implementation Steps
+
+1. **Create Service Registry Interface**
+   - Create `pkg/services/registry.go`
+   - Define ServiceRegistry interface
+   - Define ServiceInfo struct
+
+2. **Implement Consul Registry**
+   - Create `internal/services/registry/consul.go`
+   - Implement Consul integration
+   - Add health checking
+
+3. **Implement Kubernetes Registry**
+   - Create `internal/services/registry/kubernetes.go`
+   - Implement K8s service discovery
+   - Add health checking
+
+4. **Add Service Registration**
+   - Auto-register services on startup
+   - Add health check endpoints
+   - Handle graceful shutdown
+
+5. **Add Configuration**
+   - Add registry configuration
+   - Support multiple registry types
+
+6. **Integrate with Service Factory**
+   - Use registry for service discovery
+   - Resolve services via registry
+
+## Acceptance Criteria
+- [ ] Service registry interface is defined
+- [ ] Consul registry works correctly
+- [ ] Kubernetes registry works correctly
+- [ ] Services are auto-registered on startup
+- [ ] Service discovery works
+- [ ] Health checking works
+- [ ] Registry is configurable
+- [ ] Graceful deregistration works
+
+## Related ADRs
+- [ADR-0029: Microservices Architecture](../../adr/0029-microservices-architecture.md)
+- [ADR-0030: Service Communication Strategy](../../adr/0030-service-communication-strategy.md)
+
+## Implementation Notes
+- Consul is the primary registry for production
+- Kubernetes service discovery for K8s deployments
+- Health checks should be lightweight
+- Support service versioning
+
+## Testing
+```bash
+# Test service registry
+go test ./internal/services/registry/...
+
+# Test service discovery
+go test ./internal/services/registry/... -run TestDiscovery
+```
+
+## Files to Create/Modify
+- `pkg/services/registry.go` - Service registry interface
+- `internal/services/registry/consul.go` - Consul registry
+- `internal/services/registry/kubernetes.go` - Kubernetes registry
+- `internal/services/factory.go` - Integrate with registry
+- `internal/di/providers.go` - Add registry provider
+- `config/default.yaml` - Add registry configuration
+