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,58 @@
# Task 4.1.1: Create `modules/blog/` directory:
## Metadata
- **Task ID**: 4.1.1
- **Title**: Create `modules/blog/` directory:
- **Phase**: 4 - Sample Feature Module (Blog)
- **Section**: 4.1
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Create `modules/blog/` directory:
## Requirements
- Create `modules/blog/` directory:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 4.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
modules/blog/
├── go.mod
├── module.yaml
├── internal/
├── api/
└── handler.go
├── domain/
├── post.go
└── post_repo.go
└── service/
└── post_service.go
└── pkg/
└── module.go
```

View File

@@ -0,0 +1,47 @@
# Task 4.1.2: Initialize `go.mod`:
## Metadata
- **Task ID**: 4.1.2
- **Title**: Initialize `go.mod`:
- **Phase**: 4 - Sample Feature Module (Blog)
- **Section**: 4.1
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Initialize `go.mod`:
## Requirements
- Initialize `go.mod`:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 4.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
cd modules/blog
go mod init github.com/yourorg/blog
```

View File

@@ -0,0 +1,70 @@
# Task 4.2.1: Create `modules/blog/module.yaml`:
## Metadata
- **Task ID**: 4.2.1
- **Title**: Create `modules/blog/module.yaml`:
- **Phase**: 4 - Sample Feature Module (Blog)
- **Section**: 4.2
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Create `modules/blog/module.yaml`:
## Requirements
- Create `modules/blog/module.yaml`:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 4.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 ./...
```
## Code Reference
```go
name: blog
version: 0.1.0
dependencies:
- core >= 1.0.0
permissions:
- blog.post.create
- blog.post.read
- blog.post.update
- blog.post.delete
routes:
- method: POST
path: /api/v1/blog/posts
permission: blog.post.create
- method: GET
path: /api/v1/blog/posts/:id
permission: blog.post.read
- method: PUT
path: /api/v1/blog/posts/:id
permission: blog.post.update
- method: DELETE
path: /api/v1/blog/posts/:id
permission: blog.post.delete
- method: GET
path: /api/v1/blog/posts
permission: blog.post.read
```

View File

@@ -0,0 +1,53 @@
# Task 4.3.1: Create `modules/blog/internal/domain/post.go`:
## Metadata
- **Task ID**: 4.3.1
- **Title**: Create `modules/blog/internal/domain/post.go`:
- **Phase**: 4 - Sample Feature Module (Blog)
- **Section**: 4.3
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Create `modules/blog/internal/domain/post.go`:
## Requirements
- Create `modules/blog/internal/domain/post.go`:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 4.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 ./...
```
## Code Reference
```go
type Post struct {
ID string
Title string
Content string
AuthorID string
CreatedAt time.Time
UpdatedAt time.Time
}
```

View File

@@ -0,0 +1,40 @@
# Task 4.3.2: Create Ent schema `modules/blog/internal/ent/schema/post.go`:
## Metadata
- **Task ID**: 4.3.2
- **Title**: Create Ent schema `modules/blog/internal/ent/schema/post.go`:
- **Phase**: 4 - Sample Feature Module (Blog)
- **Section**: 4.3
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Create Ent schema `modules/blog/internal/ent/schema/post.go`:
## Requirements
- Create Ent schema `modules/blog/internal/ent/schema/post.go`:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 4.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 4.3.3: Generate Ent code for blog module
## Metadata
- **Task ID**: 4.3.3
- **Title**: Generate Ent code for blog module
- **Phase**: 4 - Sample Feature Module (Blog)
- **Section**: 4.3
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Generate Ent code for blog module
## Requirements
- Generate Ent code for blog module
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 4.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,52 @@
# Task 4.4.1: Create `modules/blog/internal/domain/post_repo.go`:
## Metadata
- **Task ID**: 4.4.1
- **Title**: Create `modules/blog/internal/domain/post_repo.go`:
- **Phase**: 4 - Sample Feature Module (Blog)
- **Section**: 4.4
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Create `modules/blog/internal/domain/post_repo.go`:
## Requirements
- Create `modules/blog/internal/domain/post_repo.go`:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 4.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 ./...
```
## Code Reference
```go
type PostRepository interface {
Create(ctx context.Context, p *Post) (*Post, error)
FindByID(ctx context.Context, id string) (*Post, error)
FindByAuthor(ctx context.Context, authorID string) ([]*Post, error)
Update(ctx context.Context, p *Post) error
Delete(ctx context.Context, id string) error
}
```

View File

@@ -0,0 +1,40 @@
# Task 4.4.2: Implement using Ent client (shared from core)
## Metadata
- **Task ID**: 4.4.2
- **Title**: Implement using Ent client (shared from core)
- **Phase**: 4 - Sample Feature Module (Blog)
- **Section**: 4.4
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Implement using Ent client (shared from core)
## Requirements
- Implement using Ent client (shared from core)
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 4.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 4.5.1: Create `modules/blog/internal/service/post_service.go`:
## Metadata
- **Task ID**: 4.5.1
- **Title**: Create `modules/blog/internal/service/post_service.go`:
- **Phase**: 4 - Sample Feature Module (Blog)
- **Section**: 4.5
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Create `modules/blog/internal/service/post_service.go`:
## Requirements
- Create `modules/blog/internal/service/post_service.go`:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 4.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 4.6.1: Create `modules/blog/internal/api/handler.go`:
## Metadata
- **Task ID**: 4.6.1
- **Title**: Create `modules/blog/internal/api/handler.go`:
- **Phase**: 4 - Sample Feature Module (Blog)
- **Section**: 4.6
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Create `modules/blog/internal/api/handler.go`:
## Requirements
- Create `modules/blog/internal/api/handler.go`:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 4.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 ./...
```

View File

@@ -0,0 +1,46 @@
# Task 4.6.2: Use authorization middleware:
## Metadata
- **Task ID**: 4.6.2
- **Title**: Use authorization middleware:
- **Phase**: 4 - Sample Feature Module (Blog)
- **Section**: 4.6
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Use authorization middleware:
## Requirements
- Use authorization middleware:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 4.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 ./...
```
## Code Reference
```go
grp.Use(auth.RequirePermission(perm.BlogPostCreate))
```

View File

@@ -0,0 +1,40 @@
# Task 4.6.3: Register handlers in module's `Init()`
## Metadata
- **Task ID**: 4.6.3
- **Title**: Register handlers in module's `Init()`
- **Phase**: 4 - Sample Feature Module (Blog)
- **Section**: 4.6
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Register handlers in module's `Init()`
## Requirements
- Register handlers in module's `Init()`
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 4.6.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,70 @@
# Task 4.7.1: Create `modules/blog/pkg/module.go`:
## Metadata
- **Task ID**: 4.7.1
- **Title**: Create `modules/blog/pkg/module.go`:
- **Phase**: 4 - Sample Feature Module (Blog)
- **Section**: 4.7
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Create `modules/blog/pkg/module.go`:
## Requirements
- Create `modules/blog/pkg/module.go`:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 4.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 ./...
```
## Code Reference
```go
type BlogModule struct{}
func (b BlogModule) Name() string { return "blog" }
func (b BlogModule) Version() string { return "0.1.0" }
func (b BlogModule) Dependencies() []string { return nil }
func (b BlogModule) Init() fx.Option {
return fx.Options(
fx.Provide(NewPostRepo),
fx.Provide(NewPostService),
fx.Invoke(RegisterHandlers),
)
}
func (b BlogModule) Migrations() []func(*ent.Client) error {
return []func(*ent.Client) error{
func(c *ent.Client) error {
return c.Schema.Create(context.Background())
},
}
}
var Module BlogModule
func init() {
registry.Register(Module)
}
```

View File

@@ -0,0 +1,46 @@
# Task 4.8.1: Update main `go.mod` to include blog module:
## Metadata
- **Task ID**: 4.8.1
- **Title**: Update main `go.mod` to include blog module:
- **Phase**: 4 - Sample Feature Module (Blog)
- **Section**: 4.8
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Update main `go.mod` to include blog module:
## Requirements
- Update main `go.mod` to include blog module:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 4.8.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
replace github.com/yourorg/blog => ./modules/blog
```

View File

@@ -0,0 +1,46 @@
# Task 4.8.2: Import blog module in `cmd/platform/main.go`:
## Metadata
- **Task ID**: 4.8.2
- **Title**: Import blog module in `cmd/platform/main.go`:
- **Phase**: 4 - Sample Feature Module (Blog)
- **Section**: 4.8
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Import blog module in `cmd/platform/main.go`:
## Requirements
- Import blog module in `cmd/platform/main.go`:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 4.8.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
import _ "github.com/yourorg/blog/pkg"
```

View File

@@ -0,0 +1,40 @@
# Task 4.8.3: Run permission generation: `make generate`
## Metadata
- **Task ID**: 4.8.3
- **Title**: Run permission generation: `make generate`
- **Phase**: 4 - Sample Feature Module (Blog)
- **Section**: 4.8
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Run permission generation: `make generate`
## Requirements
- Run permission generation: `make generate`
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 4.8.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 4.8.4: Verify blog permissions are generated
## Metadata
- **Task ID**: 4.8.4
- **Title**: Verify blog permissions are generated
- **Phase**: 4 - Sample Feature Module (Blog)
- **Section**: 4.8
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Verify blog permissions are generated
## Requirements
- Verify blog permissions are generated
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 4.8.4 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 4.9.1: Create integration test `modules/blog/internal/api/handler_test.go`:
## Metadata
- **Task ID**: 4.9.1
- **Title**: Create integration test `modules/blog/internal/api/handler_test.go`:
- **Phase**: 4 - Sample Feature Module (Blog)
- **Section**: 4.9
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Create integration test `modules/blog/internal/api/handler_test.go`:
## Requirements
- Create integration test `modules/blog/internal/api/handler_test.go`:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 4.9.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 4.9.2: Add unit tests for service and repository
## Metadata
- **Task ID**: 4.9.2
- **Title**: Add unit tests for service and repository
- **Phase**: 4 - Sample Feature Module (Blog)
- **Section**: 4.9
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Add unit tests for service and repository
## Requirements
- Add unit tests for service and repository
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 4.9.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,47 @@
# Phase 4: Sample Feature Module (Blog)
## Overview
Create a sample blog module to demonstrate the module framework. This module will implement blog posts with CRUD operations, showing how to build a feature module that integrates with the core platform.
## Tasks
### 4.1 Module Setup
- [4.1.1 - Create Blog Module Directory](./4.1.1-create-modulesblog-directory.md)
- [4.1.2 - Initialize Go Module](./4.1.2-initialize-gomod.md)
### 4.2 Module Configuration
- [4.2.1 - Create Module Manifest](./4.2.1-create-modulesblogmoduleyaml.md)
### 4.3 Domain Layer
- [4.3.1 - Create Post Domain Model](./4.3.1-create-modulesbloginternaldomainpostgo.md)
- [4.3.2 - Create Ent Schema](./4.3.2-create-modulesbloginternalentschemapost.md)
- [4.3.3 - Generate Ent Code](./4.3.3-generate-ent-code-for-blog-module.md)
### 4.4 Repository Layer
- [4.4.1 - Create Post Repository Interface](./4.4.1-create-modulesbloginternaldomainpost_repogo.md)
- [4.4.2 - Implement Repository](./4.4.2-implement-using-ent-client-shared-from-core.md)
### 4.5 Service Layer
- [4.5.1 - Create Post Service](./4.5.1-create-modulesbloginternalservicepost_servicego.md)
### 4.6 API Layer
- [4.6.1 - Create API Handler](./4.6.1-create-modulesbloginternalapihandlergo.md)
## Deliverables Checklist
- [ ] Blog module directory structure created
- [ ] Module manifest defines permissions and routes
- [ ] Blog post domain model defined
- [ ] Ent schema for blog posts created
- [ ] Repository implements CRUD operations
- [ ] Service layer implements business logic
- [ ] API endpoints for blog posts working
- [ ] Module integrated with core platform
## Acceptance Criteria
- Blog module can be registered with core platform
- Permissions are generated for blog module
- CRUD operations work for blog posts
- API endpoints require proper authentication
- Module migrations run on startup
- Blog posts are associated with users