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

162
docs/content/stories/phase0/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
- **Phase**: 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 (Phase 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

47
docs/content/stories/phase0/0.1.1-initialize-go-module-go-mod-init-githubcomyourorgp.md
View File

@@ -1,47 +0,0 @@
# Task 0.1.1: Initialize Go Module
## Metadata
- **Task ID**: 0.1.1
- **Title**: Initialize Go Module
- **Phase**: 0 - Project Setup & Foundation
- **Section**: 0.1 Repository Bootstrap
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 5 minutes
- **Dependencies**: None
## Description
Initialize the Go module with the correct module path for the platform.
## Requirements
- Use module path: `git.dcentral.systems/toolz/goplt`
- Go version: 1.24.3
- Ensure `go.mod` file is created correctly
## Implementation Steps
1. Run `go mod init git.dcentral.systems/toolz/goplt` in the project root
2. Verify `go.mod` file is created with correct module path
3. Set Go version in `go.mod`: `go 1.24`
## Acceptance Criteria
- [ ] `go.mod` file exists in project root
- [ ] Module path is `git.dcentral.systems/toolz/goplt`
- [ ] Go version is set to `1.24`
- [ ] `go mod verify` passes
## Related ADRs
- [ADR-0001: Go Module Path](../../adr/0001-go-module-path.md)
- [ADR-0002: Go Version](../../adr/0002-go-version.md)
## Implementation Notes
- Ensure the module path matches the organization's Git hosting structure
- The module path will be used for all internal imports
- Update any documentation that references placeholder module paths
## Testing
```bash
# Verify module initialization
go mod verify
go mod tidy
```

47
docs/content/stories/phase0/0.1.1-initialize-go-module.md
View File

@@ -1,47 +0,0 @@
# Task 0.1.1: Initialize Go Module
## Metadata
- **Task ID**: 0.1.1
- **Title**: Initialize Go Module
- **Phase**: 0 - Project Setup & Foundation
- **Section**: 0.1 Repository Bootstrap
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 5 minutes
- **Dependencies**: None
## Description
Initialize the Go module with the correct module path for the platform.
## Requirements
- Use module path: `git.dcentral.systems/toolz/goplt`
- Go version: 1.24.3
- Ensure `go.mod` file is created correctly
## Implementation Steps
1. Run `go mod init git.dcentral.systems/toolz/goplt` in the project root
2. Verify `go.mod` file is created with correct module path
3. Set Go version in `go.mod`: `go 1.24`
## Acceptance Criteria
- [ ] `go.mod` file exists in project root
- [ ] Module path is `git.dcentral.systems/toolz/goplt`
- [ ] Go version is set to `1.24`
- [ ] `go mod verify` passes
## Related ADRs
- [ADR-0001: Go Module Path](../../adr/0001-go-module-path.md)
- [ADR-0002: Go Version](../../adr/0002-go-version.md)
## Implementation Notes
- Ensure the module path matches the organization's Git hosting structure
- The module path will be used for all internal imports
- Update any documentation that references placeholder module paths
## Testing
```bash
# Verify module initialization
go mod verify
go mod tidy
```

77
docs/content/stories/phase0/0.1.2-create-directory-structure.md
View File

@@ -1,77 +0,0 @@
# Task 0.1.2: Create directory structure:
## Metadata
- **Task ID**: 0.1.2
- **Title**: Create directory structure:
- **Phase**: 0 - Project Setup & Foundation
- **Section**: 0.1
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Create directory structure:
## Requirements
- Create directory structure:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 0.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
platform/
├── cmd/
│ └── platform/ # Main entry point
├── internal/ # Private implementation code
│ ├── di/ # Dependency injection container
│ ├── registry/ # Module registry
│ ├── pluginloader/ # Plugin loader (optional)
│ └── infra/ # Infrastructure adapters
├── 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 (Phase 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
└── go.mod
```

56
docs/content/stories/phase0/0.1.3-add-gitignore-for-go-projects.md
View File

@@ -1,56 +0,0 @@
# Task 0.1.3: Add Gitignore
## Metadata
- **Task ID**: 0.1.3
- **Title**: Add Gitignore
- **Phase**: 0 - Project Setup & Foundation
- **Section**: 0.1 Repository Bootstrap
- **Status**: Pending
- **Priority**: Medium
- **Estimated Time**: 5 minutes
- **Dependencies**: 0.1.1
## Description
Create a comprehensive `.gitignore` file for Go projects that excludes build artifacts, dependencies, IDE files, and sensitive data.
## Requirements
- Ignore Go build artifacts
- Ignore dependency caches
- Ignore IDE-specific files
- Ignore environment-specific files
- Ignore secrets and sensitive data
## Implementation Steps
1. Create `.gitignore` in project root
2. Add standard Go ignores:
- `*.exe`, `*.exe~`, `*.dll`, `*.so`, `*.dylib`
- `*.test`, `*.out`
- `go.work`, `go.work.sum`
3. Add IDE ignores:
- `.vscode/`, `.idea/`, `*.swp`, `*.swo`
4. Add environment ignores:
- `.env`, `.env.local`, `config/secrets/`
5. Add OS ignores:
- `.DS_Store`, `Thumbs.db`
6. Add build artifacts:
- `bin/`, `dist/`, `tmp/`
## Acceptance Criteria
- [ ] `.gitignore` file exists
- [ ] Common Go artifacts are ignored
- [ ] IDE files are ignored
- [ ] Sensitive files are ignored
- [ ] Test with `git status` to verify
## Implementation Notes
- Use standard Go `.gitignore` templates
- Ensure `config/secrets/` is ignored (for secret files)
- Consider adding `*.log` for log files
## Testing
```bash
# Verify gitignore works
git status
# Should not show build artifacts or IDE files
```

56
docs/content/stories/phase0/0.1.3-add-gitignore.md
View File

@@ -1,56 +0,0 @@
# Task 0.1.3: Add Gitignore
## Metadata
- **Task ID**: 0.1.3
- **Title**: Add Gitignore
- **Phase**: 0 - Project Setup & Foundation
- **Section**: 0.1 Repository Bootstrap
- **Status**: Pending
- **Priority**: Medium
- **Estimated Time**: 5 minutes
- **Dependencies**: 0.1.1
## Description
Create a comprehensive `.gitignore` file for Go projects that excludes build artifacts, dependencies, IDE files, and sensitive data.
## Requirements
- Ignore Go build artifacts
- Ignore dependency caches
- Ignore IDE-specific files
- Ignore environment-specific files
- Ignore secrets and sensitive data
## Implementation Steps
1. Create `.gitignore` in project root
2. Add standard Go ignores:
- `*.exe`, `*.exe~`, `*.dll`, `*.so`, `*.dylib`
- `*.test`, `*.out`
- `go.work`, `go.work.sum`
3. Add IDE ignores:
- `.vscode/`, `.idea/`, `*.swp`, `*.swo`
4. Add environment ignores:
- `.env`, `.env.local`, `config/secrets/`
5. Add OS ignores:
- `.DS_Store`, `Thumbs.db`
6. Add build artifacts:
- `bin/`, `dist/`, `tmp/`
## Acceptance Criteria
- [ ] `.gitignore` file exists
- [ ] Common Go artifacts are ignored
- [ ] IDE files are ignored
- [ ] Sensitive files are ignored
- [ ] Test with `git status` to verify
## Implementation Notes
- Use standard Go `.gitignore` templates
- Ensure `config/secrets/` is ignored (for secret files)
- Consider adding `*.log` for log files
## Testing
```bash
# Verify gitignore works
git status
# Should not show build artifacts or IDE files
```

63
docs/content/stories/phase0/0.1.4-create-initial-readme.md
View File

@@ -1,63 +0,0 @@
# Task 0.1.4: Create Initial README
## Metadata
- **Task ID**: 0.1.4
- **Title**: Create Initial README
- **Phase**: 0 - Project Setup & Foundation
- **Section**: 0.1 Repository Bootstrap
- **Status**: Pending
- **Priority**: Medium
- **Estimated Time**: 20 minutes
- **Dependencies**: 0.1.1
## Description
Create an initial `README.md` file that provides an overview of the project, its purpose, architecture, and quick start instructions.
## Requirements
- Project overview and description
- Architecture overview
- Quick start guide
- Links to documentation
- Build and run instructions
## Implementation Steps
1. Create `README.md` in project root
2. Add project title and description
3. Add architecture overview section
4. Add quick start instructions
5. Add links to documentation (`docs/`)
6. Add build and run commands
7. Add contribution guidelines (placeholder)
## Acceptance Criteria
- [ ] `README.md` exists
- [ ] Project overview is clear
- [ ] Quick start instructions are present
- [ ] Links to documentation work
- [ ] Build instructions are accurate
## Implementation Notes
- Keep README concise but informative
- Update as project evolves
- Include badges (build status, etc.) later
- Reference ADRs for architecture decisions
## Content Structure
```markdown
# Go Platform (goplt)
[Description]
## Architecture
[Overview]
## Quick Start
[Instructions]
## Documentation
[Links]
## Development
[Setup instructions]
```

63
docs/content/stories/phase0/0.1.4-create-initial-readmemd-with-project-overview.md
View File

@@ -1,63 +0,0 @@
# Task 0.1.4: Create Initial README
## Metadata
- **Task ID**: 0.1.4
- **Title**: Create Initial README
- **Phase**: 0 - Project Setup & Foundation
- **Section**: 0.1 Repository Bootstrap
- **Status**: Pending
- **Priority**: Medium
- **Estimated Time**: 20 minutes
- **Dependencies**: 0.1.1
## Description
Create an initial `README.md` file that provides an overview of the project, its purpose, architecture, and quick start instructions.
## Requirements
- Project overview and description
- Architecture overview
- Quick start guide
- Links to documentation
- Build and run instructions
## Implementation Steps
1. Create `README.md` in project root
2. Add project title and description
3. Add architecture overview section
4. Add quick start instructions
5. Add links to documentation (`docs/`)
6. Add build and run commands
7. Add contribution guidelines (placeholder)
## Acceptance Criteria
- [ ] `README.md` exists
- [ ] Project overview is clear
- [ ] Quick start instructions are present
- [ ] Links to documentation work
- [ ] Build instructions are accurate
## Implementation Notes
- Keep README concise but informative
- Update as project evolves
- Include badges (build status, etc.) later
- Reference ADRs for architecture decisions
## Content Structure
```markdown
# Go Platform (goplt)
[Description]
## Architecture
[Overview]
## Quick Start
[Instructions]
## Documentation
[Links]
## Development
[Setup instructions]
```

171
docs/content/stories/phase0/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
- **Phase**: 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 (Phase 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

47
docs/content/stories/phase0/0.2.1-install-config-dependencies.md
View File

@@ -1,47 +0,0 @@
# Task 0.2.1: Install Configuration Dependencies
## Metadata
- **Task ID**: 0.2.1
- **Title**: Install Configuration Dependencies
- **Phase**: 0 - Project Setup & Foundation
- **Section**: 0.2 Configuration System
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 5 minutes
- **Dependencies**: 0.1.1
## Description
Install Viper and Cobra packages for configuration management and CLI support.
## Requirements
- Install `github.com/spf13/viper` v1.18.0+
- Install `github.com/spf13/cobra` v1.8.0+
- Add to `go.mod` with proper version constraints
## Implementation Steps
1. Run `go get github.com/spf13/viper@v1.18.0`
2. Run `go get github.com/spf13/cobra@v1.8.0`
3. Run `go mod tidy` to update dependencies
4. Verify packages in `go.mod`
## Acceptance Criteria
- [ ] Viper is listed in `go.mod`
- [ ] Cobra is listed in `go.mod`
- [ ] `go mod verify` passes
- [ ] Dependencies are properly versioned
## Related ADRs
- [ADR-0004: Configuration Management](../../adr/0004-configuration-management.md)
## Implementation Notes
- Use specific versions for reproducibility
- Consider using `go get -u` for latest patch versions
- Document version choices in ADR
## Testing
```bash
go mod verify
go list -m github.com/spf13/viper
go list -m github.com/spf13/cobra
```

47
docs/content/stories/phase0/0.2.1-install-githubcomspf13viper-and-githubcomspf13cobr.md
View File

@@ -1,47 +0,0 @@
# Task 0.2.1: Install Configuration Dependencies
## Metadata
- **Task ID**: 0.2.1
- **Title**: Install Configuration Dependencies
- **Phase**: 0 - Project Setup & Foundation
- **Section**: 0.2 Configuration System
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 5 minutes
- **Dependencies**: 0.1.1
## Description
Install Viper and Cobra packages for configuration management and CLI support.
## Requirements
- Install `github.com/spf13/viper` v1.18.0+
- Install `github.com/spf13/cobra` v1.8.0+
- Add to `go.mod` with proper version constraints
## Implementation Steps
1. Run `go get github.com/spf13/viper@v1.18.0`
2. Run `go get github.com/spf13/cobra@v1.8.0`
3. Run `go mod tidy` to update dependencies
4. Verify packages in `go.mod`
## Acceptance Criteria
- [ ] Viper is listed in `go.mod`
- [ ] Cobra is listed in `go.mod`
- [ ] `go mod verify` passes
- [ ] Dependencies are properly versioned
## Related ADRs
- [ADR-0004: Configuration Management](../../adr/0004-configuration-management.md)
## Implementation Notes
- Use specific versions for reproducibility
- Consider using `go get -u` for latest patch versions
- Document version choices in ADR
## Testing
```bash
go mod verify
go list -m github.com/spf13/viper
go list -m github.com/spf13/cobra
```

59
docs/content/stories/phase0/0.2.2-create-config-interface.md
View File

@@ -1,59 +0,0 @@
# Task 0.2.2: Create Config Interface
## Metadata
- **Task ID**: 0.2.2
- **Title**: Create Config Interface
- **Phase**: 0 - Project Setup & Foundation
- **Section**: 0.2 Configuration System
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 15 minutes
- **Dependencies**: 0.2.1
## Description
Create the `ConfigProvider` interface in `pkg/config/` to abstract configuration access. This interface will be used by all modules and services.
## Requirements
- Define interface in `pkg/config/config.go`
- Include methods for type-safe access
- Support nested configuration keys
- Support unmarshaling into structs
## Implementation Steps
1. Create `pkg/config/config.go`
2. Define `ConfigProvider` interface:
```go
type ConfigProvider interface {
Get(key string) any
Unmarshal(v any) error
GetString(key string) string
GetInt(key string) int
GetBool(key string) bool
GetStringSlice(key string) []string
}
```
3. Add package documentation
4. Export interface for use by modules
## Acceptance Criteria
- [ ] `pkg/config/config.go` exists
- [ ] `ConfigProvider` interface is defined
- [ ] Interface methods match requirements
- [ ] Package documentation is present
- [ ] Interface compiles without errors
## Related ADRs
- [ADR-0004: Configuration Management](../../adr/0004-configuration-management.md)
## Implementation Notes
- Interface should be minimal and focused
- Additional methods can be added later if needed
- Consider adding `GetDuration()` for time.Duration values
- Consider adding `IsSet(key string) bool` to check if key exists
## Testing
```bash
go build ./pkg/config
go vet ./pkg/config
```

59
docs/content/stories/phase0/0.2.2-create-pkgconfigconfiggo-interface.md
View File

@@ -1,59 +0,0 @@
# Task 0.2.2: Create Config Interface
## Metadata
- **Task ID**: 0.2.2
- **Title**: Create Config Interface
- **Phase**: 0 - Project Setup & Foundation
- **Section**: 0.2 Configuration System
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 15 minutes
- **Dependencies**: 0.2.1
## Description
Create the `ConfigProvider` interface in `pkg/config/` to abstract configuration access. This interface will be used by all modules and services.
## Requirements
- Define interface in `pkg/config/config.go`
- Include methods for type-safe access
- Support nested configuration keys
- Support unmarshaling into structs
## Implementation Steps
1. Create `pkg/config/config.go`
2. Define `ConfigProvider` interface:
```go
type ConfigProvider interface {
Get(key string) any
Unmarshal(v any) error
GetString(key string) string
GetInt(key string) int
GetBool(key string) bool
GetStringSlice(key string) []string
}
```
3. Add package documentation
4. Export interface for use by modules
## Acceptance Criteria
- [ ] `pkg/config/config.go` exists
- [ ] `ConfigProvider` interface is defined
- [ ] Interface methods match requirements
- [ ] Package documentation is present
- [ ] Interface compiles without errors
## Related ADRs
- [ADR-0004: Configuration Management](../../adr/0004-configuration-management.md)
## Implementation Notes
- Interface should be minimal and focused
- Additional methods can be added later if needed
- Consider adding `GetDuration()` for time.Duration values
- Consider adding `IsSet(key string) bool` to check if key exists
## Testing
```bash
go build ./pkg/config
go vet ./pkg/config
```

60
docs/content/stories/phase0/0.2.3-implement-config-loader.md
View File

@@ -1,60 +0,0 @@
# Task 0.2.3: Implement Config Loader
## Metadata
- **Task ID**: 0.2.3
- **Title**: Implement Config Loader
- **Phase**: 0 - Project Setup & Foundation
- **Section**: 0.2 Configuration System
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 30 minutes
- **Dependencies**: 0.2.1, 0.2.2
## Description
Implement the Viper-based configuration loader in `internal/config/` that implements the `ConfigProvider` interface. This loader will handle hierarchical configuration loading from files and environment variables.
## Requirements
- Implement `ConfigProvider` interface using Viper
- Load configuration in order: defaults → environment-specific → env vars
- Support YAML configuration files
- Support environment variable overrides
- Provide placeholder for secret manager integration (Phase 6)
## Implementation Steps
1. Create `internal/config/config.go`:
- Implement `ConfigProvider` interface
- Wrap Viper instance
- Implement all interface methods
2. Create `internal/config/loader.go`:
- `LoadConfig()` function
- Load `config/default.yaml` as baseline
- Merge environment-specific YAML (development/production)
- Apply environment variable overrides
- Set up automatic environment variable binding
3. Add error handling for missing config files
4. Add logging for configuration loading
## Acceptance Criteria
- [ ] `internal/config/config.go` implements `ConfigProvider`
- [ ] `internal/config/loader.go` has `LoadConfig()` function
- [ ] Configuration loads from `config/default.yaml`
- [ ] Environment-specific configs are merged correctly
- [ ] Environment variables override file values
- [ ] Errors are handled gracefully
## Related ADRs
- [ADR-0004: Configuration Management](../../adr/0004-configuration-management.md)
## Implementation Notes
- Use Viper's `SetConfigName()` and `AddConfigPath()`
- Use `MergeInConfig()` for environment-specific files
- Use `AutomaticEnv()` for environment variable binding
- Set environment variable prefix (e.g., `GOPLT_`)
- Use `SetEnvKeyReplacer()` to replace dots with underscores
## Testing
```bash
# Test config loading
go test ./internal/config -v
```

60
docs/content/stories/phase0/0.2.3-implement-internalconfigconfiggo-using-viper.md
View File

@@ -1,60 +0,0 @@
# Task 0.2.3: Implement Config Loader
## Metadata
- **Task ID**: 0.2.3
- **Title**: Implement Config Loader
- **Phase**: 0 - Project Setup & Foundation
- **Section**: 0.2 Configuration System
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 30 minutes
- **Dependencies**: 0.2.1, 0.2.2
## Description
Implement the Viper-based configuration loader in `internal/config/` that implements the `ConfigProvider` interface. This loader will handle hierarchical configuration loading from files and environment variables.
## Requirements
- Implement `ConfigProvider` interface using Viper
- Load configuration in order: defaults → environment-specific → env vars
- Support YAML configuration files
- Support environment variable overrides
- Provide placeholder for secret manager integration (Phase 6)
## Implementation Steps
1. Create `internal/config/config.go`:
- Implement `ConfigProvider` interface
- Wrap Viper instance
- Implement all interface methods
2. Create `internal/config/loader.go`:
- `LoadConfig()` function
- Load `config/default.yaml` as baseline
- Merge environment-specific YAML (development/production)
- Apply environment variable overrides
- Set up automatic environment variable binding
3. Add error handling for missing config files
4. Add logging for configuration loading
## Acceptance Criteria
- [ ] `internal/config/config.go` implements `ConfigProvider`
- [ ] `internal/config/loader.go` has `LoadConfig()` function
- [ ] Configuration loads from `config/default.yaml`
- [ ] Environment-specific configs are merged correctly
- [ ] Environment variables override file values
- [ ] Errors are handled gracefully
## Related ADRs
- [ADR-0004: Configuration Management](../../adr/0004-configuration-management.md)
## Implementation Notes
- Use Viper's `SetConfigName()` and `AddConfigPath()`
- Use `MergeInConfig()` for environment-specific files
- Use `AutomaticEnv()` for environment variable binding
- Set environment variable prefix (e.g., `GOPLT_`)
- Use `SetEnvKeyReplacer()` to replace dots with underscores
## Testing
```bash
# Test config loading
go test ./internal/config -v
```

67
docs/content/stories/phase0/0.2.4-create-configdefaultyaml-with-basic-structure.md
View File

@@ -1,67 +0,0 @@
# Task 0.2.4: Create Configuration Files
## Metadata
- **Task ID**: 0.2.4
- **Title**: Create Configuration Files
- **Phase**: 0 - Project Setup & Foundation
- **Section**: 0.2 Configuration System
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 15 minutes
- **Dependencies**: 0.1.2
## Description
Create the baseline configuration YAML files that define the default configuration structure for the platform.
## Requirements
- Create `config/default.yaml` with baseline values
- Create `config/development.yaml` with development overrides
- Create `config/production.yaml` with production overrides
- Define configuration schema for all core services
## Implementation Steps
1. Create `config/default.yaml`:
```yaml
environment: development
server:
port: 8080
host: "0.0.0.0"
database:
driver: "postgres"
dsn: ""
logging:
level: "info"
format: "json"
```
2. Create `config/development.yaml`:
- Override logging level to "debug"
- Add development-specific settings
3. Create `config/production.yaml`:
- Override logging level to "warn"
- Add production-specific settings
4. Document configuration options
## Acceptance Criteria
- [ ] `config/default.yaml` exists with complete structure
- [ ] `config/development.yaml` exists
- [ ] `config/production.yaml` exists
- [ ] All configuration files are valid YAML
- [ ] Configuration structure is documented
## Related ADRs
- [ADR-0004: Configuration Management](../../adr/0004-configuration-management.md)
## Implementation Notes
- Use consistent indentation (2 spaces)
- Add comments for unclear configuration options
- Use environment variables for sensitive values (DSN, secrets)
- Consider adding validation schema later
## Testing
```bash
# Validate YAML syntax
yamllint config/*.yaml
# or
python3 -c "import yaml; yaml.safe_load(open('config/default.yaml'))"
```

67
docs/content/stories/phase0/0.2.4-create-configuration-files.md
View File

@@ -1,67 +0,0 @@
# Task 0.2.4: Create Configuration Files
## Metadata
- **Task ID**: 0.2.4
- **Title**: Create Configuration Files
- **Phase**: 0 - Project Setup & Foundation
- **Section**: 0.2 Configuration System
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 15 minutes
- **Dependencies**: 0.1.2
## Description
Create the baseline configuration YAML files that define the default configuration structure for the platform.
## Requirements
- Create `config/default.yaml` with baseline values
- Create `config/development.yaml` with development overrides
- Create `config/production.yaml` with production overrides
- Define configuration schema for all core services
## Implementation Steps
1. Create `config/default.yaml`:
```yaml
environment: development
server:
port: 8080
host: "0.0.0.0"
database:
driver: "postgres"
dsn: ""
logging:
level: "info"
format: "json"
```
2. Create `config/development.yaml`:
- Override logging level to "debug"
- Add development-specific settings
3. Create `config/production.yaml`:
- Override logging level to "warn"
- Add production-specific settings
4. Document configuration options
## Acceptance Criteria
- [ ] `config/default.yaml` exists with complete structure
- [ ] `config/development.yaml` exists
- [ ] `config/production.yaml` exists
- [ ] All configuration files are valid YAML
- [ ] Configuration structure is documented
## Related ADRs
- [ADR-0004: Configuration Management](../../adr/0004-configuration-management.md)
## Implementation Notes
- Use consistent indentation (2 spaces)
- Add comments for unclear configuration options
- Use environment variables for sensitive values (DSN, secrets)
- Consider adding validation schema later
## Testing
```bash
# Validate YAML syntax
yamllint config/*.yaml
# or
python3 -c "import yaml; yaml.safe_load(open('config/default.yaml'))"
```

40
docs/content/stories/phase0/0.2.5-add-internalconfigloadergo-with-loadconfig-functio.md
View File

@@ -1,40 +0,0 @@
# Task 0.2.5: Add `internal/config/loader.go` with `LoadConfig()` function
## Metadata
- **Task ID**: 0.2.5
- **Title**: Add `internal/config/loader.go` with `LoadConfig()` function
- **Phase**: 0 - Project Setup & Foundation
- **Section**: 0.2
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Add `internal/config/loader.go` with `LoadConfig()` function
## Requirements
- Add `internal/config/loader.go` with `LoadConfig()` function
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 0.2.5 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 ./...
```

136
docs/content/stories/phase0/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
- **Phase**: 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

33
docs/content/stories/phase0/0.3.1-install-gouberorgzap.md
View File

@@ -1,33 +0,0 @@
# Task 0.3.1: Install Logging Dependencies
## Metadata
- **Task ID**: 0.3.1
- **Title**: Install Logging Dependencies
- **Phase**: 0 - Project Setup & Foundation
- **Section**: 0.3 Logging Foundation
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 5 minutes
- **Dependencies**: 0.1.1
## Description
Install the Zap logging library for structured logging.
## Requirements
- Install `go.uber.org/zap` v1.26.0+
- Add to `go.mod` with proper version constraints
## Implementation Steps
1. Run `go get go.uber.org/zap@v1.26.0`
2. Run `go mod tidy`
3. Verify package in `go.mod`
## Acceptance Criteria
- [ ] Zap is listed in `go.mod`
- [ ] Version is v1.26.0 or later
- [ ] `go mod verify` passes
## Related ADRs
- [ADR-0005: Logging Framework](../../adr/0005-logging-framework.md)
- [ADR-0012: Logger Interface Design](../../adr/0012-logger-interface-design.md)

33
docs/content/stories/phase0/0.3.1-install-logging-dependencies.md
View File

@@ -1,33 +0,0 @@
# Task 0.3.1: Install Logging Dependencies
## Metadata
- **Task ID**: 0.3.1
- **Title**: Install Logging Dependencies
- **Phase**: 0 - Project Setup & Foundation
- **Section**: 0.3 Logging Foundation
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 5 minutes
- **Dependencies**: 0.1.1
## Description
Install the Zap logging library for structured logging.
## Requirements
- Install `go.uber.org/zap` v1.26.0+
- Add to `go.mod` with proper version constraints
## Implementation Steps
1. Run `go get go.uber.org/zap@v1.26.0`
2. Run `go mod tidy`
3. Verify package in `go.mod`
## Acceptance Criteria
- [ ] Zap is listed in `go.mod`
- [ ] Version is v1.26.0 or later
- [ ] `go mod verify` passes
## Related ADRs
- [ADR-0005: Logging Framework](../../adr/0005-logging-framework.md)
- [ADR-0012: Logger Interface Design](../../adr/0012-logger-interface-design.md)

52
docs/content/stories/phase0/0.3.2-create-pkgloggerloggergo-interface.md
View File

@@ -1,52 +0,0 @@
# Task 0.3.2: Create `pkg/logger/logger.go` interface:
## Metadata
- **Task ID**: 0.3.2
- **Title**: Create `pkg/logger/logger.go` interface:
- **Phase**: 0 - Project Setup & Foundation
- **Section**: 0.3
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Create `pkg/logger/logger.go` interface:
## Requirements
- Create `pkg/logger/logger.go` interface:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 0.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 ./...
```
## Code Reference
```go
type Logger interface {
Debug(msg string, fields ...Field)
Info(msg string, fields ...Field)
Warn(msg string, fields ...Field)
Error(msg string, fields ...Field)
With(fields ...Field) Logger
}
```

40
docs/content/stories/phase0/0.3.3-implement-internalloggerzap_loggergo.md
View File

@@ -1,40 +0,0 @@
# Task 0.3.3: Implement `internal/logger/zap_logger.go`:
## Metadata
- **Task ID**: 0.3.3
- **Title**: Implement `internal/logger/zap_logger.go`:
- **Phase**: 0 - Project Setup & Foundation
- **Section**: 0.3
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Implement `internal/logger/zap_logger.go`:
## Requirements
- Implement `internal/logger/zap_logger.go`:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 0.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 ./...
```

40
docs/content/stories/phase0/0.3.4-add-request-id-middleware-helper-gin-middleware.md
View File

@@ -1,40 +0,0 @@
# Task 0.3.4: Add request ID middleware helper (Gin middleware)
## Metadata
- **Task ID**: 0.3.4
- **Title**: Add request ID middleware helper (Gin middleware)
- **Phase**: 0 - Project Setup & Foundation
- **Section**: 0.3
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Add request ID middleware helper (Gin middleware)
## Requirements
- Add request ID middleware helper (Gin middleware)
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 0.3.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 ./...
```

126
docs/content/stories/phase0/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
- **Phase**: 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)

40
docs/content/stories/phase0/0.4.1-create-githubworkflowsciyml.md
View File

@@ -1,40 +0,0 @@
# Task 0.4.1: Create `.github/workflows/ci.yml`:
## Metadata
- **Task ID**: 0.4.1
- **Title**: Create `.github/workflows/ci.yml`:
- **Phase**: 0 - Project Setup & Foundation
- **Section**: 0.4
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Create `.github/workflows/ci.yml`:
## Requirements
- Create `.github/workflows/ci.yml`:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 0.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/phase0/0.4.2-add-makefile-with-common-commands.md
View File

@@ -1,40 +0,0 @@
# Task 0.4.2: Add `Makefile` with common commands:
## Metadata
- **Task ID**: 0.4.2
- **Title**: Add `Makefile` with common commands:
- **Phase**: 0 - Project Setup & Foundation
- **Section**: 0.4
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Add `Makefile` with common commands:
## Requirements
- Add `Makefile` with common commands:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 0.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 ./...
```

122
docs/content/stories/phase0/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
- **Phase**: 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 Phase 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

40
docs/content/stories/phase0/0.5.1-install-gouberorgfx.md
View File

@@ -1,40 +0,0 @@
# Task 0.5.1: Install `go.uber.org/fx`
## Metadata
- **Task ID**: 0.5.1
- **Title**: Install `go.uber.org/fx`
- **Phase**: 0 - Project Setup & Foundation
- **Section**: 0.5
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Install `go.uber.org/fx`
## Requirements
- Install `go.uber.org/fx`
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 0.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/phase0/0.5.2-create-internaldicontainergo.md
View File

@@ -1,40 +0,0 @@
# Task 0.5.2: Create `internal/di/container.go`:
## Metadata
- **Task ID**: 0.5.2
- **Title**: Create `internal/di/container.go`:
- **Phase**: 0 - Project Setup & Foundation
- **Section**: 0.5
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Create `internal/di/container.go`:
## Requirements
- Create `internal/di/container.go`:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 0.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 ./...
```

40
docs/content/stories/phase0/0.5.3-create-cmdplatformmaingo-skeleton.md
View File

@@ -1,40 +0,0 @@
# Task 0.5.3: Create `cmd/platform/main.go` skeleton:
## Metadata
- **Task ID**: 0.5.3
- **Title**: Create `cmd/platform/main.go` skeleton:
- **Phase**: 0 - Project Setup & Foundation
- **Section**: 0.5
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Create `cmd/platform/main.go` skeleton:
## Requirements
- Create `cmd/platform/main.go` skeleton:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 0.5.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 ./...
```

49
docs/content/stories/phase0/README.md
View File

@@ -1,36 +1,34 @@
# Phase 0: Project Setup & Foundation
## Overview
Initialize repository structure, set up Go modules and basic tooling, create configuration management foundation, and establish CI/CD skeleton.
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.
## Tasks
## Stories
### 0.1 Repository Bootstrap
- [0.1.1 - Initialize Go Module](./0.1.1-initialize-go-module.md)
- [0.1.2 - Create Directory Structure](./0.1.2-create-directory-structure.md)
- [0.1.3 - Add Gitignore](./0.1.3-add-gitignore.md)
- [0.1.4 - Create Initial README](./0.1.4-create-initial-readme.md)
### 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 System
- [0.2.1 - Install Configuration Dependencies](./0.2.1-install-config-dependencies.md)
- [0.2.2 - Create Config Interface](./0.2.2-create-config-interface.md)
- [0.2.3 - Implement Config Loader](./0.2.3-implement-config-loader.md)
- [0.2.4 - Create Configuration Files](./0.2.4-create-configuration-files.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 Logging Foundation
- [0.3.1 - Install Logging Dependencies](./0.3.1-install-logging-dependencies.md)
- [0.3.2 - Create Logger Interface](./0.3.2-create-logger-interface.md) - Create `pkg/logger/logger.go` interface
- [0.3.3 - Implement Zap Logger](./0.3.3-implement-zap-logger.md) - Implement `internal/logger/zap_logger.go`
- [0.3.4 - Add Request ID Middleware](./0.3.4-add-request-id-middleware.md) - Create Gin middleware for request IDs
### 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 Basic CI/CD Pipeline
- [0.4.1 - Create GitHub Actions Workflow](./0.4.1-create-github-actions-workflow.md)
- [0.4.2 - Create Makefile](./0.4.2-create-makefile.md)
### 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 Setup
- [0.5.1 - Install FX Dependency](./0.5.1-install-fx-dependency.md)
- [0.5.2 - Create DI Container](./0.5.2-create-di-container.md)
- [0.5.3 - Create Main Entry Point](./0.5.3-create-main-entry-point.md)
### 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
@@ -44,4 +42,5 @@ Initialize repository structure, set up Go modules and basic tooling, create con
- `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