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

87
docs/content/adr/0029-microservices-architecture.md Normal file
View File

@@ -0,0 +1,87 @@
# ADR-0029: Microservices Architecture
## Status
Accepted
## Context
The platform needs to scale independently, support team autonomy, and enable flexible deployment. A microservices architecture provides these benefits from day one, and the complexity of supporting both monolith and microservices modes is unnecessary.
## Decision
Design the platform as **microservices architecture from day one**:
1. **Service-Based Architecture**: All modules are independent services:
- Each module is a separate service with its own process
- Services communicate via gRPC (primary) or HTTP (fallback)
- Service client interfaces for all inter-service communication
- No direct in-process calls between services
2. **Service Registry**: Central registry for service discovery:
- All services register on startup
- Service discovery via registry
- Health checking and automatic deregistration
- Support for Consul, etcd, or Kubernetes service discovery
3. **Communication Patterns**:
- **Synchronous**: gRPC service calls (primary), HTTP/REST (fallback)
- **Asynchronous**: Event bus via Kafka
- **Shared State**: Cache (Redis) and Database (PostgreSQL)
4. **Service Boundaries**: Each module is an independent service:
- Independent Go modules (`go.mod`)
- Own database schema (via Ent)
- Own API routes
- Own process and deployment
- Can be scaled independently
5. **Development Simplification**: For local development, multiple services can run in the same process, but they still communicate via service clients (no direct calls)
## Consequences
### Positive
- **Simplified Architecture**: Single architecture pattern, no dual-mode complexity
- **Independent Scaling**: Scale individual services based on load
- **Team Autonomy**: Teams can own and deploy their services independently
- **Technology Diversity**: Different services can use different tech stacks (future)
- **Fault Isolation**: Failure in one service doesn't bring down entire platform
- **Deployment Flexibility**: Deploy services independently
- **Clear Boundaries**: Service boundaries are explicit from the start
### Negative
- **Network Latency**: Inter-service calls have network overhead
- **Distributed System Challenges**: Need to handle network failures, retries, timeouts
- **Service Discovery Overhead**: Additional infrastructure needed
- **Debugging Complexity**: Distributed tracing becomes essential
- **Data Consistency**: Cross-service transactions become challenging
- **Development Setup**: More complex local development (multiple services)
### Mitigations
- **Service Mesh**: Use service mesh (Istio, Linkerd) for advanced microservices features
- **API Gateway**: Central gateway for routing and cross-cutting concerns
- **Event Sourcing**: Use events for eventual consistency
- **Circuit Breakers**: Implement circuit breakers for resilience
- **Comprehensive Observability**: OpenTelemetry, metrics, logging essential
- **Docker Compose**: Simplify local development with docker-compose
- **Development Mode**: Run multiple services in same process for local dev (still use service clients)
## Implementation Strategy
### Phase 1: Service Client Interfaces (Phase 1)
- Define service client interfaces for all core services
- All inter-service communication goes through interfaces
### Phase 2: Service Registry (Phase 3)
- Create service registry interface
- Implement service discovery
- Support for Consul, Kubernetes service discovery
### Phase 3: gRPC Services (Phase 5)
- Implement gRPC service definitions
- Create gRPC servers for all services
- Create gRPC clients for service communication
- HTTP clients as fallback option
## References
- [Service Abstraction Pattern](https://microservices.io/patterns/data/service-per-database.html)
- [Service Discovery Patterns](https://microservices.io/patterns/service-registry.html)
- [gRPC Documentation](https://grpc.io/docs/)

73
docs/content/adr/0030-service-communication-strategy.md Normal file
View File

@@ -0,0 +1,73 @@
# ADR-0030: Service Communication Strategy
## Status
Accepted
## Context
Services need to communicate with each other in a microservices architecture. All communication must go through well-defined interfaces that support network calls.
## Decision
Use a **service client-based communication strategy**:
1. **Service Client Interfaces** (Primary for synchronous calls):
- Define interfaces in `pkg/services/` for all services
- All implementations are network-based:
- `internal/services/grpc/client/` - gRPC clients (primary)
- `internal/services/http/client/` - HTTP clients (fallback)
2. **Event Bus** (Primary for asynchronous communication):
- Distributed via Kafka
- Preferred for cross-service communication
- Event-driven architecture for loose coupling
3. **Shared Infrastructure** (For state):
- Redis for cache and distributed state
- PostgreSQL for persistent data
- Kafka for events
## Service Client Pattern
```go
// Interface in pkg/services/
type IdentityServiceClient interface {
GetUser(ctx context.Context, id string) (*User, error)
CreateUser(ctx context.Context, user *User) (*User, error)
}
// gRPC implementation (primary)
type grpcIdentityClient struct {
conn *grpc.ClientConn
client pb.IdentityServiceClient
}
// HTTP implementation (fallback)
type httpIdentityClient struct {
baseURL string
httpClient *http.Client
}
```
## Development Mode
For local development, multiple services can run in the same process, but they still communicate via service clients (gRPC or HTTP) - no direct in-process calls. This ensures the architecture is consistent.
## Consequences
### Positive
- **Unified Interface**: Consistent interface across all services
- **Easy Testing**: Can mock service clients
- **Type Safety**: gRPC provides type-safe contracts
- **Clear Boundaries**: Service boundaries are explicit
- **Scalability**: Services can be scaled independently
### Negative
- **Network Overhead**: All calls go over network
- **Interface Evolution**: Changes require coordination
- **Versioning**: Need service versioning strategy
- **Development Complexity**: More setup required for local development
## Implementation
- All services use gRPC clients (primary)
- HTTP clients as fallback option
- Service registry for service discovery
- Circuit breakers and retries for resilience

5
docs/content/adr/README.md
View File

@@ -69,6 +69,11 @@ Each ADR follows this structure:
- [ADR-0028: Testing Strategy](./0028-testing-strategy.md) - Multi-layered (unit, integration, contract, load) - [ADR-0028: Testing Strategy](./0028-testing-strategy.md) - Multi-layered (unit, integration, contract, load)
### Architecture & Scaling
- [ADR-0029: Microservices Architecture](./0029-microservices-architecture.md) - Microservices architecture from day one
- [ADR-0030: Service Communication Strategy](./0030-service-communication-strategy.md) - Service client abstraction and communication patterns
## Adding New ADRs ## Adding New ADRs
When making a new architectural decision: When making a new architectural decision:

88
docs/content/architecture-modules.md
View File

@@ -264,45 +264,54 @@ graph LR
## Module Communication ## Module Communication
Modules communicate through well-defined interfaces provided by the core platform. Modules (services) communicate through service client interfaces. All inter-service communication uses gRPC (primary) or HTTP (fallback).
### Communication Patterns ### Communication Patterns
```mermaid ```mermaid
graph TB graph TB
subgraph "Communication Patterns" subgraph "Communication Patterns"
Direct[Direct Service Calls<br/>via DI] ServiceClients[Service Clients<br/>gRPC/HTTP]
Events[Event Bus<br/>Publish/Subscribe] Events[Event Bus<br/>Kafka]
Shared[Shared Interfaces<br/>Core Services] Shared[Shared Infrastructure<br/>Redis, PostgreSQL]
end end
subgraph "Module A" subgraph "Blog Service"
AService[Service A] BlogService[Blog Service]
AHandler[Handler A] BlogHandler[Blog Handler]
end
subgraph "Service Clients"
AuthClient[Auth Service Client]
IdentityClient[Identity Service Client]
AuthzClient[Authz Service Client]
end end
subgraph "Core Services" subgraph "Core Services"
EventBus[Event Bus] EventBus[Event Bus]
AuthService[Auth Service] AuthService[Auth Service<br/>:8081]
CacheService[Cache Service] IdentityService[Identity Service<br/>:8082]
end end
subgraph "Module B" subgraph "Analytics Service"
BService[Service B] AnalyticsService[Analytics Service]
BHandler[Handler B]
end end
AHandler --> AService BlogHandler --> BlogService
AService --> AuthService BlogService -->|gRPC| AuthClient
AService --> CacheService BlogService -->|gRPC| IdentityClient
AService -->|Publish| EventBus BlogService -->|gRPC| AuthzClient
EventBus -->|Subscribe| BService BlogService -->|Publish| EventBus
BService --> AuthService EventBus -->|Subscribe| AnalyticsService
BHandler --> BService
AuthClient --> AuthService
IdentityClient --> IdentityService
AuthzClient --> IdentityService
style EventBus fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff style EventBus fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
style AService fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff style BlogService fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
style BService fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff style AnalyticsService fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
style ServiceClients fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
``` ```
### Event-Driven Communication ### Event-Driven Communication
@@ -412,25 +421,30 @@ graph TB
PostEntity[Post Entity] PostEntity[Post Entity]
end end
subgraph "Core Services Used" subgraph "Service Clients"
AuthService[Auth Service] AuthClient[Auth Service Client<br/>gRPC]
AuthzService[Authorization Service] AuthzClient[Authz Service Client<br/>gRPC]
EventBus[Event Bus] IdentityClient[Identity Service Client<br/>gRPC]
AuditService[Audit Service] AuditClient[Audit Service Client<br/>gRPC]
CacheService[Cache Service] end
subgraph "Core Services"
EventBus[Event Bus<br/>Kafka]
CacheService[Cache Service<br/>Redis]
end end
subgraph "Database" subgraph "Database"
PostsTable[(blog_posts)] PostsTable[(blog_posts)]
end end
BlogHandler --> AuthService
BlogHandler --> AuthzService
BlogHandler --> BlogService BlogHandler --> BlogService
BlogService -->|gRPC| AuthClient
BlogService -->|gRPC| AuthzClient
BlogService -->|gRPC| IdentityClient
BlogService -->|gRPC| AuditClient
BlogService --> PostRepo BlogService --> PostRepo
BlogService --> EventBus BlogService --> EventBus
BlogService --> AuditService
BlogService --> CacheService BlogService --> CacheService
PostRepo --> PostsTable PostRepo --> PostsTable
@@ -454,9 +468,15 @@ graph LR
DB[(Database)] DB[(Database)]
end end
subgraph "Service Clients"
AuthClient[Auth Service Client]
IdentityClient[Identity Service Client]
AuthzClient[Authz Service Client]
end
subgraph "Side Effects" subgraph "Side Effects"
EventBus[Event Bus] EventBus[Event Bus]
Audit[Audit Log] AuditClient[Audit Service Client]
Cache[Cache] Cache[Cache]
end end
@@ -467,12 +487,16 @@ graph LR
Service --> Repo Service --> Repo
Repo --> DB Repo --> DB
Service -->|gRPC| AuthClient
Service -->|gRPC| IdentityClient
Service -->|gRPC| AuthzClient
Service -->|gRPC| AuditClient
Service --> EventBus Service --> EventBus
Service --> Audit
Service --> Cache Service --> Cache
style Request fill:#4a90e2,stroke:#2e5c8a,stroke-width:2px,color:#fff style Request fill:#4a90e2,stroke:#2e5c8a,stroke-width:2px,color:#fff
style Service fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff style Service fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
style ServiceClients fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
``` ```
## Module Registration Flow ## Module Registration Flow

165
docs/content/architecture.md
View File

@@ -13,7 +13,12 @@ This document provides a comprehensive overview of the Go Platform architecture,
## High-Level Architecture ## High-Level Architecture
The Go Platform follows a **modular monolith** architecture that can evolve into microservices. The platform consists of a core kernel and pluggable feature modules. The Go Platform follows a **microservices architecture** where each module is an independent service:
- **Core Services**: Authentication, Identity, Authorization, Audit, etc.
- **Feature Services**: Blog, Billing, Analytics, etc. (modules)
- **Infrastructure Services**: Cache, Event Bus, Scheduler, etc.
All services communicate via gRPC (primary) or HTTP (fallback), with service discovery via a service registry. Services share infrastructure (PostgreSQL, Redis, Kafka) but are independently deployable and scalable.
```mermaid ```mermaid
graph TB graph TB
@@ -581,10 +586,168 @@ graph TB
style Module fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff style Module fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
``` ```
## Microservices Architecture
The platform is designed as **microservices from day one**, with each module being an independent service.
### Service Architecture
```mermaid
graph TB
subgraph "API Gateway"
Gateway[API Gateway<br/>Routing & Auth]
end
subgraph "Core Services"
AuthSvc[Auth Service<br/>:8081]
IdentitySvc[Identity Service<br/>:8082]
AuthzSvc[Authz Service<br/>:8083]
AuditSvc[Audit Service<br/>:8084]
end
subgraph "Feature Services"
BlogSvc[Blog Service<br/>:8091]
BillingSvc[Billing Service<br/>:8092]
AnalyticsSvc[Analytics Service<br/>:8093]
end
subgraph "Infrastructure"
DB[(PostgreSQL)]
Cache[(Redis)]
Queue[Kafka]
Registry[Service Registry]
end
Gateway --> AuthSvc
Gateway --> IdentitySvc
Gateway --> BlogSvc
Gateway --> BillingSvc
AuthSvc --> IdentitySvc
AuthSvc --> Registry
BlogSvc --> AuthzSvc
BlogSvc --> IdentitySvc
BlogSvc --> Registry
BillingSvc --> IdentitySvc
BillingSvc --> Registry
AuthSvc --> DB
IdentitySvc --> DB
BlogSvc --> DB
BillingSvc --> DB
AuthSvc --> Cache
BlogSvc --> Cache
BillingSvc --> Cache
BlogSvc --> Queue
BillingSvc --> Queue
AnalyticsSvc --> Queue
style Gateway fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
style Registry fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
```
### Service Communication
All inter-service communication uses service client interfaces:
```mermaid
graph TB
subgraph "Service Client Interface"
Interface[Service Interface<br/>pkg/services/]
end
subgraph "Implementations"
GRPC[gRPC Client<br/>Primary]
HTTP[HTTP Client<br/>Fallback]
end
subgraph "Service Registry"
Registry[Service Registry<br/>Discovery & Resolution]
end
Interface --> GRPC
Interface --> HTTP
Registry --> GRPC
Registry --> HTTP
style Interface fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
style Registry fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
```
### Service Communication Patterns
The platform uses three communication patterns:
1. **Synchronous Service Calls** (via Service Clients):
- gRPC calls (primary) - type-safe, efficient
- HTTP/REST calls (fallback) - for external integration
- All calls go through service client interfaces
- Service discovery via registry
2. **Asynchronous Events** (via Event Bus):
- Distributed via Kafka
- Preferred for cross-service communication
- Event-driven architecture for loose coupling
3. **Shared Infrastructure** (For state):
- Redis for cache and distributed state
- PostgreSQL for persistent data
- Kafka for events
### Service Registry
The service registry enables service discovery and resolution:
```mermaid
graph TB
subgraph "Service Registry"
Registry[Service Registry Interface]
Consul[Consul Registry]
K8s[K8s Service Discovery]
Etcd[etcd Registry]
end
subgraph "Services"
AuthSvc[Auth Service]
IdentitySvc[Identity Service]
BlogSvc[Blog Service]
end
Registry --> Consul
Registry --> K8s
Registry --> Etcd
Consul --> AuthSvc
K8s --> IdentitySvc
Etcd --> BlogSvc
style Registry fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
```
### Scaling Strategy
#### Independent Service Scaling
- Scale individual services based on load
- Independent resource allocation
- Independent deployment
- Better resource utilization
- Team autonomy
#### Development Mode
- For local development, multiple services can run in the same process
- Services still communicate via gRPC/HTTP (no direct calls)
- Docker Compose for easy local setup
- Maintains microservices architecture even in development
## Next Steps ## Next Steps
- [Module Architecture](./architecture-modules.md) - Detailed module architecture and design - [Module Architecture](./architecture-modules.md) - Detailed module architecture and design
- [Module Requirements](./module-requirements.md) - Requirements for each module - [Module Requirements](./module-requirements.md) - Requirements for each module
- [Component Relationships](./component-relationships.md) - Detailed component interactions - [Component Relationships](./component-relationships.md) - Detailed component interactions
- [ADRs](../adr/README.md) - Architecture Decision Records - [ADRs](../adr/README.md) - Architecture Decision Records
- [ADR-0029: Microservices Architecture](../adr/0029-microservices-architecture.md) - Microservices strategy
- [ADR-0030: Service Communication](../adr/0030-service-communication-strategy.md) - Communication patterns

86
docs/content/component-relationships.md
View File

@@ -75,23 +75,30 @@ graph TD
## Module to Core Integration ## Module to Core Integration
Modules integrate with core services through well-defined interfaces and dependency injection. Modules (services) integrate with core services through service client interfaces. All communication uses gRPC or HTTP.
```mermaid ```mermaid
graph LR graph LR
subgraph "Feature Module" subgraph "Feature Service (e.g., Blog)"
ModuleHandler[Module Handler] ModuleHandler[Module Handler]
ModuleService[Module Service] ModuleService[Module Service]
ModuleRepo[Module Repository] ModuleRepo[Module Repository]
end end
subgraph "Service Clients"
AuthClient[Auth Service Client]
AuthzClient[Authz Service Client]
IdentityClient[Identity Service Client]
AuditClient[Audit Service Client]
end
subgraph "Core Services" subgraph "Core Services"
AuthService[Auth Service] AuthService[Auth Service<br/>:8081]
AuthzService[Authz Service] AuthzService[Authz Service<br/>:8083]
EventBusService[Event Bus] IdentityService[Identity Service<br/>:8082]
CacheService[Cache Service] AuditService[Audit Service<br/>:8084]
AuditService[Audit Service] EventBusService[Event Bus<br/>Kafka]
LoggerService[Logger Service] CacheService[Cache Service<br/>Redis]
end end
subgraph "Infrastructure" subgraph "Infrastructure"
@@ -100,15 +107,20 @@ graph LR
QueueClient[Message Queue] QueueClient[Message Queue]
end end
ModuleHandler --> AuthService
ModuleHandler --> AuthzService
ModuleHandler --> ModuleService ModuleHandler --> ModuleService
ModuleService -->|gRPC| AuthClient
ModuleService -->|gRPC| AuthzClient
ModuleService -->|gRPC| IdentityClient
ModuleService -->|gRPC| AuditClient
ModuleService --> ModuleRepo ModuleService --> ModuleRepo
ModuleService --> EventBusService ModuleService --> EventBusService
ModuleService --> CacheService ModuleService --> CacheService
ModuleService --> AuditService
ModuleService --> LoggerService AuthClient --> AuthService
AuthzClient --> AuthzService
IdentityClient --> IdentityService
AuditClient --> AuditService
ModuleRepo --> DBClient ModuleRepo --> DBClient
CacheService --> CacheClient CacheService --> CacheClient
@@ -117,6 +129,7 @@ graph LR
style ModuleService fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff style ModuleService fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
style AuthService fill:#4a90e2,stroke:#2e5c8a,stroke-width:2px,color:#fff style AuthService fill:#4a90e2,stroke:#2e5c8a,stroke-width:2px,color:#fff
style DBClient fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff style DBClient fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
style ServiceClients fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
``` ```
## Service Interaction Patterns ## Service Interaction Patterns
@@ -334,12 +347,14 @@ graph TB
Audit --> Logger Audit --> Logger
ModuleLoader --> DI ModuleLoader --> DI
ModuleHandler --> Auth ModuleHandler --> ModuleService
ModuleHandler --> Authz
ModuleService --> ModuleRepo ModuleService --> ModuleRepo
ModuleService -->|gRPC| Auth
ModuleService -->|gRPC| Authz
ModuleService -->|gRPC| Identity
ModuleService -->|gRPC| Audit
ModuleService --> EventBus ModuleService --> EventBus
ModuleService --> Cache ModuleService --> Cache
ModuleService --> Audit
ModuleRepo --> DB ModuleRepo --> DB
Scheduler --> Cache Scheduler --> Cache
@@ -418,33 +433,44 @@ graph TB
style DB fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff style DB fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
``` ```
### Cross-Module Communication ### Cross-Service Communication
```mermaid ```mermaid
graph LR graph LR
subgraph "Module A" subgraph "Blog Service"
AService[Service A] BlogService[Blog Service]
end end
subgraph "Module B" subgraph "Analytics Service"
BService[Service B] AnalyticsService[Analytics Service]
end
subgraph "Service Clients"
AuthzClient[Authz Service Client]
IdentityClient[Identity Service Client]
end end
subgraph "Core Services" subgraph "Core Services"
EventBus[Event Bus] EventBus[Event Bus<br/>Kafka]
Authz[Authz Service] AuthzService[Authz Service<br/>:8083]
Cache[Cache] IdentityService[Identity Service<br/>:8082]
Cache[Cache<br/>Redis]
end end
AService -->|Direct Call| Authz BlogService -->|gRPC| AuthzClient
AService -->|Publish Event| EventBus BlogService -->|gRPC| IdentityClient
EventBus -->|Subscribe| BService BlogService -->|Publish Event| EventBus
AService -->|Cache Access| Cache EventBus -->|Subscribe| AnalyticsService
BService -->|Cache Access| Cache BlogService -->|Cache Access| Cache
AnalyticsService -->|Cache Access| Cache
style AService fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff AuthzClient --> AuthzService
style BService fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff IdentityClient --> IdentityService
style BlogService fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
style AnalyticsService fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
style EventBus fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff style EventBus fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
style ServiceClients fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
``` ```
## Next Steps ## Next Steps

2
docs/content/index.md
View File

@@ -58,7 +58,7 @@ Detailed task definitions for each phase are available in the [Stories section](
## Key Principles ## Key Principles
- **Clean/Hexagonal Architecture**: Clear separation between core and plugins - **Clean/Hexagonal Architecture**: Clear separation between core and plugins
- **Modular Monolith**: Start simple, evolve to microservices if needed - **Microservices Architecture**: Each module is an independent service from day one
- **Plugin-First Design**: Extensible architecture supporting static and dynamic modules - **Plugin-First Design**: Extensible architecture supporting static and dynamic modules
- **Security-by-Design**: Built-in authentication, authorization, and audit capabilities - **Security-by-Design**: Built-in authentication, authorization, and audit capabilities
- **Observability**: Comprehensive logging, metrics, and tracing - **Observability**: Comprehensive logging, metrics, and tracing

1099
docs/content/plan.md
View File

File diff suppressed because it is too large Load Diff

179
docs/content/stories/STORY_CONSOLIDATION_GUIDE.md Normal file
View File

@@ -0,0 +1,179 @@
# Story Consolidation Guide
## Overview
The stories have been reworked from granular, task-based items into meaningful, cohesive stories that solve complete problems. Each story now represents a complete feature or capability that can be tested end-to-end.
## Transformation Pattern
### Before (Granular Tasks)
- ❌ "Install dependency X"
- ❌ "Create file Y"
- ❌ "Add function Z"
- ❌ Multiple tiny tasks that don't deliver value alone
### After (Meaningful Stories)
- ✅ "Configuration Management System" - Complete config system with interface, implementation, and files
- ✅ "JWT Authentication System" - Complete auth with tokens, middleware, and endpoints
- ✅ "Database Layer with Ent ORM" - Complete database setup with entities, migrations, and client
## Story Structure
Each consolidated story follows this structure:
1. **Goal** - High-level objective
2. **Description** - What problem it solves
3. **Deliverables** - Complete list of what will be delivered
4. **Acceptance Criteria** - How we know it's done
5. **Implementation Steps** - High-level steps (not micro-tasks)
## Phase 0 - Completed Examples
### 0.1 Project Initialization and Repository Structure
**Consolidates:** Go module init, directory structure, .gitignore, README
### 0.2 Configuration Management System
**Consolidates:** Install viper, create interface, implement loader, create config files
### 0.3 Structured Logging System
**Consolidates:** Install zap, create interface, implement logger, request ID middleware
### 0.4 CI/CD Pipeline
**Consolidates:** GitHub Actions workflow, Makefile creation
### 0.5 DI and Application Bootstrap
**Consolidates:** Install FX, create DI container, create main.go
## Remaining Phases - Consolidation Pattern
### Phase 1: Core Kernel
- **1.1 Enhanced DI Container** - All DI providers and extensions
- **1.2 Database Layer** - Complete Ent setup with entities and migrations
- **1.3 Health & Metrics** - Complete monitoring system
- **1.4 Error Handling** - Complete error bus system
- **1.5 HTTP Server** - Complete server with all middleware
- **1.6 OpenTelemetry** - Complete tracing setup
### Phase 2: Authentication & Authorization
- **2.1 JWT Authentication System** - Complete auth with tokens
- **2.2 Identity Management** - Complete user lifecycle
- **2.3 RBAC System** - Complete permission system
- **2.4 Role Management API** - Complete role management
- **2.5 Audit Logging** - Complete audit system
- **2.6 Database Seeding** - Complete seeding system
### Phase 3: Module Framework
- **3.1 Module Interface & Registry** - Complete module system
- **3.2 Permission Code Generation** - Complete code gen system
- **3.3 Module Loader** - Complete loading and initialization
- **3.4 Module CLI** - Complete CLI tool
### Phase 4: Sample Blog Module
- **4.1 Complete Blog Module** - Full module with CRUD, permissions, API
### Phase 5: Infrastructure Adapters
- **5.1 Cache System** - Complete Redis cache
- **5.2 Event Bus** - Complete event system
- **5.3 Blob Storage** - Complete S3 storage
- **5.4 Email Notification** - Complete email system
- **5.5 Scheduler & Jobs** - Complete job system
- **5.6 Secret Store** - Complete secret management
- **5.7 Multi-tenancy** - Complete tenant support
### Phase 6: Observability
- **6.1 Enhanced OpenTelemetry** - Complete tracing
- **6.2 Error Reporting** - Complete Sentry integration
- **6.3 Enhanced Logging** - Complete log correlation
- **6.4 Metrics Expansion** - Complete metrics
- **6.5 Grafana Dashboards** - Complete dashboards
- **6.6 Rate Limiting** - Complete rate limiting
- **6.7 Security Hardening** - Complete security
- **6.8 Performance Optimization** - Complete optimizations
### Phase 7: Testing & Documentation
- **7.1 Unit Testing** - Complete test suite
- **7.2 Integration Testing** - Complete integration tests
- **7.3 Documentation** - Complete docs
- **7.4 CI/CD Enhancement** - Complete pipeline
- **7.5 Docker & Deployment** - Complete deployment setup
### Phase 8: Advanced Features
- **8.1 OIDC Support** - Complete OIDC
- **8.2 GraphQL API** - Complete GraphQL
- **8.3 Additional Modules** - Complete sample modules
- **8.4 Performance** - Complete optimizations
## Creating New Story Files
When creating story files for remaining phases, follow this template:
```markdown
# Story X.Y: [Meaningful Title]
## Metadata
- **Story ID**: X.Y
- **Title**: [Complete Feature Name]
- **Phase**: X - [Phase Name]
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: [hours]
- **Dependencies**: [story IDs]
## Goal
[High-level objective - what problem does this solve?]
## Description
[What this story delivers as a complete capability]
## Deliverables
- [Complete list of deliverables - not just files, but complete features]
- [Interface definitions]
- [Implementations]
- [API endpoints]
- [Integration points]
## Implementation Steps
1. [High-level step 1]
2. [High-level step 2]
3. [High-level step 3]
## Acceptance Criteria
- [ ] [End-to-end testable criteria]
- [ ] [Feature works completely]
- [ ] [Integration works]
## Related ADRs
- [ADR links]
## Implementation Notes
- [Important considerations]
## Testing
[How to test the complete feature]
## Files to Create/Modify
- [List of files]
```
## Key Principles
1. **Each story solves a complete problem** - Not just "install X" or "create file Y"
2. **Stories are testable end-to-end** - You can verify the complete feature works
3. **Stories deliver business value** - Even infrastructure stories solve complete problems
4. **Stories are independent where possible** - Can be worked on separately
5. **Stories have clear acceptance criteria** - You know when they're done
## Next Steps
1. Update remaining phase README files to reference consolidated stories
2. Create story files for remaining phases following the pattern
3. Update plan.md to complete all phases with story-based structure
4. Remove old granular task files (or archive them)
## Benefits of This Approach
- **Better Planning**: Stories represent complete features
- **Clearer Progress**: You can see complete features being delivered
- **Better Testing**: Each story can be tested end-to-end
- **Reduced Overhead**: Fewer story files to manage
- **More Meaningful**: Stories solve real problems, not just tasks

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 # Phase 0: Project Setup & Foundation
## Overview ## 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 Project Initialization and Repository Structure
- [0.1.1 - Initialize Go Module](./0.1.1-initialize-go-module.md) - [Story: 0.1 - Project Initialization](./0.1-project-initialization.md)
- [0.1.2 - Create Directory Structure](./0.1.2-create-directory-structure.md) - **Goal:** Establish a properly structured Go project with all necessary directories, configuration files, and documentation.
- [0.1.3 - Add Gitignore](./0.1.3-add-gitignore.md) - **Deliverables:** Go module initialization, complete directory structure, .gitignore, comprehensive README.md
- [0.1.4 - Create Initial README](./0.1.4-create-initial-readme.md)
### 0.2 Configuration System ### 0.2 Configuration Management System
- [0.2.1 - Install Configuration Dependencies](./0.2.1-install-config-dependencies.md) - [Story: 0.2 - Configuration Management System](./0.2-configuration-management-system.md)
- [0.2.2 - Create Config Interface](./0.2.2-create-config-interface.md) - **Goal:** Implement a flexible configuration system that loads settings from YAML files, environment variables, and supports type-safe access.
- [0.2.3 - Implement Config Loader](./0.2.3-implement-config-loader.md) - **Deliverables:** ConfigProvider interface, Viper implementation, configuration files, DI integration
- [0.2.4 - Create Configuration Files](./0.2.4-create-configuration-files.md)
### 0.3 Logging Foundation ### 0.3 Structured Logging System
- [0.3.1 - Install Logging Dependencies](./0.3.1-install-logging-dependencies.md) - [Story: 0.3 - Structured Logging System](./0.3-structured-logging-system.md)
- [0.3.2 - Create Logger Interface](./0.3.2-create-logger-interface.md) - Create `pkg/logger/logger.go` interface - **Goal:** Implement a production-ready logging system with structured JSON output, request correlation, and configurable log levels.
- [0.3.3 - Implement Zap Logger](./0.3.3-implement-zap-logger.md) - Implement `internal/logger/zap_logger.go` - **Deliverables:** Logger interface, Zap implementation, request ID middleware, context-aware logging
- [0.3.4 - Add Request ID Middleware](./0.3.4-add-request-id-middleware.md) - Create Gin middleware for request IDs
### 0.4 Basic CI/CD Pipeline ### 0.4 CI/CD Pipeline and Development Tooling
- [0.4.1 - Create GitHub Actions Workflow](./0.4.1-create-github-actions-workflow.md) - [Story: 0.4 - CI/CD Pipeline and Development Tooling](./0.4-cicd-pipeline.md)
- [0.4.2 - Create Makefile](./0.4.2-create-makefile.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 Dependency Injection and Application Bootstrap
- [0.5.1 - Install FX Dependency](./0.5.1-install-fx-dependency.md) - [Story: 0.5 - Dependency Injection and Application Bootstrap](./0.5-di-and-bootstrap.md)
- [0.5.2 - Create DI Container](./0.5.2-create-di-container.md) - **Goal:** Set up dependency injection container using Uber FX and create the application entry point that initializes the platform.
- [0.5.3 - Create Main Entry Point](./0.5.3-create-main-entry-point.md) - **Deliverables:** DI container, FX providers, application entry point, lifecycle management
## Deliverables Checklist ## Deliverables Checklist
- [ ] Repository structure in place - [ ] 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) - `go test ./...` runs (even if tests are empty)
- CI pipeline passes on empty commit - CI pipeline passes on empty commit
- Config loads from `config/default.yaml` - Config loads from `config/default.yaml`
- Logger can be injected and used
- Application starts and shuts down gracefully

95
docs/content/stories/phase1/1.1-enhanced-di-container.md Normal file
View File

@@ -0,0 +1,95 @@
# Story 1.1: Enhanced Dependency Injection Container
## Metadata
- **Story ID**: 1.1
- **Title**: Enhanced Dependency Injection Container
- **Phase**: 1 - Core Kernel & Infrastructure
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 3-4 hours
- **Dependencies**: 0.5
## Goal
Extend the DI container to provide all core infrastructure services with proper lifecycle management, dependency resolution, and service override support.
## Description
This story extends the basic DI container to support all core services including database, health checks, metrics, and error bus. The container must handle service initialization order, lifecycle management, and provide a clean way to override services for testing.
## Deliverables
### 1. Extended DI Container (`internal/di/container.go`)
- Registration of all core services
- Lifecycle management via FX
- Service override support for testing
- Dependency resolution
- Error handling during initialization
### 2. Provider Functions (`internal/di/providers.go`)
Complete provider functions for all core services:
- `ProvideConfig() fx.Option` - Configuration provider
- `ProvideLogger() fx.Option` - Logger provider
- `ProvideDatabase() fx.Option` - Ent database client provider
- `ProvideHealthCheckers() fx.Option` - Health check registry provider
- `ProvideMetrics() fx.Option` - Prometheus metrics registry provider
- `ProvideErrorBus() fx.Option` - Error bus provider
### 3. Core Module (`internal/di/core_module.go`)
- Export `CoreModule() fx.Option` that provides all core services
- Easy composition with future modules
- Single import point for core services
## Implementation Steps
1. **Extend Container**
- Update `internal/di/container.go`
- Add support for all core services
- Implement lifecycle hooks
2. **Create Provider Functions**
- Create `internal/di/providers.go`
- Implement all provider functions
- Handle dependencies correctly
3. **Create Core Module**
- Create `internal/di/core_module.go`
- Export CoreModule function
- Document usage
4. **Test Integration**
- Verify all services are provided
- Test service overrides
- Test lifecycle hooks
## Acceptance Criteria
- [ ] All core services are provided via DI container
- [ ] Services are initialized in correct dependency order
- [ ] Lifecycle hooks work for all services
- [ ] Services can be overridden for testing
- [ ] DI container compiles without errors
- [ ] CoreModule can be imported and used
- [ ] Error handling works during initialization
## Related ADRs
- [ADR-0003: Dependency Injection Framework](../../adr/0003-dependency-injection-framework.md)
## Implementation Notes
- Use FX's dependency injection features
- Ensure proper initialization order
- Support service overrides via FX options
- Handle errors gracefully during startup
- Document provider functions
## Testing
```bash
# Test DI container
go test ./internal/di/...
# Test service injection
go run cmd/platform/main.go
```
## Files to Create/Modify
- `internal/di/container.go` - Extended container
- `internal/di/providers.go` - Provider functions
- `internal/di/core_module.go` - Core module export

40
docs/content/stories/phase1/1.1.1-extend-internaldicontainergo.md
View File

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

40
docs/content/stories/phase1/1.1.2-create-internaldiprovidersgo.md
View File

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

40
docs/content/stories/phase1/1.1.3-add-internaldicore_modulego.md
View File

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

144
docs/content/stories/phase1/1.2-database-layer.md Normal file
View File

@@ -0,0 +1,144 @@
# Story 1.2: Database Layer with Ent ORM
## Metadata
- **Story ID**: 1.2
- **Title**: Database Layer with Ent ORM
- **Phase**: 1 - Core Kernel & Infrastructure
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 6-8 hours
- **Dependencies**: 1.1
## Goal
Set up a complete database layer using Ent ORM with core domain entities, migrations, and connection management.
## Description
This story implements the complete database layer using Ent ORM. It includes defining core domain entities (User, Role, Permission, AuditLog), setting up migrations, configuring connection pooling, and creating a database client that integrates with the DI container.
## Deliverables
### 1. Ent Schema Initialization
- Initialize Ent schema in `internal/ent/`
- Set up code generation
### 2. Core Domain Entities (`internal/ent/schema/`)
Define core entities:
- **User** (`user.go`): ID, email, password_hash, verified, created_at, updated_at
- **Role** (`role.go`): ID, name, description, created_at
- **Permission** (`permission.go`): ID, name (format: "module.resource.action")
- **AuditLog** (`audit_log.go`): ID, actor_id, action, target_id, metadata (JSON), timestamp
- **Relationships**:
- `role_permissions.go` - Many-to-many between Role and Permission
- `user_roles.go` - Many-to-many between User and Role
### 3. Generated Ent Code
- Run `go generate ./internal/ent`
- Verify generated code compiles
- Type-safe database operations
### 4. Database Client (`internal/infra/database/client.go`)
- `NewEntClient(dsn string) (*ent.Client, error)` function
- Connection pooling configuration:
- Max connections
- Max idle connections
- Connection lifetime
- Idle timeout
- Migration runner wrapper
- Database health check integration
- Graceful connection closing
### 5. Database Configuration
- Add database config to `config/default.yaml`:
- Connection string (DSN)
- Connection pool settings
- Migration settings
- Driver configuration
### 6. DI Integration
- Provider function for database client
- Register in DI container
- Lifecycle management (close on shutdown)
## Implementation Steps
1. **Install Ent**
```bash
go get entgo.io/ent/cmd/ent
```
2. **Initialize Ent Schema**
```bash
go run entgo.io/ent/cmd/ent init User Role Permission AuditLog
```
3. **Define Core Entities**
- Create schema files for each entity
- Define fields and relationships
- Add indexes where needed
4. **Generate Ent Code**
```bash
go generate ./internal/ent
```
5. **Create Database Client**
- Create `internal/infra/database/client.go`
- Implement connection management
- Add migration runner
- Add health check
6. **Add Configuration**
- Update `config/default.yaml`
- Add database configuration section
7. **Integrate with DI**
- Create provider function
- Register in container
- Test connection
## Acceptance Criteria
- [ ] Ent schema compiles and generates code successfully
- [ ] Database client connects to PostgreSQL
- [ ] Core entities can be created and queried
- [ ] Migrations run successfully on startup
- [ ] Connection pooling is configured correctly
- [ ] Database health check works
- [ ] All entities have proper indexes and relationships
- [ ] Database client is injectable via DI
- [ ] Connections are closed gracefully on shutdown
## Related ADRs
- [ADR-0013: Database ORM](../../adr/0013-database-orm.md)
## Implementation Notes
- Use Ent for type-safe database operations
- Configure connection pooling appropriately
- Run migrations on application startup
- Add proper indexes for performance
- Handle database connection errors gracefully
- Support for database migrations in future phases
## Testing
```bash
# Test Ent schema generation
go generate ./internal/ent
go build ./internal/ent
# Test database connection
go test ./internal/infra/database/...
# Test migrations
go run cmd/platform/main.go
```
## Files to Create/Modify
- `internal/ent/schema/user.go` - User entity
- `internal/ent/schema/role.go` - Role entity
- `internal/ent/schema/permission.go` - Permission entity
- `internal/ent/schema/audit_log.go` - AuditLog entity
- `internal/ent/schema/role_permissions.go` - Relationship
- `internal/ent/schema/user_roles.go` - Relationship
- `internal/infra/database/client.go` - Database client
- `internal/di/providers.go` - Add database provider
- `config/default.yaml` - Add database config

40
docs/content/stories/phase1/1.2.1-install-entgoioentcmdent.md
View File

@@ -1,40 +0,0 @@
# Task 1.2.1: Install `entgo.io/ent/cmd/ent`
## Metadata
- **Task ID**: 1.2.1
- **Title**: Install `entgo.io/ent/cmd/ent`
- **Phase**: 1 - Core Kernel & Infrastructure
- **Section**: 1.2
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Install `entgo.io/ent/cmd/ent`
## Requirements
- Install `entgo.io/ent/cmd/ent`
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 1.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 ./...
```

46
docs/content/stories/phase1/1.2.2-initialize-ent-schema.md
View File

@@ -1,46 +0,0 @@
# Task 1.2.2: Initialize Ent schema:
## Metadata
- **Task ID**: 1.2.2
- **Title**: Initialize Ent schema:
- **Phase**: 1 - Core Kernel & Infrastructure
- **Section**: 1.2
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Initialize Ent schema:
## Requirements
- Initialize Ent schema:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 1.2.2 is completed
- [ ] All requirements are met
- [ ] Code compiles and tests pass
## Related ADRs
- See relevant ADRs in `docs/adr/`
## Implementation Notes
- TODO: Add implementation notes
## Testing
```bash
# TODO: Add test commands
go test ./...
```
## Code Reference
```go
go run entgo.io/ent/cmd/ent init User Role Permission AuditLog
```

40
docs/content/stories/phase1/1.2.3-define-core-entities-in-internalentschema.md
View File

@@ -1,40 +0,0 @@
# Task 1.2.3: Define core entities in `internal/ent/schema/`:
## Metadata
- **Task ID**: 1.2.3
- **Title**: Define core entities in `internal/ent/schema/`:
- **Phase**: 1 - Core Kernel & Infrastructure
- **Section**: 1.2
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Define core entities in `internal/ent/schema/`:
## Requirements
- Define core entities in `internal/ent/schema/`:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 1.2.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/phase1/1.2.4-generate-ent-code-go-generate-internalent.md
View File

@@ -1,40 +0,0 @@
# Task 1.2.4: Generate Ent code: `go generate ./internal/ent`
## Metadata
- **Task ID**: 1.2.4
- **Title**: Generate Ent code: `go generate ./internal/ent`
- **Phase**: 1 - Core Kernel & Infrastructure
- **Section**: 1.2
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Generate Ent code: `go generate ./internal/ent`
## Requirements
- Generate Ent code: `go generate ./internal/ent`
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 1.2.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 ./...
```

40
docs/content/stories/phase1/1.2.5-create-internalinfradatabaseclientgo.md
View File

@@ -1,40 +0,0 @@
# Task 1.2.5: Create `internal/infra/database/client.go`:
## Metadata
- **Task ID**: 1.2.5
- **Title**: Create `internal/infra/database/client.go`:
- **Phase**: 1 - Core Kernel & Infrastructure
- **Section**: 1.2
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Create `internal/infra/database/client.go`:
## Requirements
- Create `internal/infra/database/client.go`:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 1.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 ./...
```

40
docs/content/stories/phase1/1.2.6-add-database-config-to-configdefaultyaml.md
View File

@@ -1,40 +0,0 @@
# Task 1.2.6: Add database config to `config/default.yaml`
## Metadata
- **Task ID**: 1.2.6
- **Title**: Add database config to `config/default.yaml`
- **Phase**: 1 - Core Kernel & Infrastructure
- **Section**: 1.2
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Add database config to `config/default.yaml`
## Requirements
- Add database config to `config/default.yaml`
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 1.2.6 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/phase1/1.3-health-metrics-system.md Normal file
View File

@@ -0,0 +1,126 @@
# Story 1.3: Health Monitoring and Metrics System
## Metadata
- **Story ID**: 1.3
- **Title**: Health Monitoring and Metrics System
- **Phase**: 1 - Core Kernel & Infrastructure
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 5-6 hours
- **Dependencies**: 1.1, 1.2
## Goal
Implement comprehensive health checks and Prometheus metrics for monitoring platform health and performance.
## Description
This story creates a complete health monitoring system with liveness and readiness probes, and a comprehensive Prometheus metrics system for tracking HTTP requests, database queries, and errors.
## Deliverables
### 1. Health Check System
- **HealthChecker Interface** (`pkg/health/health.go`):
- `HealthChecker` interface with `Check(ctx context.Context) error` method
- Health status types
- **Health Registry** (`internal/health/registry.go`):
- Thread-safe registry of health checkers
- Register multiple health checkers
- Aggregate health status
- `GET /healthz` endpoint (liveness probe)
- `GET /ready` endpoint (readiness probe with database check)
- Individual component health checks
### 2. Prometheus Metrics System
- **Metrics Registry** (`internal/metrics/metrics.go`):
- Prometheus registry setup
- HTTP request duration histogram
- HTTP request counter (by method, path, status code)
- Database query duration histogram (via Ent interceptor)
- Error counter (by type)
- Custom metrics support
- **Metrics Endpoint**:
- `GET /metrics` endpoint (Prometheus format)
- Proper content type headers
### 3. Database Health Check
- Database connectivity check
- Connection pool status
- Query execution test
### 4. Integration
- Integration with HTTP server
- Integration with DI container
- Middleware for automatic metrics collection
## Implementation Steps
1. **Install Dependencies**
```bash
go get github.com/prometheus/client_golang/prometheus
```
2. **Create Health Check Interface**
- Create `pkg/health/health.go`
- Define HealthChecker interface
3. **Implement Health Registry**
- Create `internal/health/registry.go`
- Implement registry and endpoints
4. **Create Metrics System**
- Create `internal/metrics/metrics.go`
- Define all metrics
- Create registry
5. **Add Database Health Check**
- Implement database health checker
- Register with health registry
6. **Integrate with HTTP Server**
- Add health endpoints
- Add metrics endpoint
- Add metrics middleware
7. **Integrate with DI**
- Create provider functions
- Register in container
## Acceptance Criteria
- [ ] `/healthz` returns 200 when service is alive
- [ ] `/ready` checks database connectivity and returns appropriate status
- [ ] `/metrics` exposes Prometheus metrics in correct format
- [ ] All HTTP requests are measured
- [ ] Database queries are instrumented
- [ ] Metrics are registered in DI container
- [ ] Health checks can be extended by modules
- [ ] Metrics follow Prometheus naming conventions
## Related ADRs
- [ADR-0014: Health Check Implementation](../../adr/0014-health-check-implementation.md)
## Implementation Notes
- Use Prometheus client library
- Follow Prometheus naming conventions
- Health checks should be fast (< 1 second)
- Metrics should have appropriate labels
- Consider adding custom business metrics in future
## Testing
```bash
# Test health endpoints
curl http://localhost:8080/healthz
curl http://localhost:8080/ready
# Test metrics endpoint
curl http://localhost:8080/metrics
# Test metrics collection
go test ./internal/metrics/...
```
## Files to Create/Modify
- `pkg/health/health.go` - Health checker interface
- `internal/health/registry.go` - Health registry
- `internal/metrics/metrics.go` - Metrics system
- `internal/server/server.go` - Add endpoints
- `internal/di/providers.go` - Add providers

40
docs/content/stories/phase1/1.3.1-install-githubcomprometheusclient_golangprometheus.md
View File

@@ -1,40 +0,0 @@
# Task 1.3.1: Install `github.com/prometheus/client_golang/prometheus`
## Metadata
- **Task ID**: 1.3.1
- **Title**: Install `github.com/prometheus/client_golang/prometheus`
- **Phase**: 1 - Core Kernel & Infrastructure
- **Section**: 1.3
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Install `github.com/prometheus/client_golang/prometheus`
## Requirements
- Install `github.com/prometheus/client_golang/prometheus`
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 1.3.1 is completed
- [ ] All requirements are met
- [ ] Code compiles and tests pass
## Related ADRs
- See relevant ADRs in `docs/adr/`
## Implementation Notes
- TODO: Add implementation notes
## Testing
```bash
# TODO: Add test commands
go test ./...
```

40
docs/content/stories/phase1/1.3.2-install-githubcomheptiolabshealthcheck-optional-or.md
View File

@@ -1,40 +0,0 @@
# Task 1.3.2: Install `github.com/heptiolabs/healthcheck` (optional, or custom)
## Metadata
- **Task ID**: 1.3.2
- **Title**: Install `github.com/heptiolabs/healthcheck` (optional, or custom)
- **Phase**: 1 - Core Kernel & Infrastructure
- **Section**: 1.3
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Install `github.com/heptiolabs/healthcheck` (optional, or custom)
## Requirements
- Install `github.com/heptiolabs/healthcheck` (optional, or custom)
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 1.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 ./...
```

48
docs/content/stories/phase1/1.3.3-create-pkghealthhealthgo-interface.md
View File

@@ -1,48 +0,0 @@
# Task 1.3.3: Create `pkg/health/health.go` interface:
## Metadata
- **Task ID**: 1.3.3
- **Title**: Create `pkg/health/health.go` interface:
- **Phase**: 1 - Core Kernel & Infrastructure
- **Section**: 1.3
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Create `pkg/health/health.go` interface:
## Requirements
- Create `pkg/health/health.go` interface:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 1.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 ./...
```
## Code Reference
```go
type HealthChecker interface {
Check(ctx context.Context) error
}
```

40
docs/content/stories/phase1/1.3.4-implement-internalhealthregistrygo.md
View File

@@ -1,40 +0,0 @@
# Task 1.3.4: Implement `internal/health/registry.go`:
## Metadata
- **Task ID**: 1.3.4
- **Title**: Implement `internal/health/registry.go`:
- **Phase**: 1 - Core Kernel & Infrastructure
- **Section**: 1.3
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Implement `internal/health/registry.go`:
## Requirements
- Implement `internal/health/registry.go`:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 1.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 ./...
```

40
docs/content/stories/phase1/1.3.5-create-internalmetricsmetricsgo.md
View File

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

40
docs/content/stories/phase1/1.3.6-add-metrics-endpoint-prometheus-format.md
View File

@@ -1,40 +0,0 @@
# Task 1.3.6: Add `/metrics` endpoint (Prometheus format)
## Metadata
- **Task ID**: 1.3.6
- **Title**: Add `/metrics` endpoint (Prometheus format)
- **Phase**: 1 - Core Kernel & Infrastructure
- **Section**: 1.3
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Add `/metrics` endpoint (Prometheus format)
## Requirements
- Add `/metrics` endpoint (Prometheus format)
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 1.3.6 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/phase1/1.3.7-register-endpoints-in-main-http-router.md
View File

@@ -1,40 +0,0 @@
# Task 1.3.7: Register endpoints in main HTTP router
## Metadata
- **Task ID**: 1.3.7
- **Title**: Register endpoints in main HTTP router
- **Phase**: 1 - Core Kernel & Infrastructure
- **Section**: 1.3
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Register endpoints in main HTTP router
## Requirements
- Register endpoints in main HTTP router
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 1.3.7 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 ./...
```

103
docs/content/stories/phase1/1.4-error-handling.md Normal file
View File

@@ -0,0 +1,103 @@
# Story 1.4: Error Handling and Error Bus
## Metadata
- **Story ID**: 1.4
- **Title**: Error Handling and Error Bus
- **Phase**: 1 - Core Kernel & Infrastructure
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 4-5 hours
- **Dependencies**: 1.1, 1.3
## Goal
Implement centralized error handling with an error bus that captures, logs, and optionally reports all application errors.
## Description
This story creates a complete error handling system with an error bus that captures all errors, logs them with context, and provides a foundation for future error reporting integrations (like Sentry).
## Deliverables
### 1. Error Bus Interface (`pkg/errorbus/errorbus.go`)
- `ErrorPublisher` interface with `Publish(err error)` method
- Error context support
- Error categorization
### 2. Channel-Based Error Bus (`internal/errorbus/channel_bus.go`)
- Buffered channel for error publishing
- Background goroutine consumes errors
- Logs all errors with context (request ID, user ID, etc.)
- Error aggregation
- Optional: Sentry integration placeholder (Phase 6)
### 3. Panic Recovery Middleware
- Recovers from panics in HTTP handlers
- Publishes panics to error bus
- Returns appropriate HTTP error responses (500)
- Preserves error context
### 4. Integration
- Integration with DI container
- Integration with HTTP middleware stack
- Integration with logger
## Implementation Steps
1. **Create Error Bus Interface**
- Create `pkg/errorbus/errorbus.go`
- Define ErrorPublisher interface
2. **Implement Channel-Based Error Bus**
- Create `internal/errorbus/channel_bus.go`
- Implement buffered channel
- Implement background consumer
- Add error logging
3. **Create Panic Recovery Middleware**
- Create middleware for Gin
- Recover from panics
- Publish to error bus
- Return error responses
4. **Integrate with DI**
- Create provider function
- Register in container
5. **Integrate with HTTP Server**
- Add panic recovery middleware
- Test error handling
## Acceptance Criteria
- [ ] Errors are captured and logged via error bus
- [ ] Panics are recovered and logged
- [ ] HTTP handlers return proper error responses
- [ ] Error bus is injectable via DI
- [ ] Error context (request ID, user ID) is preserved
- [ ] Background error consumer works correctly
- [ ] Error bus doesn't block request handling
## Related ADRs
- [ADR-0015: Error Bus Implementation](../../adr/0015-error-bus-implementation.md)
- [ADR-0026: Error Reporting Service](../../adr/0026-error-reporting-service.md)
## Implementation Notes
- Use buffered channels to prevent blocking
- Background goroutine should handle errors asynchronously
- Preserve error context (stack traces, request IDs)
- Consider error rate limiting in future
- Placeholder for Sentry integration in Phase 6
## Testing
```bash
# Test error bus
go test ./internal/errorbus/...
# Test panic recovery
# Trigger panic in handler and verify recovery
```
## Files to Create/Modify
- `pkg/errorbus/errorbus.go` - Error bus interface
- `internal/errorbus/channel_bus.go` - Error bus implementation
- `internal/server/middleware.go` - Panic recovery middleware
- `internal/di/providers.go` - Add error bus provider

48
docs/content/stories/phase1/1.4.1-create-pkgerrorbuserrorbusgo-interface.md
View File

@@ -1,48 +0,0 @@
# Task 1.4.1: Create `pkg/errorbus/errorbus.go` interface:
## Metadata
- **Task ID**: 1.4.1
- **Title**: Create `pkg/errorbus/errorbus.go` interface:
- **Phase**: 1 - Core Kernel & Infrastructure
- **Section**: 1.4
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Create `pkg/errorbus/errorbus.go` interface:
## Requirements
- Create `pkg/errorbus/errorbus.go` interface:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 1.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 ErrorPublisher interface {
Publish(err error)
}
```

40
docs/content/stories/phase1/1.4.2-implement-internalerrorbuschannel_busgo.md
View File

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

40
docs/content/stories/phase1/1.4.3-add-panic-recovery-middleware-that-publishes-to-er.md
View File

@@ -1,40 +0,0 @@
# Task 1.4.3: Add panic recovery middleware that publishes to error bus
## Metadata
- **Task ID**: 1.4.3
- **Title**: Add panic recovery middleware that publishes to error bus
- **Phase**: 1 - Core Kernel & Infrastructure
- **Section**: 1.4
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Add panic recovery middleware that publishes to error bus
## Requirements
- Add panic recovery middleware that publishes to error bus
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 1.4.3 is completed
- [ ] All requirements are met
- [ ] Code compiles and tests pass
## Related ADRs
- See relevant ADRs in `docs/adr/`
## Implementation Notes
- TODO: Add implementation notes
## Testing
```bash
# TODO: Add test commands
go test ./...
```

40
docs/content/stories/phase1/1.4.4-register-error-bus-in-di-container.md
View File

@@ -1,40 +0,0 @@
# Task 1.4.4: Register error bus in DI container
## Metadata
- **Task ID**: 1.4.4
- **Title**: Register error bus in DI container
- **Phase**: 1 - Core Kernel & Infrastructure
- **Section**: 1.4
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Register error bus in DI container
## Requirements
- Register error bus in DI container
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 1.4.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 ./...
```

122
docs/content/stories/phase1/1.5-http-server.md Normal file
View File

@@ -0,0 +1,122 @@
# Story 1.5: HTTP Server Foundation with Middleware Stack
## Metadata
- **Story ID**: 1.5
- **Title**: HTTP Server Foundation with Middleware Stack
- **Phase**: 1 - Core Kernel & Infrastructure
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 6-8 hours
- **Dependencies**: 1.1, 1.3, 1.4
## Goal
Create a production-ready HTTP server with comprehensive middleware for security, observability, and error handling.
## Description
This story implements a complete HTTP server using Gin with a comprehensive middleware stack including request ID generation, structured logging, panic recovery, metrics collection, CORS, and graceful shutdown.
## Deliverables
### 1. HTTP Server (`internal/server/server.go`)
- Gin router initialization
- Server configuration (port, host, timeouts)
- Graceful shutdown handling
### 2. Comprehensive Middleware Stack
- **Request ID Generator**: Unique ID per request
- **Structured Logging**: Log all requests with context
- **Panic Recovery**: Recover panics → error bus
- **Prometheus Metrics**: Collect request metrics
- **CORS Support**: Configurable CORS headers
- **Request Timeout**: Handle request timeouts
- **Response Compression**: Gzip compression for responses
### 3. Core Route Registration
- `GET /healthz` - Liveness probe
- `GET /ready` - Readiness probe
- `GET /metrics` - Prometheus metrics
### 4. FX Lifecycle Integration
- HTTP server starts on `OnStart` hook
- Graceful shutdown on `OnStop` hook (drains connections)
- Port configuration from config system
### 5. Integration
- Integration with main application entry point
- Integration with all middleware systems
## Implementation Steps
1. **Install Dependencies**
```bash
go get github.com/gin-gonic/gin
```
2. **Create HTTP Server**
- Create `internal/server/server.go`
- Initialize Gin router
- Configure server settings
3. **Implement Middleware**
- Request ID middleware
- Logging middleware
- Panic recovery middleware
- Metrics middleware
- CORS middleware
- Timeout middleware
- Compression middleware
4. **Register Core Routes**
- Health endpoints
- Metrics endpoint
5. **Integrate with FX**
- Add lifecycle hooks
- Handle graceful shutdown
6. **Test Server**
- Verify server starts
- Test all endpoints
- Test graceful shutdown
## Acceptance Criteria
- [ ] HTTP server starts successfully
- [ ] All middleware executes in correct order
- [ ] Request IDs are generated and logged
- [ ] Metrics are collected for all requests
- [ ] Panics are recovered and handled
- [ ] Graceful shutdown works correctly
- [ ] Server is configurable via config system
- [ ] CORS is configurable per environment
- [ ] All core endpoints work correctly
## Related ADRs
- [ADR-0006: HTTP Framework](../../adr/0006-http-framework.md)
## Implementation Notes
- Use Gin for HTTP routing
- Middleware order is important
- Support graceful shutdown with connection draining
- CORS should be configurable per environment
- Consider adding rate limiting in future (Phase 6)
## Testing
```bash
# Test server startup
go run cmd/platform/main.go
# Test endpoints
curl http://localhost:8080/healthz
curl http://localhost:8080/ready
curl http://localhost:8080/metrics
# Test graceful shutdown
# Send SIGTERM and verify graceful shutdown
```
## Files to Create/Modify
- `internal/server/server.go` - HTTP server
- `internal/server/middleware.go` - Middleware functions
- `internal/di/providers.go` - Add server provider
- `config/default.yaml` - Add server configuration

40
docs/content/stories/phase1/1.5.1-install-githubcomgin-gonicgin.md
View File

@@ -1,40 +0,0 @@
# Task 1.5.1: Install `github.com/gin-gonic/gin`
## Metadata
- **Task ID**: 1.5.1
- **Title**: Install `github.com/gin-gonic/gin`
- **Phase**: 1 - Core Kernel & Infrastructure
- **Section**: 1.5
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Install `github.com/gin-gonic/gin`
## Requirements
- Install `github.com/gin-gonic/gin`
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 1.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/phase1/1.5.2-create-internalserverservergo.md
View File

@@ -1,40 +0,0 @@
# Task 1.5.2: Create `internal/server/server.go`:
## Metadata
- **Task ID**: 1.5.2
- **Title**: Create `internal/server/server.go`:
- **Phase**: 1 - Core Kernel & Infrastructure
- **Section**: 1.5
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Create `internal/server/server.go`:
## Requirements
- Create `internal/server/server.go`:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 1.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/phase1/1.5.3-wire-http-server-into-fx-lifecycle.md
View File

@@ -1,40 +0,0 @@
# Task 1.5.3: Wire HTTP server into fx lifecycle:
## Metadata
- **Task ID**: 1.5.3
- **Title**: Wire HTTP server into fx lifecycle:
- **Phase**: 1 - Core Kernel & Infrastructure
- **Section**: 1.5
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Wire HTTP server into fx lifecycle:
## Requirements
- Wire HTTP server into fx lifecycle:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 1.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 ./...
```

40
docs/content/stories/phase1/1.5.4-update-cmdplatformmaingo-to-use-fx-lifecycle.md
View File

@@ -1,40 +0,0 @@
# Task 1.5.4: Update `cmd/platform/main.go` to use fx lifecycle
## Metadata
- **Task ID**: 1.5.4
- **Title**: Update `cmd/platform/main.go` to use fx lifecycle
- **Phase**: 1 - Core Kernel & Infrastructure
- **Section**: 1.5
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Update `cmd/platform/main.go` to use fx lifecycle
## Requirements
- Update `cmd/platform/main.go` to use fx lifecycle
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 1.5.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 ./...
```

117
docs/content/stories/phase1/1.6-opentelemetry.md Normal file
View File

@@ -0,0 +1,117 @@
# Story 1.6: OpenTelemetry Distributed Tracing
## Metadata
- **Story ID**: 1.6
- **Title**: OpenTelemetry Distributed Tracing
- **Phase**: 1 - Core Kernel & Infrastructure
- **Status**: Pending
- **Priority**: Medium
- **Estimated Time**: 5-6 hours
- **Dependencies**: 1.1, 1.5
## Goal
Integrate OpenTelemetry for distributed tracing across the platform to enable observability in production.
## Description
This story implements OpenTelemetry tracing for HTTP requests and database queries, enabling distributed tracing across the platform. Traces will be exported to stdout in development and OTLP collector in production.
## Deliverables
### 1. OpenTelemetry Setup (`internal/observability/tracer.go`)
- TracerProvider initialization
- Export to stdout (development mode)
- Export to OTLP collector (production mode)
- Trace context propagation
- Resource attributes (service name, version, etc.)
### 2. HTTP Instrumentation Middleware
- Automatic span creation for HTTP requests
- Trace context propagation via headers
- Span attributes (method, path, status code, duration)
- Error recording in spans
### 3. Database Instrumentation
- Ent interceptor for database queries
- Query spans with timing and parameters
- Database operation attributes
### 4. Integration with Logger
- Include trace ID in logs
- Correlate logs with traces
- Span context in structured logs
### 5. Configuration
- Tracing configuration in config files
- Enable/disable tracing
- Export endpoint configuration
## Implementation Steps
1. **Install Dependencies**
```bash
go get go.opentelemetry.io/otel
go get go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp
go get go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp
```
2. **Create Tracer Setup**
- Create `internal/observability/tracer.go`
- Initialize TracerProvider
- Set up exporters
3. **Add HTTP Instrumentation**
- Create HTTP middleware
- Instrument Gin router
- Add trace context propagation
4. **Add Database Instrumentation**
- Create Ent interceptor
- Instrument database queries
- Add query attributes
5. **Integrate with Logger**
- Extract trace ID from context
- Add trace ID to logs
6. **Add Configuration**
- Add tracing config
- Configure export endpoints
## Acceptance Criteria
- [ ] HTTP requests create OpenTelemetry spans
- [ ] Database queries are traced
- [ ] Trace context propagates across service boundaries
- [ ] Trace IDs are included in logs
- [ ] Traces export correctly to configured backend
- [ ] Tracing works in both development and production modes
- [ ] Tracing has minimal performance impact
- [ ] Spans have appropriate attributes
## Related ADRs
- [ADR-0016: OpenTelemetry Observability](../../adr/0016-opentelemetry-observability.md)
## Implementation Notes
- Use OpenTelemetry Go SDK
- Support both stdout and OTLP exporters
- Trace context should propagate via HTTP headers
- Consider sampling for high-volume production
- Minimize performance impact
## Testing
```bash
# Test tracing
go run cmd/platform/main.go
# Make requests and verify traces
curl http://localhost:8080/healthz
# Check trace export (stdout or OTLP)
```
## Files to Create/Modify
- `internal/observability/tracer.go` - Tracer setup
- `internal/server/middleware.go` - Add tracing middleware
- `internal/infra/database/client.go` - Add tracing interceptor
- `internal/logger/zap_logger.go` - Add trace ID to logs
- `config/default.yaml` - Add tracing configuration

40
docs/content/stories/phase1/1.6.1-install-opentelemetry-packages.md
View File

@@ -1,40 +0,0 @@
# Task 1.6.1: Install OpenTelemetry packages:
## Metadata
- **Task ID**: 1.6.1
- **Title**: Install OpenTelemetry packages:
- **Phase**: 1 - Core Kernel & Infrastructure
- **Section**: 1.6
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Install OpenTelemetry packages:
## Requirements
- Install OpenTelemetry packages:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 1.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 ./...
```

40
docs/content/stories/phase1/1.6.2-create-internalobservabilitytracergo.md
View File

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

40
docs/content/stories/phase1/1.6.3-add-http-instrumentation-middleware.md
View File

@@ -1,40 +0,0 @@
# Task 1.6.3: Add HTTP instrumentation middleware
## Metadata
- **Task ID**: 1.6.3
- **Title**: Add HTTP instrumentation middleware
- **Phase**: 1 - Core Kernel & Infrastructure
- **Section**: 1.6
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Add HTTP instrumentation middleware
## Requirements
- Add HTTP instrumentation middleware
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 1.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 ./...
```

40
docs/content/stories/phase1/1.6.4-add-trace-context-propagation-to-requests.md
View File

@@ -1,40 +0,0 @@
# Task 1.6.4: Add trace context propagation to requests
## Metadata
- **Task ID**: 1.6.4
- **Title**: Add trace context propagation to requests
- **Phase**: 1 - Core Kernel & Infrastructure
- **Section**: 1.6
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Add trace context propagation to requests
## Requirements
- Add trace context propagation to requests
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 1.6.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 ./...
```

114
docs/content/stories/phase1/1.7-service-abstraction-layer.md Normal file
View File

@@ -0,0 +1,114 @@
# Story 1.7: Service Client Interfaces
## Metadata
- **Story ID**: 1.7
- **Title**: Service Client Interfaces
- **Phase**: 1 - Core Kernel & Infrastructure
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 4-6 hours
- **Dependencies**: 1.1, 1.2, 2.1, 2.2
## Goal
Create service client interfaces for all core services to enable microservices communication. All inter-service communication will go through these interfaces.
## Description
This story implements the foundation for microservices architecture by creating service client interfaces for all core services. These interfaces will be implemented as gRPC clients (primary) or HTTP clients (fallback), ensuring all services communicate via network calls.
## Deliverables
### 1. Service Client Interfaces (`pkg/services/`)
Define service client interfaces for all core services:
- `IdentityServiceClient` - User and identity operations
- `AuthServiceClient` - Authentication operations
- `AuthzServiceClient` - Authorization operations
- `PermissionServiceClient` - Permission resolution
- `AuditServiceClient` - Audit logging
- `CacheServiceClient` - Cache operations (if needed)
- `EventBusClient` - Event publishing (already abstracted)
### 2. Service Client Factory (`internal/services/factory.go`)
Factory pattern for creating service clients:
- Create gRPC clients (primary)
- Create HTTP clients (fallback)
- Support service registry integration
- Handle client lifecycle and connection pooling
### 3. Configuration
- Service client configuration in `config/default.yaml`:
```yaml
services:
default_protocol: grpc # grpc, http
registry:
type: consul # consul, kubernetes, etcd
consul:
address: localhost:8500
```
### 5. DI Integration
- Provider functions for service clients
- Register in DI container
- Support service client injection
## Implementation Steps
1. **Define Service Client Interfaces**
- Create `pkg/services/identity.go`
- Create `pkg/services/auth.go`
- Create `pkg/services/authz.go`
- Define all interface methods
- Design for network calls (context, timeouts, errors)
2. **Create Service Factory**
- Create `internal/services/factory.go`
- Implement gRPC client creation
- Implement HTTP client creation (fallback)
- Support service registry integration
3. **Add Configuration**
- Add service configuration
- Support protocol selection (gRPC/HTTP)
- Service registry configuration
4. **Update Core Services**
- Services expose gRPC servers
- Services use service clients for inter-service calls
- No direct in-process calls between services
## Acceptance Criteria
- [ ] Service client interfaces are defined for all core services
- [ ] Service factory creates gRPC clients
- [ ] Service factory creates HTTP clients (fallback)
- [ ] Service clients are injectable via DI
- [ ] Configuration supports protocol selection
- [ ] Service clients are testable and mockable
- [ ] All inter-service communication goes through service clients
## Related ADRs
- [ADR-0029: Microservices Architecture](../../adr/0029-microservices-architecture.md)
- [ADR-0030: Service Communication Strategy](../../adr/0030-service-communication-strategy.md)
## Implementation Notes
- Interfaces should match existing service methods
- Use context for all operations
- Support cancellation and timeouts
- Design for network calls (retries, circuit breakers)
- gRPC will be implemented in Phase 5, but interfaces are defined here
## Testing
```bash
# Test service clients
go test ./internal/services/...
# Test service factory
go test ./internal/services/factory_test.go
```
## Files to Create/Modify
- `pkg/services/identity.go` - Identity service client interface
- `pkg/services/auth.go` - Auth service client interface
- `pkg/services/authz.go` - Authz service client interface
- `internal/services/factory.go` - Service client factory
- `internal/di/providers.go` - Add service client providers
- `config/default.yaml` - Add service configuration

90
docs/content/stories/phase1/README.md
View File

@@ -1,64 +1,58 @@
# Phase 1: Core Kernel & Infrastructure # Phase 1: Core Kernel & Infrastructure
## Overview ## Overview
Implement dependency injection container, set up database (Ent ORM), create health and metrics endpoints, implement error bus, and add basic HTTP server with middleware. Extend DI container to support all core services, implement database layer with Ent ORM, build health monitoring and metrics system, create error handling and error bus, establish HTTP server with comprehensive middleware stack, and integrate OpenTelemetry for distributed tracing.
## Tasks ## Stories
### 1.1 Dependency Injection Container ### 1.1 Enhanced Dependency Injection Container
- [1.1.1 - Extend DI Container](./1.1.1-extend-internaldicontainergo.md) - [Story: 1.1 - Enhanced DI Container](./1.1-enhanced-di-container.md)
- [1.1.2 - Create DI Providers](./1.1.2-create-internaldiprovidersgo.md) - **Goal:** Extend the DI container to provide all core infrastructure services with proper lifecycle management.
- [1.1.3 - Add Core Module](./1.1.3-add-internaldicore_modulego.md) - **Deliverables:** Extended DI container, provider functions for all services, core module export
### 1.2 Database Setup (Ent) ### 1.2 Database Layer with Ent ORM
- [1.2.1 - Install Ent](./1.2.1-install-entgoioentcmdent.md) - [Story: 1.2 - Database Layer](./1.2-database-layer.md)
- [1.2.2 - Initialize Ent Schema](./1.2.2-initialize-ent-schema.md) - **Goal:** Set up a complete database layer using Ent ORM with core domain entities, migrations, and connection management.
- [1.2.3 - Define Core Entities](./1.2.3-define-core-entities-in-internalentschema.md) - **Deliverables:** Ent schema, core entities, database client, migrations, connection pooling
- [1.2.4 - Generate Ent Code](./1.2.4-generate-ent-code-go-generate-internalent.md)
- [1.2.5 - Create Database Client](./1.2.5-create-internalinfradatabaseclientgo.md)
- [1.2.6 - Add Database Config](./1.2.6-add-database-config-to-configdefaultyaml.md)
### 1.3 Health & Metrics ### 1.3 Health Monitoring and Metrics System
- [1.3.1 - Install Prometheus](./1.3.1-install-githubcomprometheusclient_golangprometheus.md) - [Story: 1.3 - Health & Metrics](./1.3-health-metrics-system.md)
- [1.3.2 - Install Health Check](./1.3.2-install-githubcomheptiolabshealthcheck-optional-or.md) - **Goal:** Implement comprehensive health checks and Prometheus metrics for monitoring platform health and performance.
- [1.3.3 - Create Health Interface](./1.3.3-create-pkghealthhealthgo-interface.md) - **Deliverables:** Health check system, Prometheus metrics, health endpoints, metrics endpoint
- [1.3.4 - Implement Health Registry](./1.3.4-implement-internalhealthregistrygo.md)
- [1.3.5 - Create Metrics](./1.3.5-create-internalmetricsmetricsgo.md)
- [1.3.6 - Add Metrics Endpoint](./1.3.6-add-metrics-endpoint-prometheus-format.md)
- [1.3.7 - Register Endpoints](./1.3.7-register-endpoints-in-main-http-router.md)
### 1.4 Error Bus ### 1.4 Error Handling and Error Bus
- [1.4.1 - Create Error Bus Interface](./1.4.1-create-pkgerrorbuserrorbusgo-interface.md) - [Story: 1.4 - Error Handling](./1.4-error-handling.md)
- [1.4.2 - Implement Channel Bus](./1.4.2-implement-internalerrorbuschannel_busgo.md) - **Goal:** Implement centralized error handling with an error bus that captures, logs, and optionally reports all application errors.
- [1.4.3 - Add Panic Recovery Middleware](./1.4.3-add-panic-recovery-middleware-that-publishes-to-er.md) - **Deliverables:** Error bus interface, channel-based implementation, panic recovery middleware
- [1.4.4 - Register Error Bus](./1.4.4-register-error-bus-in-di-container.md)
### 1.5 HTTP Server Foundation ### 1.5 HTTP Server Foundation with Middleware Stack
- [1.5.1 - Install Gin](./1.5.1-install-githubcomgin-gonicgin.md) - [Story: 1.5 - HTTP Server](./1.5-http-server.md)
- [1.5.2 - Create Server](./1.5.2-create-internalserverservergo.md) - **Goal:** Create a production-ready HTTP server with comprehensive middleware for security, observability, and error handling.
- [1.5.3 - Wire HTTP Server](./1.5.3-wire-http-server-into-fx-lifecycle.md) - **Deliverables:** HTTP server, comprehensive middleware stack, core routes, FX lifecycle integration
- [1.5.4 - Update Main Entry Point](./1.5.4-update-cmdplatformmaingo-to-use-fx-lifecycle.md)
### 1.6 Observability (OpenTelemetry) ### 1.6 OpenTelemetry Distributed Tracing
- [1.6.1 - Install OpenTelemetry](./1.6.1-install-opentelemetry-packages.md) - [Story: 1.6 - OpenTelemetry](./1.6-opentelemetry.md)
- [1.6.2 - Create Tracer](./1.6.2-create-internalobservabilitytracergo.md) - **Goal:** Integrate OpenTelemetry for distributed tracing across the platform to enable observability in production.
- [1.6.3 - Add HTTP Instrumentation](./1.6.3-add-http-instrumentation-middleware.md) - **Deliverables:** OpenTelemetry setup, HTTP instrumentation, database instrumentation, trace-log correlation
- [1.6.4 - Add Trace Context Propagation](./1.6.4-add-trace-context-propagation-to-requests.md)
### 1.7 Service Client Interfaces
- [Story: 1.7 - Service Client Interfaces](./1.7-service-abstraction-layer.md)
- **Goal:** Create service client interfaces for all core services to enable microservices communication.
- **Deliverables:** Service client interfaces, service factory, configuration
## Deliverables Checklist ## Deliverables Checklist
- [ ] DI container with all core services registered - [ ] DI container with all core services
- [ ] Database schema defined with Ent - [ ] Database client with Ent schema
- [ ] Health check endpoints working - [ ] Health and metrics endpoints functional
- [ ] Metrics endpoint exposed - [ ] Error bus captures and logs errors
- [ ] Error bus implemented and integrated
- [ ] HTTP server with middleware stack - [ ] HTTP server with middleware stack
- [ ] OpenTelemetry tracing integrated - [ ] Basic observability with OpenTelemetry
- [ ] Service client interfaces for microservices
## Acceptance Criteria ## Acceptance Criteria
- `GET /healthz` returns 200 - `GET /healthz` returns 200
- `GET /ready` checks database connectivity - `GET /ready` checks DB connectivity
- `GET /metrics` returns Prometheus metrics - `GET /metrics` exposes Prometheus metrics
- HTTP requests are logged with structured logging - Panic recovery logs errors via error bus
- Panic recovery middleware catches and reports errors - Database migrations run on startup
- OpenTelemetry traces are generated for HTTP requests - HTTP requests are traced with OpenTelemetry

139
docs/content/stories/phase2/2.1-jwt-authentication.md Normal file
View File

@@ -0,0 +1,139 @@
# Story 2.1: JWT Authentication System
## Metadata
- **Story ID**: 2.1
- **Title**: JWT Authentication System
- **Phase**: 2 - Authentication & Authorization
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 6-8 hours
- **Dependencies**: 1.2, 1.5
## Goal
Implement a complete JWT-based authentication system with access tokens, refresh tokens, and secure token management.
## Description
This story implements the complete JWT authentication system including token generation, verification, authentication middleware, and login/refresh endpoints. The system supports short-lived access tokens and long-lived refresh tokens for secure authentication.
## Deliverables
### 1. Authentication Interfaces (`pkg/auth/auth.go`)
- `Authenticator` interface for token generation and verification
- `TokenClaims` struct with user ID, roles, tenant ID, expiration
- Token validation utilities
### 2. JWT Implementation (`internal/auth/jwt_auth.go`)
- Generate short-lived access tokens (15 minutes default)
- Generate long-lived refresh tokens (7 days default)
- Token signature verification using HMAC or RSA
- Token expiration validation
- Claims extraction and validation
### 3. Authentication Middleware (`internal/auth/middleware.go`)
- Extract JWT from `Authorization: Bearer <token>` header
- Verify token validity (signature and expiration)
- Inject authenticated user into request context
- Helper function: `auth.FromContext(ctx) *User`
- Handle authentication errors appropriately
### 4. Authentication Endpoints
- `POST /api/v1/auth/login` - Authenticate user and return tokens
- Validate email and password
- Return access + refresh tokens
- Log login attempts
- `POST /api/v1/auth/refresh` - Refresh access token using refresh token
- Validate refresh token
- Issue new access token
- Optionally rotate refresh token
### 5. gRPC Server (Microservices)
- Expose gRPC server for authentication service
- gRPC service definition in `api/proto/auth.proto`
- gRPC server implementation in `internal/auth/grpc/server.go`
- Service registration in service registry
### 6. Integration
- Integration with DI container
- Use `IdentityServiceClient` for user operations (if Identity service is separate)
- Integration with HTTP server
- Integration with user repository
- Integration with audit logging
## Implementation Steps
1. **Install Dependencies**
```bash
go get github.com/golang-jwt/jwt/v5
```
2. **Create Authentication Interfaces**
- Create `pkg/auth/auth.go`
- Define Authenticator interface
- Define TokenClaims struct
3. **Implement JWT Authentication**
- Create `internal/auth/jwt_auth.go`
- Implement token generation
- Implement token verification
- Handle token expiration
4. **Create Authentication Middleware**
- Create `internal/auth/middleware.go`
- Implement token extraction
- Implement token verification
- Inject user into context
5. **Create Authentication Endpoints**
- Create login handler
- Create refresh handler
- Add routes to HTTP server
6. **Integrate with DI**
- Create provider function
- Register in container
## Acceptance Criteria
- [ ] Users can login and receive access and refresh tokens
- [ ] Access tokens expire after configured duration
- [ ] Refresh tokens can be used to obtain new access tokens
- [ ] Invalid tokens are rejected with appropriate errors
- [ ] Authenticated user is available in request context
- [ ] Login attempts are logged (success and failure)
- [ ] Token secrets are configurable
- [ ] Token claims include user ID, roles, and tenant ID
## Related ADRs
- [ADR-0017: JWT Token Strategy](../../adr/0017-jwt-token-strategy.md)
- [ADR-0029: Microservices Architecture](../../adr/0029-microservices-architecture.md)
- [ADR-0030: Service Communication Strategy](../../adr/0030-service-communication-strategy.md)
## Implementation Notes
- Use JWT v5 library
- Support both HMAC and RSA signing
- Token secrets should be configurable
- Consider token blacklisting for logout (future enhancement)
- Refresh tokens should be stored securely (database or cache)
## Testing
```bash
# Test authentication
go test ./internal/auth/...
# Test login endpoint
curl -X POST http://localhost:8080/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"user@example.com","password":"password"}'
# Test refresh endpoint
curl -X POST http://localhost:8080/api/v1/auth/refresh \
-H "Authorization: Bearer <refresh_token>"
```
## Files to Create/Modify
- `pkg/auth/auth.go` - Authentication interfaces
- `internal/auth/jwt_auth.go` - JWT implementation
- `internal/auth/middleware.go` - Authentication middleware
- `internal/auth/handler.go` - Authentication handlers
- `internal/di/providers.go` - Add auth provider
- `config/default.yaml` - Add JWT configuration

40
docs/content/stories/phase2/2.1.1-install-githubcomgolang-jwtjwtv5.md
View File

@@ -1,40 +0,0 @@
# Task 2.1.1: Install `github.com/golang-jwt/jwt/v5`
## Metadata
- **Task ID**: 2.1.1
- **Title**: Install `github.com/golang-jwt/jwt/v5`
- **Phase**: 2 - Authentication & Authorization
- **Section**: 2.1
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Install `github.com/golang-jwt/jwt/v5`
## Requirements
- Install `github.com/golang-jwt/jwt/v5`
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 2.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 ./...
```

56
docs/content/stories/phase2/2.1.2-create-pkgauthauthgo-interfaces.md
View File

@@ -1,56 +0,0 @@
# Task 2.1.2: Create `pkg/auth/auth.go` interfaces:
## Metadata
- **Task ID**: 2.1.2
- **Title**: Create `pkg/auth/auth.go` interfaces:
- **Phase**: 2 - Authentication & Authorization
- **Section**: 2.1
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Create `pkg/auth/auth.go` interfaces:
## Requirements
- Create `pkg/auth/auth.go` interfaces:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 2.1.2 is completed
- [ ] All requirements are met
- [ ] Code compiles and tests pass
## Related ADRs
- See relevant ADRs in `docs/adr/`
## Implementation Notes
- TODO: Add implementation notes
## Testing
```bash
# TODO: Add test commands
go test ./...
```
## Code Reference
```go
type Authenticator interface {
GenerateToken(userID string, roles []string, tenantID string) (string, error)
VerifyToken(token string) (*TokenClaims, error)
}
type TokenClaims struct {
UserID string
Roles []string
TenantID string
ExpiresAt time.Time
}
```

40
docs/content/stories/phase2/2.1.3-implement-internalauthjwt_authgo.md
View File

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

40
docs/content/stories/phase2/2.1.4-create-internalauthmiddlewarego.md
View File

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

40
docs/content/stories/phase2/2.1.5-add-login-endpoint-post-apiv1authlogin.md
View File

@@ -1,40 +0,0 @@
# Task 2.1.5: Add login endpoint: `POST /api/v1/auth/login`
## Metadata
- **Task ID**: 2.1.5
- **Title**: Add login endpoint: `POST /api/v1/auth/login`
- **Phase**: 2 - Authentication & Authorization
- **Section**: 2.1
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Add login endpoint: `POST /api/v1/auth/login`
## Requirements
- Add login endpoint: `POST /api/v1/auth/login`
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 2.1.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 ./...
```

40
docs/content/stories/phase2/2.1.6-add-refresh-endpoint-post-apiv1authrefresh.md
View File

@@ -1,40 +0,0 @@
# Task 2.1.6: Add refresh endpoint: `POST /api/v1/auth/refresh`
## Metadata
- **Task ID**: 2.1.6
- **Title**: Add refresh endpoint: `POST /api/v1/auth/refresh`
- **Phase**: 2 - Authentication & Authorization
- **Section**: 2.1
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Add refresh endpoint: `POST /api/v1/auth/refresh`
## Requirements
- Add refresh endpoint: `POST /api/v1/auth/refresh`
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 2.1.6 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 ./...
```

82
docs/content/stories/phase2/2.2-identity-management.md Normal file
View File

@@ -0,0 +1,82 @@
# Story 2.2: Identity Management System
## Metadata
- **Story ID**: 2.2
- **Title**: Identity Management System
- **Phase**: 2 - Authentication & Authorization
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 8-10 hours
- **Dependencies**: 1.2, 2.1
## Goal
Build a complete user identity management system with registration, email verification, password management, and user CRUD operations.
## Description
This story implements the complete user identity management system including user registration, email verification, password reset, password change, and user profile management. All operations are secured and audited.
## Deliverables
### 1. Identity Interfaces (`pkg/identity/identity.go`)
- `UserRepository` interface for user data access
- `UserService` interface for user business logic
- User domain models
### 2. User Repository (`internal/identity/user_repo.go`)
- CRUD operations using Ent
- Password hashing (bcrypt or argon2)
- Email uniqueness validation
- User lookup by ID and email
- User search and pagination
### 3. User Service (`internal/identity/user_service.go`)
- User registration with email verification token generation
- Email verification flow
- Password reset flow (token-based, time-limited)
- Password change with old password verification
- User profile updates
- User deletion (soft delete option)
### 4. User Management API Endpoints
- `POST /api/v1/users` - Register new user
- `GET /api/v1/users/:id` - Get user profile (authorized)
- `PUT /api/v1/users/:id` - Update user profile (authorized)
- `DELETE /api/v1/users/:id` - Delete user (admin only)
- `POST /api/v1/users/verify-email` - Verify email with token
- `POST /api/v1/users/reset-password` - Request password reset
- `POST /api/v1/users/change-password` - Change password
### 5. gRPC Server (Microservices)
- Expose gRPC server for identity service
- gRPC service definition in `api/proto/identity.proto`
- gRPC server implementation in `internal/identity/grpc/server.go`
- Service registration in service registry
### 6. Integration
- Integration with email notification system (Phase 5 placeholder)
- Integration with audit logging
- Integration with authentication system
- Identity service is an independent service that can be deployed separately
## Acceptance Criteria
- [ ] Users can register with email and password
- [ ] Passwords are securely hashed
- [ ] Email verification tokens are generated and validated
- [ ] Password reset flow works end-to-end
- [ ] Users can update their profiles
- [ ] User operations require proper authentication
- [ ] All user actions are audited
- [ ] Email uniqueness is enforced
## Related ADRs
- [ADR-0018: Password Hashing](../../adr/0018-password-hashing.md)
- [ADR-0029: Microservices Architecture](../../adr/0029-microservices-architecture.md)
- [ADR-0030: Service Communication Strategy](../../adr/0030-service-communication-strategy.md)
## Files to Create/Modify
- `pkg/identity/identity.go` - Identity interfaces
- `internal/identity/user_repo.go` - User repository
- `internal/identity/user_service.go` - User service
- `internal/identity/handler.go` - User handlers
- `internal/di/providers.go` - Add identity providers

59
docs/content/stories/phase2/2.2.1-create-pkgidentityidentitygo-interfaces.md
View File

@@ -1,59 +0,0 @@
# Task 2.2.1: Create `pkg/identity/identity.go` interfaces:
## Metadata
- **Task ID**: 2.2.1
- **Title**: Create `pkg/identity/identity.go` interfaces:
- **Phase**: 2 - Authentication & Authorization
- **Section**: 2.2
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Create `pkg/identity/identity.go` interfaces:
## Requirements
- Create `pkg/identity/identity.go` interfaces:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 2.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
type UserRepository interface {
FindByID(ctx context.Context, id string) (*User, error)
FindByEmail(ctx context.Context, email string) (*User, error)
Create(ctx context.Context, u *User) error
Update(ctx context.Context, u *User) error
Delete(ctx context.Context, id string) error
}
type UserService interface {
Register(ctx context.Context, email, password string) (*User, error)
VerifyEmail(ctx context.Context, token string) error
ResetPassword(ctx context.Context, email string) error
ChangePassword(ctx context.Context, userID, oldPassword, newPassword string) error
}
```

40
docs/content/stories/phase2/2.2.2-implement-internalidentityuser_repogo-using-ent.md
View File

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

40
docs/content/stories/phase2/2.2.3-implement-internalidentityuser_servicego.md
View File

@@ -1,40 +0,0 @@
# Task 2.2.3: Implement `internal/identity/user_service.go`:
## Metadata
- **Task ID**: 2.2.3
- **Title**: Implement `internal/identity/user_service.go`:
- **Phase**: 2 - Authentication & Authorization
- **Section**: 2.2
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Implement `internal/identity/user_service.go`:
## Requirements
- Implement `internal/identity/user_service.go`:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 2.2.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/phase2/2.2.4-add-endpoints.md
View File

@@ -1,40 +0,0 @@
# Task 2.2.4: Add endpoints:
## Metadata
- **Task ID**: 2.2.4
- **Title**: Add endpoints:
- **Phase**: 2 - Authentication & Authorization
- **Section**: 2.2
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Add endpoints:
## Requirements
- Add endpoints:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 2.2.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 ./...
```

70
docs/content/stories/phase2/2.3-rbac-system.md Normal file
View File

@@ -0,0 +1,70 @@
# Story 2.3: Role-Based Access Control (RBAC) System
## Metadata
- **Story ID**: 2.3
- **Title**: Role-Based Access Control (RBAC) System
- **Phase**: 2 - Authentication & Authorization
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 6-8 hours
- **Dependencies**: 1.2, 2.1
## Goal
Implement a complete RBAC system with permissions, role management, and authorization middleware.
## Description
This story implements the complete RBAC system including permission definitions, permission resolution, authorization checking, and middleware for protecting routes.
## Deliverables
### 1. Permission System (`pkg/perm/perm.go`)
- `Permission` type (string format: "module.resource.action")
- Core permission constants (system, user, role permissions)
- Permission validation utilities
### 2. Permission Resolver (`pkg/perm/resolver.go` & `internal/perm/in_memory_resolver.go`)
- `PermissionResolver` interface
- Implementation that loads user roles and permissions from database
- Permission checking with caching
- Permission inheritance via roles
### 3. Authorization System (`pkg/auth/authz.go` & `internal/auth/rbac_authorizer.go`)
- `Authorizer` interface
- RBAC authorizer implementation
- Extract user from context
- Check permissions
- Return authorization errors
### 4. Authorization Middleware
- `RequirePermission(perm Permission) gin.HandlerFunc` decorator
- Integration with route registration
- Proper error responses for unauthorized access
### 5. gRPC Server (Microservices)
- Expose gRPC server for authorization service
- gRPC service definition in `api/proto/authz.proto`
- gRPC server implementation in `internal/auth/grpc/authz_server.go`
- Service registration in service registry
- Uses `IdentityServiceClient` for user operations
## Acceptance Criteria
- [ ] Permissions are defined and can be checked
- [ ] Users inherit permissions through roles
- [ ] Authorization middleware protects routes
- [ ] Unauthorized requests return 403 errors
- [ ] Permission checks are cached for performance
- [ ] Permission system is extensible by modules
## Related ADRs
- [ADR-0019: Permission DSL Format](../../adr/0019-permission-dsl-format.md)
- [ADR-0029: Microservices Architecture](../../adr/0029-microservices-architecture.md)
- [ADR-0030: Service Communication Strategy](../../adr/0030-service-communication-strategy.md)
## Files to Create/Modify
- `pkg/perm/perm.go` - Permission types
- `pkg/perm/resolver.go` - Permission resolver interface
- `internal/perm/in_memory_resolver.go` - Permission resolver implementation
- `pkg/auth/authz.go` - Authorization interface
- `internal/auth/rbac_authorizer.go` - RBAC authorizer
- `internal/auth/middleware.go` - Add authorization middleware

59
docs/content/stories/phase2/2.3.1-create-pkgpermpermgo.md
View File

@@ -1,59 +0,0 @@
# Task 2.3.1: Create `pkg/perm/perm.go`:
## Metadata
- **Task ID**: 2.3.1
- **Title**: Create `pkg/perm/perm.go`:
- **Phase**: 2 - Authentication & Authorization
- **Section**: 2.3
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Create `pkg/perm/perm.go`:
## Requirements
- Create `pkg/perm/perm.go`:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 2.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 Permission string
// Core permissions
var (
SystemHealthCheck Permission = "system.health.check"
UserCreate Permission = "user.create"
UserRead Permission = "user.read"
UserUpdate Permission = "user.update"
UserDelete Permission = "user.delete"
RoleCreate Permission = "role.create"
RoleRead Permission = "role.read"
RoleUpdate Permission = "role.update"
RoleDelete Permission = "role.delete"
)
```

49
docs/content/stories/phase2/2.3.2-create-pkgpermresolvergo-interface.md
View File

@@ -1,49 +0,0 @@
# Task 2.3.2: Create `pkg/perm/resolver.go` interface:
## Metadata
- **Task ID**: 2.3.2
- **Title**: Create `pkg/perm/resolver.go` interface:
- **Phase**: 2 - Authentication & Authorization
- **Section**: 2.3
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Create `pkg/perm/resolver.go` interface:
## Requirements
- Create `pkg/perm/resolver.go` interface:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 2.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 PermissionResolver interface {
HasPermission(ctx context.Context, userID string, perm Permission) (bool, error)
GetUserPermissions(ctx context.Context, userID string) ([]Permission, error)
}
```

40
docs/content/stories/phase2/2.3.3-implement-internalpermin_memory_resolvergo.md
View File

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

48
docs/content/stories/phase2/2.3.4-create-pkgauthauthzgo-interface.md
View File

@@ -1,48 +0,0 @@
# Task 2.3.4: Create `pkg/auth/authz.go` interface:
## Metadata
- **Task ID**: 2.3.4
- **Title**: Create `pkg/auth/authz.go` interface:
- **Phase**: 2 - Authentication & Authorization
- **Section**: 2.3
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Create `pkg/auth/authz.go` interface:
## Requirements
- Create `pkg/auth/authz.go` interface:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 2.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 ./...
```
## Code Reference
```go
type Authorizer interface {
Authorize(ctx context.Context, perm Permission) error
}
```

40
docs/content/stories/phase2/2.3.5-implement-internalauthrbac_authorizergo.md
View File

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

40
docs/content/stories/phase2/2.3.6-create-authorization-middleware.md
View File

@@ -1,40 +0,0 @@
# Task 2.3.6: Create authorization middleware:
## Metadata
- **Task ID**: 2.3.6
- **Title**: Create authorization middleware:
- **Phase**: 2 - Authentication & Authorization
- **Section**: 2.3
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Create authorization middleware:
## Requirements
- Create authorization middleware:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 2.3.6 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 ./...
```

64
docs/content/stories/phase2/2.4-role-management.md Normal file
View File

@@ -0,0 +1,64 @@
# Story 2.4: Role Management API
## Metadata
- **Story ID**: 2.4
- **Title**: Role Management API
- **Phase**: 2 - Authentication & Authorization
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 5-6 hours
- **Dependencies**: 1.2, 2.3
## Goal
Provide complete API for managing roles, assigning permissions to roles, and assigning roles to users.
## Description
This story implements the complete role management API allowing administrators to create, update, and delete roles, assign permissions to roles, and assign roles to users.
## Deliverables
### 1. Role Repository (`internal/identity/role_repo.go`)
- CRUD operations for roles
- Assign permissions to roles (many-to-many)
- Assign roles to users (many-to-many)
- List roles with permissions
- List users with roles
### 2. Role Management API Endpoints
- `POST /api/v1/roles` - Create new role
- `GET /api/v1/roles` - List all roles (with pagination)
- `GET /api/v1/roles/:id` - Get role details with permissions
- `PUT /api/v1/roles/:id` - Update role
- `DELETE /api/v1/roles/:id` - Delete role
- `POST /api/v1/roles/:id/permissions` - Assign permissions to role
- `DELETE /api/v1/roles/:id/permissions/:permId` - Remove permission from role
- `POST /api/v1/users/:id/roles` - Assign roles to user
- `DELETE /api/v1/users/:id/roles/:roleId` - Remove role from user
### 3. Authorization and Validation
- All endpoints protected (admin only)
- Input validation
- Error handling
### 4. gRPC Server (Microservices)
- Expose role management via existing Authz service gRPC server
- Role management methods in `api/proto/authz.proto`
- Service registration in service registry
## Acceptance Criteria
- [ ] Admin users can create and manage roles
- [ ] Permissions can be assigned to roles
- [ ] Roles can be assigned to users
- [ ] Role changes affect user permissions immediately
- [ ] All role operations are audited
- [ ] API endpoints are protected with proper permissions
## Related ADRs
- [ADR-0029: Microservices Architecture](../../adr/0029-microservices-architecture.md)
- [ADR-0030: Service Communication Strategy](../../adr/0030-service-communication-strategy.md)
## Files to Create/Modify
- `internal/identity/role_repo.go` - Role repository
- `internal/identity/role_handler.go` - Role handlers
- `internal/server/routes.go` - Add role routes

40
docs/content/stories/phase2/2.4.1-create-internalidentityrole_repogo.md
View File

@@ -1,40 +0,0 @@
# Task 2.4.1: Create `internal/identity/role_repo.go`:
## Metadata
- **Task ID**: 2.4.1
- **Title**: Create `internal/identity/role_repo.go`:
- **Phase**: 2 - Authentication & Authorization
- **Section**: 2.4
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Create `internal/identity/role_repo.go`:
## Requirements
- Create `internal/identity/role_repo.go`:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 2.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/phase2/2.4.2-add-endpoints.md
View File

@@ -1,40 +0,0 @@
# Task 2.4.2: Add endpoints:
## Metadata
- **Task ID**: 2.4.2
- **Title**: Add endpoints:
- **Phase**: 2 - Authentication & Authorization
- **Section**: 2.4
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: TBD
- **Dependencies**: TBD
## Description
Add endpoints:
## Requirements
- Add endpoints:
## Implementation Steps
1. TODO: Add implementation steps
2. TODO: Add implementation steps
3. TODO: Add implementation steps
## Acceptance Criteria
- [ ] Task 2.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 ./...
```

74
docs/content/stories/phase2/2.5-audit-logging.md Normal file
View File

@@ -0,0 +1,74 @@
# Story 2.5: Audit Logging System
## Metadata
- **Story ID**: 2.5
- **Title**: Audit Logging System
- **Phase**: 2 - Authentication & Authorization
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 5-6 hours
- **Dependencies**: 1.2, 2.1
## Goal
Implement comprehensive audit logging that records all security-sensitive actions for compliance and security monitoring.
## Description
This story implements a complete audit logging system that records all authenticated actions with full context including actor, action, target, and metadata.
## Deliverables
### 1. Audit Interface (`pkg/audit/audit.go`)
- `Auditor` interface with `Record(ctx, action)` method
- `AuditAction` struct with actor, action, target, metadata
### 2. Audit Implementation (`internal/audit/ent_auditor.go`)
- Write audit logs to `audit_log` table
- Capture actor from request context
- Include request metadata (ID, IP, user agent, timestamp)
- Store action details and target information
- Support JSON metadata for flexible logging
### 3. Audit Middleware
- Intercept all authenticated requests
- Record action (HTTP method + path)
- Extract user and request context
- Store audit log entry
### 4. gRPC Server (Microservices)
- Expose gRPC server for audit service
- gRPC service definition in `api/proto/audit.proto`
- gRPC server implementation in `internal/audit/grpc/server.go`
- Service registration in service registry
### 5. Integration
- Integration with authentication endpoints
- Log login attempts (success and failure)
- Log password changes
- Log role assignments and removals
- Log permission changes
- Log user registration
### 5. Audit Log Query API
- `GET /api/v1/audit-logs` - Query audit logs with filters (admin only)
- Support filtering by actor, action, date range
- Pagination support
## Acceptance Criteria
- [ ] All authenticated actions are logged
- [ ] Audit logs include complete context (actor, action, target, metadata)
- [ ] Audit logs are immutable (no updates/deletes)
- [ ] Audit logs can be queried and filtered
- [ ] Audit logging has minimal performance impact
- [ ] Audit logs are stored securely
## Related ADRs
- [ADR-0020: Audit Logging Storage](../../adr/0020-audit-logging-storage.md)
- [ADR-0029: Microservices Architecture](../../adr/0029-microservices-architecture.md)
- [ADR-0030: Service Communication Strategy](../../adr/0030-service-communication-strategy.md)
## Files to Create/Modify
- `pkg/audit/audit.go` - Audit interface
- `internal/audit/ent_auditor.go` - Audit implementation
- `internal/audit/middleware.go` - Audit middleware
- `internal/audit/handler.go` - Audit query handler

Some files were not shown because too many files have changed in this diff Show More