# Story 3.1: Module System Interface and Service Registry

## Metadata
- **Story ID**: 3.1
- **Title**: Module System Interface and Service Registry
- **Epic**: 3 - Module Framework (Feature Services)
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 5-6 hours
- **Dependencies**: 1.1, 1.7, 2.3

## Goal
Design module interface for feature services with service registration and dependency resolution. Modules are services that register with Consul and communicate via service clients.

## Description
This story creates the foundation for feature services (modules) by defining the module interface, manifest structure, and service registration. Feature services are independent services with their own entry points, gRPC servers, and database schemas. They register with Consul and use service clients for inter-service communication.

## Deliverables

### 1. Module Interface (`pkg/module/module.go`)
- `IModule` interface for feature services:
  - `Name() string` - Service name
  - `Version() string` - Service version
  - `Dependencies() []string` - Service dependencies (other services)
  - `Init() fx.Option` - FX options for service initialization
  - `Migrations() []func(*ent.Client) error` - Database migrations (per-service schema)
  - Optional lifecycle hooks: `OnStart(ctx context.Context) error`
  - Optional lifecycle hooks: `OnStop(ctx context.Context) error`

**Note:** Modules are services - each module has its own `cmd/{service}/main.go` entry point.

### 2. Module Manifest (`pkg/module/manifest.go`)
- `Manifest` struct with:
  - Name, Version, Dependencies (service names)
  - Permissions list
  - gRPC service definitions
  - Database schema information
- `module.yaml` schema definition
- Manifest parsing and validation

### 3. Service Registration Integration
- Integration with Consul service registry (from Epic 1)
- Service registration helpers
- Service discovery integration
- Health check integration

### 4. Module Registry (`internal/registry/module_registry.go`)
- Thread-safe module map (for tracking feature services)
- `Register(m IModule)` function
- `All() []IModule` function
- `Get(name string) (IModule, error)` function
- Dependency validation (check service dependencies are available)
- Duplicate name detection
- Version compatibility checking
- Dependency cycle detection

**Note:** This is separate from the service registry (Consul) - this tracks feature services for dependency resolution.

## Implementation Steps

1. **Create Module Interface**
   - Create `pkg/module/module.go`
   - Define IModule interface
   - Add lifecycle hooks

2. **Create Module Manifest**
   - Create `pkg/module/manifest.go`
   - Define Manifest struct
   - Define module.yaml schema

3. **Create Module Registry**
   - Create `internal/registry/registry.go`
   - Implement thread-safe registry
   - Add validation logic

4. **Test Registration**
   - Test module registration
   - Test dependency validation
   - Test duplicate detection

## Acceptance Criteria
- [x] Feature services can register via module interface
- [x] Registry validates service dependencies
- [x] Registry prevents duplicate registrations
- [x] Module interface supports service architecture
- [x] Dependency cycles are detected
- [x] Version compatibility is checked
- [x] Service registration with Consul is integrated
- [x] Feature services can discover core services via service registry

## Related ADRs
- [ADR-0021: Module Loading Strategy](../../adr/0021-module-loading-strategy.md)
- [ADR-0029: Microservices Architecture](../../adr/0029-microservices-architecture.md)
- [ADR-0030: Service Communication Strategy](../../adr/0030-service-communication-strategy.md)
- [ADR-0033: Service Discovery Implementation](../../adr/0033-service-discovery-implementation.md)

## Files to Create/Modify
- `pkg/module/module.go` - Module interface for feature services
- `pkg/module/manifest.go` - Module manifest
- `internal/registry/module_registry.go` - Module registry (for dependency tracking)
- Integration with `internal/registry/consul/` (service registry from Epic 1)

