# Story 3.1: Module System Interface and Registry

## Metadata
- **Story ID**: 3.1
- **Title**: Module System Interface and Registry
- **Phase**: 3 - Module Framework
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 5-6 hours
- **Dependencies**: 1.1, 2.3

## Goal
Design and implement the complete module system interface with registration, dependency resolution, and lifecycle management.

## Description
This story creates the foundation of the module system by defining the module interface, manifest structure, and registry. The system must support module registration, dependency validation, and lifecycle hooks.

## Deliverables

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

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

### 3. Module Registry (`internal/registry/registry.go`)
- Thread-safe module map
- `Register(m IModule)` function
- `All() []IModule` function
- `Get(name string) (IModule, error)` function
- Dependency validation (check dependencies are satisfied)
- Duplicate name detection
- Version compatibility checking
- Dependency cycle detection

## 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
- [ ] Modules can register via `registry.Register()`
- [ ] Registry validates dependencies
- [ ] Registry prevents duplicate registrations
- [ ] Module interface is extensible
- [ ] Dependency cycles are detected
- [ ] Version compatibility is checked

## Related ADRs
- [ADR-0021: Module Loading Strategy](../../adr/0021-module-loading-strategy.md)

## Files to Create/Modify
- `pkg/module/module.go` - Module interface
- `pkg/module/manifest.go` - Module manifest
- `internal/registry/registry.go` - Module registry