feat: microservice architecture

docs/content/adr/0029-microservices-architecture.md

@@ -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/)
+

docs/content/adr/0030-service-communication-strategy.md

@@ -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
+

docs/content/adr/README.md

@@ -69,6 +69,11 @@ Each ADR follows this structure:
 
 - [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
 
 When making a new architectural decision:

docs/content/architecture-modules.md

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

docs/content/architecture.md

@@ -13,7 +13,12 @@ This document provides a comprehensive overview of the Go Platform 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
 graph TB
@@ -581,10 +586,168 @@ graph TB
     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
 
 - [Module Architecture](./architecture-modules.md) - Detailed module architecture and design
 - [Module Requirements](./module-requirements.md) - Requirements for each module
 - [Component Relationships](./component-relationships.md) - Detailed component interactions
 - [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
 

docs/content/component-relationships.md

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

docs/content/index.md

@@ -58,7 +58,7 @@ Detailed task definitions for each phase are available in the [Stories section](
 ## Key Principles
 
 - **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
 - **Security-by-Design**: Built-in authentication, authorization, and audit capabilities
 - **Observability**: Comprehensive logging, metrics, and tracing

docs/content/stories/STORY_CONSOLIDATION_GUIDE.md

@@ -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
+

docs/content/stories/phase0/0.1-project-initialization.md

@@ -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
+

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

@@ -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
-```
-

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

@@ -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
-```
-

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

@@ -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
-```

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

@@ -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
-```
-

docs/content/stories/phase0/0.1.3-add-gitignore.md

@@ -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
-```
-

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

@@ -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]
-```
-

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

@@ -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]
-```
-

docs/content/stories/phase0/0.2-configuration-management-system.md

@@ -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
+

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

@@ -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
-```
-

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

@@ -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
-```
-

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

@@ -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
-```
-

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

@@ -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
-```
-

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

@@ -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
-```
-

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

@@ -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
-```
-

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

@@ -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'))"
-```
-

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

@@ -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'))"
-```
-

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

@@ -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 ./...
-```
-

docs/content/stories/phase0/0.3-structured-logging-system.md

@@ -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
+

docs/content/stories/phase0/0.3.1-install-gouberorgzap.md

@@ -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)
-

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

@@ -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)
-

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

@@ -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
-  }
-```

docs/content/stories/phase0/0.3.3-implement-internalloggerzap_loggergo.md

@@ -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 ./...
-```
-

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

@@ -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 ./...
-```
-

docs/content/stories/phase0/0.4-cicd-pipeline.md

@@ -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)
+

docs/content/stories/phase0/0.4.1-create-githubworkflowsciyml.md

@@ -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 ./...
-```
-

docs/content/stories/phase0/0.4.2-add-makefile-with-common-commands.md

@@ -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 ./...
-```
-

docs/content/stories/phase0/0.5-di-and-bootstrap.md

@@ -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
+

docs/content/stories/phase0/0.5.1-install-gouberorgfx.md

@@ -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 ./...
-```
-

docs/content/stories/phase0/0.5.2-create-internaldicontainergo.md

@@ -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 ./...
-```
-

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

@@ -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 ./...
-```
-

docs/content/stories/phase0/README.md

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

docs/content/stories/phase1/1.1-enhanced-di-container.md

@@ -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
+

docs/content/stories/phase1/1.1.1-extend-internaldicontainergo.md

@@ -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 ./...
-```
-

docs/content/stories/phase1/1.1.2-create-internaldiprovidersgo.md

@@ -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 ./...
-```
-

docs/content/stories/phase1/1.1.3-add-internaldicore_modulego.md

@@ -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 ./...
-```
-

docs/content/stories/phase1/1.2-database-layer.md

@@ -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
+

docs/content/stories/phase1/1.2.1-install-entgoioentcmdent.md

@@ -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 ./...
-```
-

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

@@ -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
-```

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

@@ -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 ./...
-```
-

docs/content/stories/phase1/1.2.4-generate-ent-code-go-generate-internalent.md

@@ -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 ./...
-```
-

docs/content/stories/phase1/1.2.5-create-internalinfradatabaseclientgo.md

@@ -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 ./...
-```
-

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

@@ -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 ./...
-```
-

docs/content/stories/phase1/1.3-health-metrics-system.md

@@ -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
+

docs/content/stories/phase1/1.3.1-install-githubcomprometheusclient_golangprometheus.md

@@ -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 ./...
-```
-

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

@@ -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 ./...
-```
-

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

@@ -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
-  }
-```

docs/content/stories/phase1/1.3.4-implement-internalhealthregistrygo.md

@@ -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 ./...
-```
-

docs/content/stories/phase1/1.3.5-create-internalmetricsmetricsgo.md

@@ -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 ./...
-```
-

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

@@ -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 ./...
-```
-

docs/content/stories/phase1/1.3.7-register-endpoints-in-main-http-router.md

@@ -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 ./...
-```
-

docs/content/stories/phase1/1.4-error-handling.md

@@ -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
+

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

@@ -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)
-  }
-```

docs/content/stories/phase1/1.4.2-implement-internalerrorbuschannel_busgo.md

@@ -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 ./...
-```
-

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

@@ -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 ./...
-```
-

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

@@ -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 ./...
-```
-

docs/content/stories/phase1/1.5-http-server.md

@@ -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
+

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

@@ -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 ./...
-```
-

docs/content/stories/phase1/1.5.2-create-internalserverservergo.md

@@ -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 ./...
-```
-

docs/content/stories/phase1/1.5.3-wire-http-server-into-fx-lifecycle.md

@@ -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 ./...
-```
-

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

@@ -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 ./...
-```
-

docs/content/stories/phase1/1.6-opentelemetry.md

@@ -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
+

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

@@ -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 ./...
-```
-

docs/content/stories/phase1/1.6.2-create-internalobservabilitytracergo.md

@@ -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 ./...
-```
-

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

@@ -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 ./...
-```
-

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

@@ -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 ./...
-```
-

docs/content/stories/phase1/1.7-service-abstraction-layer.md

@@ -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
+

docs/content/stories/phase1/README.md

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

docs/content/stories/phase2/2.1-jwt-authentication.md

@@ -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
+

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

@@ -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 ./...
-```
-

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

@@ -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
-  }
-```

docs/content/stories/phase2/2.1.3-implement-internalauthjwt_authgo.md

@@ -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 ./...
-```
-

docs/content/stories/phase2/2.1.4-create-internalauthmiddlewarego.md

@@ -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 ./...
-```
-

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

@@ -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 ./...
-```
-

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

@@ -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 ./...
-```
-

docs/content/stories/phase2/2.2-identity-management.md

@@ -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
+

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

@@ -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
-  }
-```

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

@@ -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 ./...
-```
-

docs/content/stories/phase2/2.2.3-implement-internalidentityuser_servicego.md

@@ -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 ./...
-```
-

docs/content/stories/phase2/2.2.4-add-endpoints.md

@@ -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 ./...
-```
-

docs/content/stories/phase2/2.3-rbac-system.md

@@ -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
+

docs/content/stories/phase2/2.3.1-create-pkgpermpermgo.md

@@ -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"
-  )
-```

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

@@ -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)
-  }
-```

docs/content/stories/phase2/2.3.3-implement-internalpermin_memory_resolvergo.md

@@ -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 ./...
-```
-

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

@@ -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
-  }
-```

docs/content/stories/phase2/2.3.5-implement-internalauthrbac_authorizergo.md

@@ -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 ./...
-```
-

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

@@ -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 ./...
-```
-

docs/content/stories/phase2/2.4-role-management.md

@@ -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
+

docs/content/stories/phase2/2.4.1-create-internalidentityrole_repogo.md

@@ -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 ./...
-```
-

docs/content/stories/phase2/2.4.2-add-endpoints.md

@@ -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 ./...
-```
-

docs/content/stories/phase2/2.5-audit-logging.md

@@ -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
+