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

feat: microservice architecture

Browse Source
This commit is contained in:
0x1d
2025-11-05 09:12:34 +01:00
parent 54a047f5dc
commit 65a428534c
354 changed files with 5544 additions and 13141 deletions
Download Patch File Download Diff File Expand all files Collapse all files

85
docs/content/stories/phase3/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
- **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

52
docs/content/stories/phase3/3.1.1-create-pkgmodulemodulego.md
View File

@@ -1,52 +0,0 @@
# Task 3.1.1: Create `pkg/module/module.go`:
## Metadata
- **Task ID**: 3.1.1
- **Title**: Create `pkg/module/module.go`:
- **Phase**: 3 - Module Framework
- **Section**: 3.1
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Create `pkg/module/module.go`:
## Requirements
- Create `pkg/module/module.go`:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 3.1.1 is completed
- [ ] All requirements are met
- [ ] Code compiles and tests pass
## Related ADRs
- See relevant ADRs in `docs/adr/`
## Implementation Notes
- TODO: Add implementation notes
## Testing
```bash
# TODO: Add test commands
go test ./...
```
## Code Reference
```go
type IModule interface {
Name() string
Version() string
Dependencies() []string
Init() fx.Option
Migrations() []func(*ent.Client) error
}
```

52
docs/content/stories/phase3/3.1.2-create-pkgmodulemanifestgo.md
View File

@@ -1,52 +0,0 @@
# Task 3.1.2: Create `pkg/module/manifest.go`:
## Metadata
- **Task ID**: 3.1.2
- **Title**: Create `pkg/module/manifest.go`:
- **Phase**: 3 - Module Framework
- **Section**: 3.1
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Create `pkg/module/manifest.go`:
## Requirements
- Create `pkg/module/manifest.go`:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 3.1.2 is completed
- [ ] All requirements are met
- [ ] Code compiles and tests pass
## Related ADRs
- See relevant ADRs in `docs/adr/`
## Implementation Notes
- TODO: Add implementation notes
## Testing
```bash
# TODO: Add test commands
go test ./...
```
## Code Reference
```go
type Manifest struct {
Name string
Version string
Dependencies []string
Permissions []string
Routes []Route
}
```

40
docs/content/stories/phase3/3.1.3-define-moduleyaml-schema-used-for-code-generation.md
View File

@@ -1,40 +0,0 @@
# Task 3.1.3: Define `module.yaml` schema (used for code generation)
## Metadata
- **Task ID**: 3.1.3
- **Title**: Define `module.yaml` schema (used for code generation)
- **Phase**: 3 - Module Framework
- **Section**: 3.1
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Define `module.yaml` schema (used for code generation)
## Requirements
- Define `module.yaml` schema (used for code generation)
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 3.1.3 is completed
- [ ] All requirements are met
- [ ] Code compiles and tests pass
## Related ADRs
- See relevant ADRs in `docs/adr/`
## Implementation Notes
- TODO: Add implementation notes
## Testing
```bash
# TODO: Add test commands
go test ./...
```

65
docs/content/stories/phase3/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
- **Phase**: 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

40
docs/content/stories/phase3/3.2.1-create-internalregistryregistrygo.md
View File

@@ -1,40 +0,0 @@
# Task 3.2.1: Create `internal/registry/registry.go`:
## Metadata
- **Task ID**: 3.2.1
- **Title**: Create `internal/registry/registry.go`:
- **Phase**: 3 - Module Framework
- **Section**: 3.2
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Create `internal/registry/registry.go`:
## Requirements
- Create `internal/registry/registry.go`:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 3.2.1 is completed
- [ ] All requirements are met
- [ ] Code compiles and tests pass
## Related ADRs
- See relevant ADRs in `docs/adr/`
## Implementation Notes
- TODO: Add implementation notes
## Testing
```bash
# TODO: Add test commands
go test ./...
```

40
docs/content/stories/phase3/3.2.2-add-registration-validation.md
View File

@@ -1,40 +0,0 @@
# Task 3.2.2: Add registration validation:
## Metadata
- **Task ID**: 3.2.2
- **Title**: Add registration validation:
- **Phase**: 3 - Module Framework
- **Section**: 3.2
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Add registration validation:
## Requirements
- Add registration validation:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 3.2.2 is completed
- [ ] All requirements are met
- [ ] Code compiles and tests pass
## Related ADRs
- See relevant ADRs in `docs/adr/`
## Implementation Notes
- TODO: Add implementation notes
## Testing
```bash
# TODO: Add test commands
go test ./...
```

83
docs/content/stories/phase3/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
- **Phase**: 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

40
docs/content/stories/phase3/3.3.1-create-scriptsgenerate-permissionsgo.md
View File

@@ -1,40 +0,0 @@
# Task 3.3.1: Create `scripts/generate-permissions.go`:
## Metadata
- **Task ID**: 3.3.1
- **Title**: Create `scripts/generate-permissions.go`:
- **Phase**: 3 - Module Framework
- **Section**: 3.3
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Create `scripts/generate-permissions.go`:
## Requirements
- Create `scripts/generate-permissions.go`:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 3.3.1 is completed
- [ ] All requirements are met
- [ ] Code compiles and tests pass
## Related ADRs
- See relevant ADRs in `docs/adr/`
## Implementation Notes
- TODO: Add implementation notes
## Testing
```bash
# TODO: Add test commands
go test ./...
```

40
docs/content/stories/phase3/3.3.2-add-gogenerate-directive-to-pkgpermpermgo.md
View File

@@ -1,40 +0,0 @@
# Task 3.3.2: Add `//go:generate` directive to `pkg/perm/perm.go`
## Metadata
- **Task ID**: 3.3.2
- **Title**: Add `//go:generate` directive to `pkg/perm/perm.go`
- **Phase**: 3 - Module Framework
- **Section**: 3.3
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Add `//go:generate` directive to `pkg/perm/perm.go`
## Requirements
- Add `//go:generate` directive to `pkg/perm/perm.go`
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 3.3.2 is completed
- [ ] All requirements are met
- [ ] Code compiles and tests pass
## Related ADRs
- See relevant ADRs in `docs/adr/`
## Implementation Notes
- TODO: Add implementation notes
## Testing
```bash
# TODO: Add test commands
go test ./...
```

40
docs/content/stories/phase3/3.3.3-update-makefile-with-make-generate-command.md
View File

@@ -1,40 +0,0 @@
# Task 3.3.3: Update `Makefile` with `make generate` command
## Metadata
- **Task ID**: 3.3.3
- **Title**: Update `Makefile` with `make generate` command
- **Phase**: 3 - Module Framework
- **Section**: 3.3
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Update `Makefile` with `make generate` command
## Requirements
- Update `Makefile` with `make generate` command
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 3.3.3 is completed
- [ ] All requirements are met
- [ ] Code compiles and tests pass
## Related ADRs
- See relevant ADRs in `docs/adr/`
## Implementation Notes
- TODO: Add implementation notes
## Testing
```bash
# TODO: Add test commands
go test ./...
```

62
docs/content/stories/phase3/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
- **Phase**: 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

40
docs/content/stories/phase3/3.4.1-create-internalpluginloaderloadergo.md
View File

@@ -1,40 +0,0 @@
# Task 3.4.1: Create `internal/pluginloader/loader.go`:
## Metadata
- **Task ID**: 3.4.1
- **Title**: Create `internal/pluginloader/loader.go`:
- **Phase**: 3 - Module Framework
- **Section**: 3.4
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Create `internal/pluginloader/loader.go`:
## Requirements
- Create `internal/pluginloader/loader.go`:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 3.4.1 is completed
- [ ] All requirements are met
- [ ] Code compiles and tests pass
## Related ADRs
- See relevant ADRs in `docs/adr/`
## Implementation Notes
- TODO: Add implementation notes
## Testing
```bash
# TODO: Add test commands
go test ./...
```

40
docs/content/stories/phase3/3.4.2-implement-internalpluginloaderstatic_loadergo.md
View File

@@ -1,40 +0,0 @@
# Task 3.4.2: Implement `internal/pluginloader/static_loader.go`:
## Metadata
- **Task ID**: 3.4.2
- **Title**: Implement `internal/pluginloader/static_loader.go`:
- **Phase**: 3 - Module Framework
- **Section**: 3.4
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Implement `internal/pluginloader/static_loader.go`:
## Requirements
- Implement `internal/pluginloader/static_loader.go`:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 3.4.2 is completed
- [ ] All requirements are met
- [ ] Code compiles and tests pass
## Related ADRs
- See relevant ADRs in `docs/adr/`
## Implementation Notes
- TODO: Add implementation notes
## Testing
```bash
# TODO: Add test commands
go test ./...
```

40
docs/content/stories/phase3/3.4.3-implement-internalpluginloaderplugin_loadergo-opti.md
View File

@@ -1,40 +0,0 @@
# Task 3.4.3: Implement `internal/pluginloader/plugin_loader.go` (optional):
## Metadata
- **Task ID**: 3.4.3
- **Title**: Implement `internal/pluginloader/plugin_loader.go` (optional):
- **Phase**: 3 - Module Framework
- **Section**: 3.4
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Implement `internal/pluginloader/plugin_loader.go` (optional):
## Requirements
- Implement `internal/pluginloader/plugin_loader.go` (optional):
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 3.4.3 is completed
- [ ] All requirements are met
- [ ] Code compiles and tests pass
## Related ADRs
- See relevant ADRs in `docs/adr/`
## Implementation Notes
- TODO: Add implementation notes
## Testing
```bash
# TODO: Add test commands
go test ./...
```

138
docs/content/stories/phase3/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
- **Phase**: 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

40
docs/content/stories/phase3/3.5.1-create-internalmoduleinitializergo.md
View File

@@ -1,40 +0,0 @@
# Task 3.5.1: Create `internal/module/initializer.go`:
## Metadata
- **Task ID**: 3.5.1
- **Title**: Create `internal/module/initializer.go`:
- **Phase**: 3 - Module Framework
- **Section**: 3.5
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Create `internal/module/initializer.go`:
## Requirements
- Create `internal/module/initializer.go`:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 3.5.1 is completed
- [ ] All requirements are met
- [ ] Code compiles and tests pass
## Related ADRs
- See relevant ADRs in `docs/adr/`
## Implementation Notes
- TODO: Add implementation notes
## Testing
```bash
# TODO: Add test commands
go test ./...
```

40
docs/content/stories/phase3/3.5.2-run-migrations.md
View File

@@ -1,40 +0,0 @@
# Task 3.5.2: Run migrations:
## Metadata
- **Task ID**: 3.5.2
- **Title**: Run migrations:
- **Phase**: 3 - Module Framework
- **Section**: 3.5
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Run migrations:
## Requirements
- Run migrations:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 3.5.2 is completed
- [ ] All requirements are met
- [ ] Code compiles and tests pass
## Related ADRs
- See relevant ADRs in `docs/adr/`
## Implementation Notes
- TODO: Add implementation notes
## Testing
```bash
# TODO: Add test commands
go test ./...
```

50
docs/content/stories/phase3/3.6.1-extend-pkgmodulemodulego.md
View File

@@ -1,50 +0,0 @@
# Task 3.6.1: Extend `pkg/module/module.go`:
## Metadata
- **Task ID**: 3.6.1
- **Title**: Extend `pkg/module/module.go`:
- **Phase**: 3 - Module Framework
- **Section**: 3.6
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Extend `pkg/module/module.go`:
## Requirements
- Extend `pkg/module/module.go`:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 3.6.1 is completed
- [ ] All requirements are met
- [ ] Code compiles and tests pass
## Related ADRs
- See relevant ADRs in `docs/adr/`
## Implementation Notes
- TODO: Add implementation notes
## Testing
```bash
# TODO: Add test commands
go test ./...
```
## Code Reference
```go
type IModule interface {
// ... existing methods
OnStart(ctx context.Context) error // Optional
OnStop(ctx context.Context) error // Optional
}
```

40
docs/content/stories/phase3/3.6.2-integrate-with-fxlifecycle.md
View File

@@ -1,40 +0,0 @@
# Task 3.6.2: Integrate with fx.Lifecycle:
## Metadata
- **Task ID**: 3.6.2
- **Title**: Integrate with fx.Lifecycle:
- **Phase**: 3 - Module Framework
- **Section**: 3.6
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Integrate with fx.Lifecycle:
## Requirements
- Integrate with fx.Lifecycle:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 3.6.2 is completed
- [ ] All requirements are met
- [ ] Code compiles and tests pass
## Related ADRs
- See relevant ADRs in `docs/adr/`
## Implementation Notes
- TODO: Add implementation notes
## Testing
```bash
# TODO: Add test commands
go test ./...
```

40
docs/content/stories/phase3/3.7.1-create-cmdplatformctlmaingo.md
View File

@@ -1,40 +0,0 @@
# Task 3.7.1: Create `cmd/platformctl/main.go`:
## Metadata
- **Task ID**: 3.7.1
- **Title**: Create `cmd/platformctl/main.go`:
- **Phase**: 3 - Module Framework
- **Section**: 3.7
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Create `cmd/platformctl/main.go`:
## Requirements
- Create `cmd/platformctl/main.go`:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 3.7.1 is completed
- [ ] All requirements are met
- [ ] Code compiles and tests pass
## Related ADRs
- See relevant ADRs in `docs/adr/`
## Implementation Notes
- TODO: Add implementation notes
## Testing
```bash
# TODO: Add test commands
go test ./...
```

40
docs/content/stories/phase3/3.7.2-add-to-makefile-make-install-cli.md
View File

@@ -1,40 +0,0 @@
# Task 3.7.2: Add to `Makefile`: `make install-cli`
## Metadata
- **Task ID**: 3.7.2
- **Title**: Add to `Makefile`: `make install-cli`
- **Phase**: 3 - Module Framework
- **Section**: 3.7
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Add to `Makefile`: `make install-cli`
## Requirements
- Add to `Makefile`: `make install-cli`
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 3.7.2 is completed
- [ ] All requirements are met
- [ ] Code compiles and tests pass
## Related ADRs
- See relevant ADRs in `docs/adr/`
## Implementation Notes
- TODO: Add implementation notes
## Testing
```bash
# TODO: Add test commands
go test ./...
```

76
docs/content/stories/phase3/README.md
View File

@@ -1,54 +1,48 @@
# Phase 3: Module Framework
## Overview
Define module interface and registration system, implement static module registry, create permission code generation tool, build module loader (support both static and plugin modes), and add module discovery and initialization.
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.
## Tasks
## Stories
### 3.1 Module Interface
- [3.1.1 - Create Module Interface](./3.1.1-create-pkgmodulemodulego.md)
- [3.1.2 - Create Module Manifest](./3.1.2-create-pkgmodulemanifestgo.md)
- [3.1.3 - Define Module YAML Schema](./3.1.3-define-moduleyaml-schema-used-for-code-generation.md)
### 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 Static Module Registry
- [3.2.1 - Create Registry](./3.2.1-create-internalregistryregistrygo.md)
- [3.2.2 - Add Registration Validation](./3.2.2-add-registration-validation.md)
### 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 Permission Code Generation
- [3.3.1 - Create Generate Script](./3.3.1-create-scriptsgenerate-permissionsgo.md)
- [3.3.2 - Add Go Generate Directive](./3.3.2-add-gogenerate-directive-to-pkgpermpermgo.md)
- [3.3.3 - Update Makefile](./3.3.3-update-makefile-with-make-generate-command.md)
### 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 Loader
- [3.4.1 - Create Loader Interface](./3.4.1-create-internalpluginloaderloadergo.md)
- [3.4.2 - Implement Static Loader](./3.4.2-implement-internalpluginloaderstatic_loadergo.md)
- [3.4.3 - Implement Plugin Loader](./3.4.3-implement-internalpluginloaderplugin_loadergo-opti.md)
### 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 Module Initialization
- [3.5.1 - Create Initializer](./3.5.1-create-internalmoduleinitializergo.md)
- [3.5.2 - Run Migrations](./3.5.2-run-migrations.md)
### 3.6 Module Lifecycle
- [3.6.1 - Extend Module Interface](./3.6.1-extend-pkgmodulemodulego.md)
- [3.6.2 - Integrate with FX Lifecycle](./3.6.2-integrate-with-fxlifecycle.md)
### 3.7 Platform CLI
- [3.7.1 - Create CLI Tool](./3.7.1-create-cmdplatformctlmaingo.md)
- [3.7.2 - Add to Makefile](./3.7.2-add-to-makefile-make-install-cli.md)
### 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 defined
- [ ] Static module registry implemented
- [ ] Permission code generation working
- [ ] Module loader supports static and plugin modes
- [ ] Modules can be discovered and initialized
- [ ] Module migrations run on startup
- [ ] Platform CLI tool for module management
- [ ] 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 be registered statically
- Permission constants are generated from module manifests
- Modules are initialized with correct dependency order
- Module migrations run automatically
- CLI tool can list and manage modules
- 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