toolz/goplt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: reword phase to epic, update mkdocs

Browse Source
This commit is contained in:
0x1d
2025-11-05 09:28:33 +01:00
parent 65a428534c
commit ace9678f6c
64 changed files with 214 additions and 208 deletions
Download Patch File Download Diff File Expand all files Collapse all files

85
docs/content/stories/epic3/3.1-module-system-interface.md Normal file
View File

@@ -0,0 +1,85 @@
# 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](../../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

65
docs/content/stories/epic3/3.2-permission-code-generation.md Normal file
View File

@@ -0,0 +1,65 @@
# Story 3.2: Permission Code Generation System
## Metadata
- **Story ID**: 3.2
- **Title**: Permission Code Generation System
- **Epic**: 3 - Module Framework
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 4-5 hours
- **Dependencies**: 3.1
## Goal
Create automated permission code generation from module manifests to ensure type-safe permission constants.
## Description
This story implements a code generation system that scans module manifests and generates type-safe permission constants, ensuring permissions are defined in one place and used consistently throughout the codebase.
## Deliverables
### 1. Permission Generation Script (`scripts/generate-permissions.go`)
- Scan all `modules/*/module.yaml` files
- Extract permissions from manifests
- Generate `pkg/perm/generated.go` with Permission constants
- Support for multiple modules
- Error handling and validation
- Format generated code
### 2. Go Generate Integration
- `//go:generate` directive in `pkg/perm/perm.go`
- Automatic generation on build
- Integration with build process
### 3. Makefile Integration
- `make generate` command
- Run permission generation
- Verify generated code
## Implementation Steps
1. **Create Generation Script**
- Create `scripts/generate-permissions.go`
- Implement YAML parsing
- Implement code generation
2. **Add Go Generate Directive**
- Add directive to `pkg/perm/perm.go`
- Test generation
3. **Update Makefile**
- Add `make generate` command
- Integrate with build process
## Acceptance Criteria
- [ ] Permission constants are generated from `module.yaml`
- [ ] Generated code is type-safe
- [ ] Code generation runs automatically
- [ ] Permissions follow naming convention
- [ ] Multiple modules are supported
- [ ] Generated code is properly formatted
## Files to Create/Modify
- `scripts/generate-permissions.go` - Generation script
- `pkg/perm/perm.go` - Add go:generate directive
- `Makefile` - Add generate command

83
docs/content/stories/epic3/3.3-module-loader.md Normal file
View File

@@ -0,0 +1,83 @@
# Story 3.3: Module Loader and Initialization
## Metadata
- **Story ID**: 3.3
- **Title**: Module Loader and Initialization
- **Epic**: 3 - Module Framework
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 6-8 hours
- **Dependencies**: 3.1, 1.2
## Goal
Implement module loading (static and dynamic) with dependency resolution and automatic initialization.
## Description
This story implements the complete module loading system that discovers modules, resolves dependencies, initializes them in the correct order, and runs their migrations. It supports both static registration (preferred) and dynamic plugin loading.
## Deliverables
### 1. Module Loader (`internal/pluginloader/loader.go`)
- Support static registration (preferred method)
- Optional: Go plugin loading (`.so` files)
- Module discovery from `modules/*/module.yaml`
- Loader interface for extensibility
### 2. Static Loader (`internal/pluginloader/static_loader.go`)
- Import modules via side-effect imports
- Collect all registered modules
- Module discovery and registration
### 3. Optional Plugin Loader (`internal/pluginloader/plugin_loader.go`)
- Scan `./plugins/*.so` files
- Load via `plugin.Open()`
- Extract and validate module symbols
- Version compatibility checking
### 4. Module Initializer (`internal/module/initializer.go`)
- Collect all registered modules
- Resolve dependency order (topological sort)
- Initialize each module's `Init()` fx.Option
- Merge all options into main fx container
- Run migrations in dependency order
- Handle errors gracefully
### 5. FX Lifecycle Integration
- Call `OnStart()` during app startup
- Call `OnStop()` during graceful shutdown
- Proper error handling
## Implementation Steps
1. **Create Module Loader**
- Create `internal/pluginloader/loader.go`
- Define loader interface
2. **Implement Static Loader**
- Create `internal/pluginloader/static_loader.go`
- Implement static module loading
3. **Implement Module Initializer**
- Create `internal/module/initializer.go`
- Implement dependency resolution
- Implement initialization
4. **Integrate with FX**
- Add lifecycle hooks
- Test initialization
## Acceptance Criteria
- [ ] Modules load in correct dependency order
- [ ] Module migrations run automatically
- [ ] Module initialization integrates with FX
- [ ] Lifecycle hooks work correctly
- [ ] Dependency resolution handles cycles
- [ ] Errors are handled gracefully
## Files to Create/Modify
- `internal/pluginloader/loader.go` - Loader interface
- `internal/pluginloader/static_loader.go` - Static loader
- `internal/pluginloader/plugin_loader.go` - Plugin loader (optional)
- `internal/module/initializer.go` - Module initializer
- `internal/di/container.go` - Integrate module initialization

62
docs/content/stories/epic3/3.4-module-cli.md Normal file
View File

@@ -0,0 +1,62 @@
# Story 3.4: Module Management CLI Tool
## Metadata
- **Story ID**: 3.4
- **Title**: Module Management CLI Tool
- **Epic**: 3 - Module Framework
- **Status**: Pending
- **Priority**: Medium
- **Estimated Time**: 4-5 hours
- **Dependencies**: 3.1, 3.3
## Goal
Provide CLI tooling for managing modules, validating dependencies, and testing module loading.
## Description
This story creates a CLI tool that allows developers and operators to manage modules, validate dependencies, test module loading, and inspect module information.
## Deliverables
### 1. CLI Tool (`cmd/platformctl/main.go`)
- `platformctl modules list` - List all loaded modules with versions
- `platformctl modules validate` - Validate module dependencies
- `platformctl modules test <module>` - Test module loading
- `platformctl modules info <module>` - Show module details
- `platformctl modules dependencies <module>` - Show module dependencies
- Command-line argument parsing
- Error handling and user-friendly output
### 2. Makefile Integration
- `make install-cli` - Install CLI tool
- `make cli` - Build CLI tool
- `make cli-test` - Test CLI tool
## Implementation Steps
1. **Create CLI Tool**
- Create `cmd/platformctl/main.go`
- Use cobra for CLI framework
- Implement commands
2. **Implement Commands**
- List command
- Validate command
- Test command
- Info command
3. **Add to Makefile**
- Add build commands
- Add install commands
## Acceptance Criteria
- [ ] CLI tool lists all modules
- [ ] Dependency validation works
- [ ] Module testing works
- [ ] CLI is installable and usable
- [ ] Commands provide helpful output
- [ ] Error messages are clear
## Files to Create/Modify
- `cmd/platformctl/main.go` - CLI tool
- `Makefile` - Add CLI commands

138
docs/content/stories/epic3/3.5-service-registry.md Normal file
View File

@@ -0,0 +1,138 @@
# 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

48
docs/content/stories/epic3/README.md Normal file
View File

@@ -0,0 +1,48 @@
# Epic 3: Module Framework
## Overview
Design and implement complete module system interface, build module registry with dependency resolution, create permission code generation from module manifests, implement module loader supporting static and dynamic loading, add module lifecycle management and initialization, and provide CLI tooling for module management.
## Stories
### 3.1 Module System Interface and Registry
- [Story: 3.1 - Module System Interface](./3.1-module-system-interface.md)
- **Goal:** Design and implement the complete module system interface with registration, dependency resolution, and lifecycle management.
- **Deliverables:** Module interface, module manifest, module registry
### 3.2 Permission Code Generation System
- [Story: 3.2 - Permission Code Generation](./3.2-permission-code-generation.md)
- **Goal:** Create automated permission code generation from module manifests to ensure type-safe permission constants.
- **Deliverables:** Permission generation script, Go generate integration, Makefile integration
### 3.3 Module Loader and Initialization
- [Story: 3.3 - Module Loader](./3.3-module-loader.md)
- **Goal:** Implement module loading (static and dynamic) with dependency resolution and automatic initialization.
- **Deliverables:** Module loader, static loader, plugin loader, module initializer, FX lifecycle integration
### 3.4 Module Management CLI Tool
- [Story: 3.4 - Module CLI](./3.4-module-cli.md)
- **Goal:** Provide CLI tooling for managing modules, validating dependencies, and testing module loading.
- **Deliverables:** CLI tool, Makefile integration
### 3.5 Service Registry and Discovery
- [Story: 3.5 - Service Registry](./3.5-service-registry.md)
- **Goal:** Implement a service registry that enables service discovery for microservices.
- **Deliverables:** Service registry interface, Consul registry, Kubernetes registry, service registration
## Deliverables Checklist
- [ ] Module interface and registration system
- [ ] Static module registry working
- [ ] Permission code generation tool
- [ ] Module loader with dependency resolution
- [ ] Module initialization in main app
- [ ] CLI tool for module management
- [ ] Service registry for discovery
## Acceptance Criteria
- Modules can register via `registry.Register()`
- Permission constants are generated from `module.yaml`
- Modules load in correct dependency order
- Module migrations run on startup
- `platformctl modules list` shows all modules
- Integration test: load multiple modules and verify initialization