docs: add mkdocs, update links, add architecture documentation

This commit is contained in:
2025-11-05 07:44:21 +01:00
parent 6a17236474
commit 54a047f5dc
351 changed files with 3482 additions and 10 deletions

View File

@@ -0,0 +1,52 @@
# 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
}
```

View File

@@ -0,0 +1,52 @@
# 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
}
```

View File

@@ -0,0 +1,40 @@
# 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 ./...
```

View File

@@ -0,0 +1,40 @@
# 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 ./...
```

View File

@@ -0,0 +1,40 @@
# 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 ./...
```

View File

@@ -0,0 +1,40 @@
# 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 ./...
```

View File

@@ -0,0 +1,40 @@
# 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 ./...
```

View File

@@ -0,0 +1,40 @@
# 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 ./...
```

View File

@@ -0,0 +1,40 @@
# 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 ./...
```

View File

@@ -0,0 +1,40 @@
# 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 ./...
```

View File

@@ -0,0 +1,40 @@
# 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 ./...
```

View File

@@ -0,0 +1,40 @@
# 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 ./...
```

View File

@@ -0,0 +1,40 @@
# 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 ./...
```

View File

@@ -0,0 +1,50 @@
# 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
}
```

View File

@@ -0,0 +1,40 @@
# 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 ./...
```

View File

@@ -0,0 +1,40 @@
# 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 ./...
```

View File

@@ -0,0 +1,40 @@
# 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 ./...
```

View File

@@ -0,0 +1,54 @@
# 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.
## Tasks
### 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.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.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.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.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)
## 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
## 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