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

162
docs/content/stories/epic0/0.1-project-initialization.md Normal file
View File

@@ -0,0 +1,162 @@
# Story 0.1: Project Initialization and Repository Structure
## Metadata
- **Story ID**: 0.1
- **Title**: Project Initialization and Repository Structure
- **Epic**: 0 - Project Setup & Foundation
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 2-3 hours
- **Dependencies**: None
## Goal
Establish a properly structured Go project with all necessary directories, configuration files, and documentation that follows Go best practices and supports the platform's modular architecture.
## Description
This story covers the complete project initialization, including Go module setup, directory structure creation, and initial documentation. The project structure must support the microservices architecture with clear separation between core services, feature services (modules), and infrastructure.
## Deliverables
### 1. Go Module Initialization
- Initialize Go module with correct module path: `git.dcentral.systems/toolz/goplt`
- Set Go version to 1.24 in `go.mod`
- Verify module initialization with `go mod verify`
### 2. Complete Directory Structure
Create the following directory structure:
```
platform/
├── cmd/
│ └── platform/ # Main entry point
├── internal/ # Private implementation code
│ ├── di/ # Dependency injection container
│ ├── registry/ # Module registry
│ ├── pluginloader/ # Plugin loader (optional)
│ ├── config/ # Config implementation
│ ├── logger/ # Logger implementation
│ ├── infra/ # Infrastructure adapters
│ └── ent/ # Ent ORM schemas
├── pkg/ # Public interfaces (exported)
│ ├── config/ # ConfigProvider interface
│ ├── logger/ # Logger interface
│ ├── module/ # IModule interface
│ ├── auth/ # Auth interfaces
│ ├── perm/ # Permission DSL
│ └── infra/ # Infrastructure interfaces
├── modules/ # Feature modules
│ └── blog/ # Sample Blog module (Epic 4)
├── config/ # Configuration files
│ ├── default.yaml
│ ├── development.yaml
│ └── production.yaml
├── api/ # OpenAPI specs
├── scripts/ # Build/test scripts
├── docs/ # Documentation
├── ops/ # Operations (Grafana dashboards, etc.)
├── .github/
│ └── workflows/
│ └── ci.yml
├── Dockerfile
├── docker-compose.yml
├── docker-compose.test.yml
├── .gitignore
├── README.md
└── go.mod
```
### 3. .gitignore Configuration
- Exclude build artifacts (`bin/`, `dist/`)
- Exclude Go build cache
- Exclude IDE files (`.vscode/`, `.idea/`, etc.)
- Exclude test coverage files
- Exclude dependency directories
- Exclude environment-specific files
### 4. Initial README.md
Create comprehensive README with:
- Project overview and purpose
- Architecture overview
- Quick start guide
- Development setup instructions
- Directory structure explanation
- Links to documentation
- Contributing guidelines
### 5. Basic Documentation Structure
- Set up `docs/` directory
- Create architecture documentation placeholder
- Create API documentation structure
## Implementation Steps
1. **Initialize Go Module**
```bash
go mod init git.dcentral.systems/toolz/goplt
```
- Verify `go.mod` is created
- Set Go version constraint
2. **Create Directory Structure**
- Create all directories listed above
- Ensure proper nesting and organization
- Add placeholder `.gitkeep` files in empty directories if needed
3. **Configure .gitignore**
- Add Go-specific ignore patterns
- Add IDE-specific patterns
- Add OS-specific patterns
- Add build artifact patterns
4. **Create README.md**
- Write comprehensive project overview
- Document architecture principles
- Provide setup instructions
- Include example commands
5. **Verify Structure**
- Run `go mod verify`
- Check all directories exist
- Verify .gitignore works
- Test README formatting
## Acceptance Criteria
- [ ] `go mod init` creates module with correct path `git.dcentral.systems/toolz/goplt`
- [ ] Go version is set to `1.24` in `go.mod`
- [ ] All directories from the structure are in place
- [ ] `.gitignore` excludes build artifacts, dependencies, and IDE files
- [ ] `README.md` provides clear project overview and setup instructions
- [ ] Project structure matches architecture documentation
- [ ] `go mod verify` passes
- [ ] Directory structure follows Go best practices
## Related ADRs
- [ADR-0001: Go Module Path](../../adr/0001-go-module-path.md)
- [ADR-0002: Go Version](../../adr/0002-go-version.md)
- [ADR-0007: Project Directory Structure](../../adr/0007-project-directory-structure.md)
## Implementation Notes
- The module path should match the organization's Git hosting structure
- All internal packages must use `internal/` prefix to ensure they are not importable by external modules
- Public interfaces in `pkg/` should be minimal and well-documented
- Empty directories can have `.gitkeep` files to ensure they are tracked in Git
- The directory structure should be documented in the README
## Testing
```bash
# Verify module initialization
go mod verify
go mod tidy
# Check directory structure
tree -L 3 -a
# Verify .gitignore
git status
```
## Files to Create/Modify
- `go.mod` - Go module definition
- `README.md` - Project documentation
- `.gitignore` - Git ignore patterns
- All directory structure as listed above

171
docs/content/stories/epic0/0.2-configuration-management-system.md Normal file
View File

@@ -0,0 +1,171 @@
# Story 0.2: Configuration Management System
## Metadata
- **Story ID**: 0.2
- **Title**: Configuration Management System
- **Epic**: 0 - Project Setup & Foundation
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 4-6 hours
- **Dependencies**: 0.1
## Goal
Implement a flexible configuration system that loads settings from YAML files, environment variables, and supports type-safe access. The system must be injectable via DI and usable by all modules.
## Description
This story implements a complete configuration management system using Viper that provides a clean interface for accessing configuration values. The system supports multiple configuration sources (YAML files, environment variables) with proper precedence and type-safe accessors.
## Deliverables
### 1. Configuration Interface (`pkg/config/config.go`)
Define `ConfigProvider` interface with:
- `Get(key string) any` - Get any value
- `Unmarshal(v any) error` - Unmarshal into struct
- `GetString(key string) string` - Type-safe string getter
- `GetInt(key string) int` - Type-safe int getter
- `GetBool(key string) bool` - Type-safe bool getter
- `GetStringSlice(key string) []string` - Type-safe slice getter
- `GetDuration(key string) time.Duration` - Type-safe duration getter
- `IsSet(key string) bool` - Check if key exists
### 2. Viper Implementation (`internal/config/config.go`)
Implement `ConfigProvider` using Viper:
- Load `config/default.yaml` as baseline
- Merge environment-specific YAML files (development/production)
- Apply environment variable overrides (uppercase with underscores)
- Support nested configuration keys (dot notation)
- Provide all type-safe getters
- Support unmarshaling into structs
- Handle configuration validation errors
### 3. Configuration Loader (`internal/config/loader.go`)
- `LoadConfig(env string) (ConfigProvider, error)` function
- Environment detection (development/production)
- Configuration file discovery
- Validation of required configuration keys
- Error handling and reporting
### 4. Configuration Files
Create configuration files:
**`config/default.yaml`** - Base configuration:
```yaml
environment: development
server:
port: 8080
host: "0.0.0.0"
read_timeout: 30s
write_timeout: 30s
database:
driver: "postgres"
dsn: ""
max_connections: 25
max_idle_connections: 5
logging:
level: "info"
format: "json"
output: "stdout"
```
**`config/development.yaml`** - Development overrides:
```yaml
environment: development
logging:
level: "debug"
format: "console"
```
**`config/production.yaml`** - Production overrides:
```yaml
environment: production
logging:
level: "warn"
format: "json"
```
### 5. DI Integration
- Provider function for ConfigProvider
- Register in DI container
- Make configurable via FX
## Implementation Steps
1. **Install Dependencies**
```bash
go get github.com/spf13/viper@v1.18.0
go get github.com/spf13/cobra@v1.8.0
```
2. **Create Configuration Interface**
- Define `ConfigProvider` interface in `pkg/config/config.go`
- Add package documentation
- Export interface for use by modules
3. **Implement Viper Configuration**
- Create `internal/config/config.go`
- Implement all interface methods
- Handle configuration loading and merging
- Support nested keys and environment variables
4. **Create Configuration Loader**
- Implement `LoadConfig()` function
- Add environment detection logic
- Add validation logic
- Handle errors gracefully
5. **Create Configuration Files**
- Create `config/default.yaml` with base configuration
- Create `config/development.yaml` with dev overrides
- Create `config/production.yaml` with prod overrides
- Ensure proper YAML structure
6. **Integrate with DI**
- Create provider function
- Register in DI container
- Test injection
## Acceptance Criteria
- [ ] `ConfigProvider` interface is defined and documented
- [ ] Viper implementation loads YAML files successfully
- [ ] Environment variables override YAML values
- [ ] Type-safe getters work correctly (string, int, bool, etc.)
- [ ] Configuration can be unmarshaled into structs
- [ ] Nested keys work with dot notation
- [ ] Configuration system is injectable via DI container
- [ ] All modules can access configuration through interface
- [ ] Configuration validation works
- [ ] Error handling is comprehensive
## Related ADRs
- [ADR-0004: Configuration Management](../../adr/0004-configuration-management.md)
## Implementation Notes
- Use Viper's automatic environment variable support (uppercase with underscores)
- Support both single-level and nested configuration keys
- Consider adding configuration schema validation in future
- Environment variable format: `SERVER_PORT`, `DATABASE_DSN`, etc.
- Configuration files should be in YAML for readability
- Support secret manager integration placeholder (Epic 6)
## Testing
```bash
# Test configuration loading
go test ./internal/config/...
# Test type-safe getters
go run -c "test config getters"
# Test environment variable overrides
export SERVER_PORT=9090
go run cmd/platform/main.go
```
## Files to Create/Modify
- `pkg/config/config.go` - Configuration interface
- `internal/config/config.go` - Viper implementation
- `internal/config/loader.go` - Configuration loader
- `config/default.yaml` - Base configuration
- `config/development.yaml` - Development configuration
- `config/production.yaml` - Production configuration
- `internal/di/providers.go` - Add config provider

136
docs/content/stories/epic0/0.3-structured-logging-system.md Normal file
View File

@@ -0,0 +1,136 @@
# Story 0.3: Structured Logging System
## Metadata
- **Story ID**: 0.3
- **Title**: Structured Logging System
- **Epic**: 0 - Project Setup & Foundation
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 4-6 hours
- **Dependencies**: 0.1, 0.2
## Goal
Implement a production-ready logging system with structured JSON output, request correlation, and configurable log levels that can be used by all modules.
## Description
This story implements a complete logging system using Zap that provides structured logging, request correlation via request IDs, and context-aware logging. The system must support both development (human-readable) and production (JSON) formats.
## Deliverables
### 1. Logger Interface (`pkg/logger/logger.go`)
Define `Logger` interface with:
- `Debug(msg string, fields ...Field)` - Debug level logging
- `Info(msg string, fields ...Field)` - Info level logging
- `Warn(msg string, fields ...Field)` - Warning level logging
- `Error(msg string, fields ...Field)` - Error level logging
- `With(fields ...Field) Logger` - Create child logger with fields
- `WithContext(ctx context.Context) Logger` - Create logger with context fields
- `Field` type for structured fields
- Package-level convenience functions
### 2. Zap Implementation (`internal/logger/zap_logger.go`)
Implement `Logger` interface using Zap:
- Structured JSON logging for production mode
- Human-readable console logging for development mode
- Configurable log levels (debug, info, warn, error)
- Request-scoped fields support
- Context-aware logging (extract request ID, user ID from context)
- Field mapping to Zap fields
- Error stack trace support
### 3. Request ID Middleware (`internal/logger/middleware.go`)
Gin middleware for request correlation:
- Generate unique request ID per HTTP request
- Add request ID to request context
- Add request ID to all logs within request context
- Return request ID in response headers (`X-Request-ID`)
- Support for existing request IDs in headers
### 4. Global Logger Export (`pkg/logger/global.go`)
- Export default logger instance
- Package-level convenience functions
- Thread-safe logger access
### 5. DI Integration
- Provider function for Logger
- Register in DI container
- Make configurable via FX
## Implementation Steps
1. **Install Dependencies**
```bash
go get go.uber.org/zap@v1.26.0
```
2. **Create Logger Interface**
- Define `Logger` interface in `pkg/logger/logger.go`
- Define `Field` type for structured fields
- Add package documentation
3. **Implement Zap Logger**
- Create `internal/logger/zap_logger.go`
- Implement all interface methods
- Support both JSON and console encoders
- Handle log levels and field mapping
4. **Create Request ID Middleware**
- Create `internal/logger/middleware.go`
- Implement Gin middleware
- Generate and propagate request IDs
- Add to response headers
5. **Add Global Logger**
- Create `pkg/logger/global.go`
- Export default logger
- Add convenience functions
6. **Integrate with DI**
- Create provider function
- Register in DI container
- Test injection
## Acceptance Criteria
- [ ] `Logger` interface is defined and documented
- [ ] Zap implementation supports JSON and console formats
- [ ] Log levels are configurable and respected
- [ ] Request IDs are generated and included in all logs
- [ ] Request ID middleware works with Gin
- [ ] Context-aware logging extracts request ID and user ID
- [ ] Logger can be injected via DI container
- [ ] All modules can use logger through interface
- [ ] Request correlation works across service boundaries
- [ ] Structured fields work correctly
## Related ADRs
- [ADR-0005: Logging Framework](../../adr/0005-logging-framework.md)
- [ADR-0012: Logger Interface Design](../../adr/0012-logger-interface-design.md)
## Implementation Notes
- Use Zap's production and development presets
- Request IDs should be UUIDs or similar unique identifiers
- Context should be propagated through all service calls
- Log levels should be configurable via configuration system
- Consider adding log sampling for high-volume production
- Support for log rotation and file output (future enhancement)
## Testing
```bash
# Test logger interface
go test ./pkg/logger/...
# Test Zap implementation
go test ./internal/logger/...
# Test request ID middleware
go test ./internal/logger/... -run TestRequestIDMiddleware
```
## Files to Create/Modify
- `pkg/logger/logger.go` - Logger interface
- `pkg/logger/global.go` - Global logger export
- `internal/logger/zap_logger.go` - Zap implementation
- `internal/logger/middleware.go` - Request ID middleware
- `internal/di/providers.go` - Add logger provider
- `config/default.yaml` - Add logging configuration

126
docs/content/stories/epic0/0.4-cicd-pipeline.md Normal file
View File

@@ -0,0 +1,126 @@
# Story 0.4: CI/CD Pipeline and Development Tooling
## Metadata
- **Story ID**: 0.4
- **Title**: CI/CD Pipeline and Development Tooling
- **Epic**: 0 - Project Setup & Foundation
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 3-4 hours
- **Dependencies**: 0.1
## Goal
Establish automated testing, linting, and build processes with a developer-friendly Makefile that enables efficient development workflow.
## Description
This story sets up the complete CI/CD pipeline using GitHub Actions and provides a comprehensive Makefile with common development commands. The pipeline should run on every push and pull request, ensuring code quality and buildability.
## Deliverables
### 1. GitHub Actions Workflow (`.github/workflows/ci.yml`)
Complete CI pipeline with:
- Go 1.24 setup
- Go module caching for faster builds
- Linting with golangci-lint or staticcheck
- Unit tests execution
- Test coverage reporting
- Binary build validation
- Code formatting validation (gofmt)
- Artifact uploads for build outputs
### 2. Comprehensive Makefile
Developer-friendly Makefile with commands:
- `make test` - Run all tests
- `make test-coverage` - Run tests with coverage report
- `make lint` - Run linters
- `make fmt` - Format code
- `make fmt-check` - Check code formatting
- `make build` - Build platform binary
- `make clean` - Clean build artifacts
- `make docker-build` - Build Docker image
- `make docker-run` - Run Docker container
- `make generate` - Run code generation
- `make verify` - Verify code (fmt, lint, test)
- `make help` - Show available commands
### 3. Linter Configuration
- `.golangci.yml` or similar linter config
- Configured rules and exclusions
- Reasonable defaults for Go projects
### 4. Pre-commit Hooks (Optional)
- Git hooks for formatting and linting
- Prevent committing unformatted code
## Implementation Steps
1. **Create GitHub Actions Workflow**
- Create `.github/workflows/ci.yml`
- Set up Go environment
- Configure module caching
- Add linting step
- Add testing step
- Add build step
- Add artifact uploads
2. **Create Makefile**
- Define common variables (GO, BINARY_NAME, etc.)
- Add test target
- Add lint target
- Add build target
- Add format targets
- Add Docker targets
- Add help target
3. **Configure Linter**
- Install golangci-lint or configure staticcheck
- Create linter configuration file
- Set up reasonable rules
4. **Test CI Pipeline**
- Push changes to trigger CI
- Verify all steps pass
- Check artifact uploads
## Acceptance Criteria
- [ ] CI pipeline runs on every push and PR
- [ ] All linting checks pass
- [ ] Tests run successfully (even if empty initially)
- [ ] Binary builds successfully
- [ ] Docker image builds successfully
- [ ] Makefile commands work as expected
- [ ] CI pipeline fails fast on errors
- [ ] Code formatting is validated
- [ ] Test coverage is reported
- [ ] Artifacts are uploaded correctly
## Related ADRs
- [ADR-0010: CI/CD Platform](../../adr/0010-ci-cd-platform.md)
## Implementation Notes
- Use Go 1.24 in CI to match project requirements
- Cache Go modules to speed up CI runs
- Use golangci-lint for comprehensive linting
- Set up test coverage threshold (e.g., 80%)
- Make sure CI fails on any error
- Consider adding security scanning (gosec) in future
- Docker builds should use multi-stage builds
## Testing
```bash
# Test Makefile commands
make test
make lint
make build
make clean
# Test CI locally (using act or similar)
act push
```
## Files to Create/Modify
- `.github/workflows/ci.yml` - GitHub Actions workflow
- `Makefile` - Development commands
- `.golangci.yml` - Linter configuration (optional)
- `.git/hooks/pre-commit` - Pre-commit hooks (optional)

122
docs/content/stories/epic0/0.5-di-and-bootstrap.md Normal file
View File

@@ -0,0 +1,122 @@
# Story 0.5: Dependency Injection and Application Bootstrap
## Metadata
- **Story ID**: 0.5
- **Title**: Dependency Injection and Application Bootstrap
- **Epic**: 0 - Project Setup & Foundation
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 4-5 hours
- **Dependencies**: 0.1, 0.2, 0.3
## Goal
Set up dependency injection container using Uber FX and create the application entry point that initializes the platform with proper lifecycle management.
## Description
This story implements the dependency injection system using Uber FX and creates the main application entry point. The DI container will manage service lifecycle, dependencies, and provide a clean way to wire services together.
## Deliverables
### 1. DI Container (`internal/di/container.go`)
FX-based dependency injection container:
- Initialize FX container
- Register Config and Logger providers
- Basic lifecycle hooks (OnStart, OnStop)
- Support service overrides for testing
- Graceful shutdown handling
### 2. DI Providers (`internal/di/providers.go`)
Provider functions for core services:
- `ProvideConfig() fx.Option` - Configuration provider
- `ProvideLogger() fx.Option` - Logger provider
- Provider functions return FX options for easy composition
### 3. Application Entry Point (`cmd/platform/main.go`)
Main application bootstrap:
- Load configuration
- Initialize DI container with core services
- Set up basic application lifecycle
- Start minimal HTTP server (placeholder for Epic 1)
- Handle graceful shutdown (SIGINT, SIGTERM)
- Proper error handling and logging
### 4. Core Module (`internal/di/core_module.go`)
Optional: Export core module as FX option:
- `CoreModule() fx.Option` - Provides all core services
- Easy to compose with future modules
## Implementation Steps
1. **Install Dependencies**
```bash
go get go.uber.org/fx@latest
```
2. **Create DI Container**
- Create `internal/di/container.go`
- Initialize FX app
- Set up lifecycle hooks
- Add graceful shutdown
3. **Create Provider Functions**
- Create `internal/di/providers.go`
- Implement `ProvideConfig()` function
- Implement `ProvideLogger()` function
- Return FX options
4. **Create Application Entry Point**
- Create `cmd/platform/main.go`
- Load configuration
- Initialize FX app with providers
- Set up signal handling
- Start minimal server (placeholder)
- Handle shutdown gracefully
5. **Test Application**
- Verify application starts
- Verify graceful shutdown works
- Test service injection
## Acceptance Criteria
- [ ] DI container initializes successfully
- [ ] Config and Logger are provided via DI
- [ ] Application starts and runs
- [ ] Application shuts down gracefully on signals
- [ ] Lifecycle hooks work correctly
- [ ] Services can be overridden for testing
- [ ] Application compiles and runs successfully
- [ ] Error handling is comprehensive
- [ ] Logging works during startup/shutdown
## Related ADRs
- [ADR-0003: Dependency Injection Framework](../../adr/0003-dependency-injection-framework.md)
## Implementation Notes
- Use FX for dependency injection and lifecycle management
- Support graceful shutdown with context cancellation
- Handle SIGINT and SIGTERM signals
- Log startup and shutdown events
- Make services easily testable via interfaces
- Consider adding health check endpoint in future
- Support for service overrides is important for testing
## Testing
```bash
# Test application startup
go run cmd/platform/main.go
# Test graceful shutdown
# Start app, then send SIGTERM
kill -TERM <pid>
# Test DI container
go test ./internal/di/...
```
## Files to Create/Modify
- `internal/di/container.go` - DI container
- `internal/di/providers.go` - Provider functions
- `internal/di/core_module.go` - Core module (optional)
- `cmd/platform/main.go` - Application entry point
- `go.mod` - Add FX dependency

46
docs/content/stories/epic0/README.md Normal file
View File

@@ -0,0 +1,46 @@
# Epic 0: Project Setup & Foundation
## Overview
Initialize repository structure with proper Go project layout, implement configuration management system, establish structured logging system, set up CI/CD pipeline and development tooling, and bootstrap dependency injection and application entry point.
## Stories
### 0.1 Project Initialization and Repository Structure
- [Story: 0.1 - Project Initialization](./0.1-project-initialization.md)
- **Goal:** Establish a properly structured Go project with all necessary directories, configuration files, and documentation.
- **Deliverables:** Go module initialization, complete directory structure, .gitignore, comprehensive README.md
### 0.2 Configuration Management System
- [Story: 0.2 - Configuration Management System](./0.2-configuration-management-system.md)
- **Goal:** Implement a flexible configuration system that loads settings from YAML files, environment variables, and supports type-safe access.
- **Deliverables:** ConfigProvider interface, Viper implementation, configuration files, DI integration
### 0.3 Structured Logging System
- [Story: 0.3 - Structured Logging System](./0.3-structured-logging-system.md)
- **Goal:** Implement a production-ready logging system with structured JSON output, request correlation, and configurable log levels.
- **Deliverables:** Logger interface, Zap implementation, request ID middleware, context-aware logging
### 0.4 CI/CD Pipeline and Development Tooling
- [Story: 0.4 - CI/CD Pipeline and Development Tooling](./0.4-cicd-pipeline.md)
- **Goal:** Establish automated testing, linting, and build processes with a developer-friendly Makefile.
- **Deliverables:** GitHub Actions workflow, comprehensive Makefile, build automation
### 0.5 Dependency Injection and Application Bootstrap
- [Story: 0.5 - Dependency Injection and Application Bootstrap](./0.5-di-and-bootstrap.md)
- **Goal:** Set up dependency injection container using Uber FX and create the application entry point that initializes the platform.
- **Deliverables:** DI container, FX providers, application entry point, lifecycle management
## Deliverables Checklist
- [ ] Repository structure in place
- [ ] Configuration system loads YAML files and env vars
- [ ] Structured logging works
- [ ] CI pipeline runs linting and builds binary
- [ ] Basic DI container initialized
## Acceptance Criteria
- `go build ./cmd/platform` succeeds
- `go test ./...` runs (even if tests are empty)
- CI pipeline passes on empty commit
- Config loads from `config/default.yaml`
- Logger can be injected and used
- Application starts and shuts down gracefully