feat: reword phase to epic, update mkdocs
This commit is contained in:
95
docs/content/stories/epic1/1.1-enhanced-di-container.md
Normal file
95
docs/content/stories/epic1/1.1-enhanced-di-container.md
Normal file
@@ -0,0 +1,95 @@
|
||||
# Story 1.1: Enhanced Dependency Injection Container
|
||||
|
||||
## Metadata
|
||||
- **Story ID**: 1.1
|
||||
- **Title**: Enhanced Dependency Injection Container
|
||||
- **Epic**: 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
|
||||
|
||||
144
docs/content/stories/epic1/1.2-database-layer.md
Normal file
144
docs/content/stories/epic1/1.2-database-layer.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# Story 1.2: Database Layer with Ent ORM
|
||||
|
||||
## Metadata
|
||||
- **Story ID**: 1.2
|
||||
- **Title**: Database Layer with Ent ORM
|
||||
- **Epic**: 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 epics
|
||||
|
||||
## 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
|
||||
|
||||
126
docs/content/stories/epic1/1.3-health-metrics-system.md
Normal file
126
docs/content/stories/epic1/1.3-health-metrics-system.md
Normal file
@@ -0,0 +1,126 @@
|
||||
# Story 1.3: Health Monitoring and Metrics System
|
||||
|
||||
## Metadata
|
||||
- **Story ID**: 1.3
|
||||
- **Title**: Health Monitoring and Metrics System
|
||||
- **Epic**: 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
|
||||
|
||||
103
docs/content/stories/epic1/1.4-error-handling.md
Normal file
103
docs/content/stories/epic1/1.4-error-handling.md
Normal file
@@ -0,0 +1,103 @@
|
||||
# Story 1.4: Error Handling and Error Bus
|
||||
|
||||
## Metadata
|
||||
- **Story ID**: 1.4
|
||||
- **Title**: Error Handling and Error Bus
|
||||
- **Epic**: 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 (Epic 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 Epic 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
|
||||
|
||||
122
docs/content/stories/epic1/1.5-http-server.md
Normal file
122
docs/content/stories/epic1/1.5-http-server.md
Normal file
@@ -0,0 +1,122 @@
|
||||
# Story 1.5: HTTP Server Foundation with Middleware Stack
|
||||
|
||||
## Metadata
|
||||
- **Story ID**: 1.5
|
||||
- **Title**: HTTP Server Foundation with Middleware Stack
|
||||
- **Epic**: 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 (Epic 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
|
||||
|
||||
117
docs/content/stories/epic1/1.6-opentelemetry.md
Normal file
117
docs/content/stories/epic1/1.6-opentelemetry.md
Normal file
@@ -0,0 +1,117 @@
|
||||
# Story 1.6: OpenTelemetry Distributed Tracing
|
||||
|
||||
## Metadata
|
||||
- **Story ID**: 1.6
|
||||
- **Title**: OpenTelemetry Distributed Tracing
|
||||
- **Epic**: 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
|
||||
|
||||
114
docs/content/stories/epic1/1.7-service-abstraction-layer.md
Normal file
114
docs/content/stories/epic1/1.7-service-abstraction-layer.md
Normal file
@@ -0,0 +1,114 @@
|
||||
# Story 1.7: Service Client Interfaces
|
||||
|
||||
## Metadata
|
||||
- **Story ID**: 1.7
|
||||
- **Title**: Service Client Interfaces
|
||||
- **Epic**: 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 Epic 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
|
||||
|
||||
58
docs/content/stories/epic1/README.md
Normal file
58
docs/content/stories/epic1/README.md
Normal file
@@ -0,0 +1,58 @@
|
||||
# Epic 1: Core Kernel & Infrastructure
|
||||
|
||||
## Overview
|
||||
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.
|
||||
|
||||
## Stories
|
||||
|
||||
### 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 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 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 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 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 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
|
||||
- [ ] Database client with Ent schema
|
||||
- [ ] Health and metrics endpoints functional
|
||||
- [ ] Error bus captures and logs errors
|
||||
- [ ] HTTP server with middleware stack
|
||||
- [ ] Basic observability with OpenTelemetry
|
||||
- [ ] Service client interfaces for microservices
|
||||
|
||||
## Acceptance Criteria
|
||||
- `GET /healthz` returns 200
|
||||
- `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
|
||||
Reference in New Issue
Block a user