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

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

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

Related ADRs

• ADR-0021: Module Loading Strategy
• ADR-0029: Microservices Architecture
• ADR-0030: Service Communication Strategy
• ADR-0033: Service Discovery Implementation

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)