goplt/docs/content/stories/epic3/3.1-module-system-interface.md

Story 3.1: Module System Interface and Registry

Metadata

• Story ID: 3.1
• Title: Module System Interface and Registry
• Epic: 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

Files to Create/Modify

• pkg/module/module.go - Module interface
• pkg/module/manifest.go - Module manifest
• internal/registry/registry.go - Module registry