# 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