# Epic 1: Core Kernel & Infrastructure

## Overview
Build the core kernel infrastructure (config, logger, DI, health, metrics, observability) with **no business logic**. Implement API Gateway as core infrastructure component. Create service client interfaces and service registry foundation. Establish HTTP/gRPC server foundations that services will use.

**Note:** This epic focuses on infrastructure only. Business services (Auth, Identity, Authz, Audit) are implemented in Epic 2 as separate microservices.

## 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 core kernel infrastructure services only (no business logic) with proper lifecycle management.
- **Deliverables:** Extended DI container, provider functions for core kernel services only, core module export

### 1.2 Database Client Foundation
- [Story: 1.2 - Database Client Foundation](./1.2-database-layer.md)
- **Goal:** Set up database client foundation for services. Each service will have its own database connection and schema.
- **Deliverables:** Database client wrapper with schema support, connection pooling, per-service connection management

**Note:** Core domain entities (User, Role, Permission, AuditLog) are implemented in Epic 2 as part of their respective services.

### 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/gRPC Server Foundation
- [Story: 1.5 - HTTP/gRPC Server Foundation](./1.5-http-server.md)
- **Goal:** Create HTTP and gRPC server foundation that services can use. Each service will have its own server instance.
- **Deliverables:** HTTP server foundation, gRPC server foundation, common middleware, lifecycle management

### 1.6 OpenTelemetry Distributed Tracing
- [Story: 1.6 - OpenTelemetry](./1.6-opentelemetry.md)
- **Goal:** Integrate OpenTelemetry for distributed tracing across all services to enable observability in production.
- **Deliverables:** OpenTelemetry setup, HTTP instrumentation, gRPC instrumentation, database instrumentation, trace-log correlation

### 1.7 Service Client Interfaces
- [Story: 1.7 - Service Client Interfaces](./1.7-service-client-interfaces.md)
- **Goal:** Create service client interfaces for all core services to enable microservices communication.
- **Deliverables:** Service client interfaces in `pkg/services/`, service client factory, gRPC/HTTP client implementations

### 1.8 API Gateway Implementation
- [Story: 1.8 - API Gateway](./1.8-api-gateway.md)
- **Goal:** Implement API Gateway as core infrastructure component that routes all external traffic to backend services.
- **Deliverables:** API Gateway service entry point, gateway implementation with routing, JWT validation, rate limiting, service discovery integration

## Deliverables Checklist
- [x] DI container with core kernel services only (no business logic)
- [x] Database client foundation (per-service connections)
- [x] Health and metrics endpoints functional
- [x] Error bus captures and logs errors
- [x] HTTP/gRPC server foundation for services
- [x] Basic observability with OpenTelemetry
- [x] Service client interfaces defined
- [x] API Gateway service (core infrastructure)
- [x] Basic service registry implementation (Consul)

## Acceptance Criteria
- `GET /healthz` returns 200 for all services
- `GET /ready` checks service health
- `GET /metrics` exposes Prometheus metrics
- Panic recovery logs errors via error bus
- HTTP/gRPC requests are traced with OpenTelemetry
- API Gateway routes requests to backend services
- Service client interfaces are defined
- Services can register with Consul
- No business logic services in Epic 1

## Implementation Summary

- [Implementation Summary and Verification Instructions](./SUMMARY.md) - Complete guide on how to verify all Epic 1 functionality, including database testing and Docker Compose setup