Merge pull request 'feature/microservice-architecture' (#5) from feature/microservice-architecture into main

Reviewed-on: #5

.github/workflows/ci.yml

@@ -17,7 +17,7 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@v5
         with:
-          go-version: '1.24'
+          go-version: '1.25.3'
 
       - name: Cache Go modules
         uses: actions/cache@v4
@@ -76,15 +76,13 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@v5
         with:
-          go-version: '1.24'
+          go-version: '1.25.3'
 
-      - name: Install golangci-lint v2.1.6
+      - name: golangci-lint
-        run: |
+        uses: golangci/golangci-lint-action@v7
-          curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v2.1.6
+        with:
-          echo "$(go env GOPATH)/bin" >> $GITHUB_PATH
+          version: latest
-
+          args: --timeout=5m
-      - name: Run golangci-lint
-        run: golangci-lint run --timeout=5m
 
   build:
     name: Build
@@ -96,7 +94,7 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@v5
         with:
-          go-version: '1.24'
+          go-version: '1.25.3'
 
       - name: Cache Go modules
         uses: actions/cache@v4
@@ -110,13 +108,17 @@ jobs:
         run: go mod download
 
       - name: Build
-        run: go build -v -o bin/platform ./cmd/platform
+        run: |
+          go build -v -o bin/platform ./cmd/platform
+          go build -v -o bin/api-gateway ./cmd/api-gateway
 
       - name: Upload build artifacts
         uses: actions/upload-artifact@v3
         with:
-          name: platform-binary
+          name: binaries
-          path: bin/platform
+          path: |
+            bin/platform
+            bin/api-gateway
           retention-days: 7
 
   fmt:
@@ -129,7 +131,7 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@v5
         with:
-          go-version: '1.24'
+          go-version: '1.25.3'
 
       - name: Check formatting
         run: |

.gitignore

@@ -7,6 +7,7 @@
 bin/
 dist/
 platform
+api-gateway
 
 # Test binary, built with `go test -c`
 *.test

.golangci.yml

@@ -1,7 +1,7 @@
 # golangci-lint configuration
 # See https://golangci-lint.run/usage/configuration/
 
-version: 2
+version: "2"
 
 run:
   timeout: 5m
@@ -17,23 +17,8 @@ linters:
   disable:
     - gocritic  # Can be enabled later for stricter checks
 
-linters-settings:
-  gosec:
-    severity: medium
-  errcheck:
-    check-blank: true
-
 issues:
-  exclude-use-default: false
   max-issues-per-linter: 0
   max-same-issues: 0
-  exclude-rules:
+  # Note: exclusion rules moved in v2 config; keep minimal allowed keys
-    # Exclude test files from some checks
-    - path: _test\.go
-      linters:
-        - errcheck
-        - gosec
 
-output:
-  print-issued-lines: true
-  print-linter-name: true

Makefile

@@ -18,7 +18,7 @@ help:
 	@echo "  make lint          - Run linters"
 	@echo "  make fmt           - Format code"
 	@echo "  make fmt-check     - Check code formatting"
-	@echo "  make build         - Build platform binary"
+	@echo "  make build         - Build platform and api-gateway binaries"
 	@echo "  make clean         - Clean build artifacts"
 	@echo "  make docker-build  - Build Docker image"
 	@echo "  make docker-run    - Run Docker container"
@@ -85,9 +85,10 @@ fmt-check:
 	@echo "Code is properly formatted"
 
 build:
-	@echo "Building platform binary..."
+	@echo "Building platform and api-gateway binaries..."
-	$(GO) build -v -o $(BINARY_PATH) ./cmd/platform
+	$(GO) build -v -o bin/platform ./cmd/platform
-	@echo "Build complete: $(BINARY_PATH)"
+	$(GO) build -v -o bin/api-gateway ./cmd/api-gateway
+	@echo "Build complete: bin/platform, bin/api-gateway"
 
 clean:
 	@echo "Cleaning build artifacts..."
@@ -110,6 +111,27 @@ generate:
 	@echo "Running code generation..."
 	$(GO) generate ./...
 
+generate-proto:
+	@echo "Generating gRPC code from proto files..."
+	@if ! command -v protoc > /dev/null; then \
+		echo "protoc not found. Install Protocol Buffers compiler."; \
+		exit 1; \
+	fi
+	@if ! command -v protoc-gen-go > /dev/null; then \
+		echo "protoc-gen-go not found. Install with: go install google.golang.org/protobuf/cmd/protoc-gen-go@latest"; \
+		exit 1; \
+	fi
+	@if ! command -v protoc-gen-go-grpc > /dev/null; then \
+		echo "protoc-gen-go-grpc not found. Install with: go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest"; \
+		exit 1; \
+	fi
+	@mkdir -p api/proto/generated
+	@protoc --go_out=api/proto/generated --go_opt=paths=source_relative \
+		--go-grpc_out=api/proto/generated --go-grpc_opt=paths=source_relative \
+		--proto_path=api/proto \
+		api/proto/*.proto
+	@echo "gRPC code generation complete"
+
 verify: fmt-check lint test
 	@echo "Verification complete"
 

api/proto/audit.proto

@@ -0,0 +1,56 @@
+syntax = "proto3";
+
+package audit.v1;
+
+option go_package = "git.dcentral.systems/toolz/goplt/api/proto/generated/audit/v1;auditv1";
+
+// AuditService provides audit logging operations.
+service AuditService {
+  // Record records an audit log entry.
+  rpc Record(RecordRequest) returns (RecordResponse);
+  
+  // Query queries audit logs based on filters.
+  rpc Query(QueryRequest) returns (QueryResponse);
+}
+
+// AuditLogEntry represents an audit log entry.
+message AuditLogEntry {
+  string user_id = 1;
+  string action = 2; // e.g., "user.create", "user.update"
+  string resource = 3; // e.g., "user", "role"
+  string resource_id = 4;
+  string ip_address = 5;
+  string user_agent = 6;
+  map<string, string> metadata = 7;
+  int64 timestamp = 8;
+}
+
+// RecordRequest contains an audit log entry to record.
+message RecordRequest {
+  AuditLogEntry entry = 1;
+}
+
+// RecordResponse indicates success.
+message RecordResponse {
+  bool success = 1;
+  string id = 2; // Audit log entry ID
+}
+
+// QueryRequest contains filters for querying audit logs.
+message QueryRequest {
+  optional string user_id = 1;
+  optional string action = 2;
+  optional string resource = 3;
+  optional string resource_id = 4;
+  optional int64 start_time = 5;
+  optional int64 end_time = 6;
+  int32 limit = 7; // Max number of results
+  int32 offset = 8; // Pagination offset
+}
+
+// QueryResponse contains audit log entries.
+message QueryResponse {
+  repeated AuditLogEntry entries = 1;
+  int32 total = 2; // Total number of matching entries
+}
+

api/proto/auth.proto

@@ -0,0 +1,71 @@
+syntax = "proto3";
+
+package auth.v1;
+
+option go_package = "git.dcentral.systems/toolz/goplt/api/proto/generated/auth/v1;authv1";
+
+// AuthService provides authentication operations.
+service AuthService {
+  // Login authenticates a user and returns access and refresh tokens.
+  rpc Login(LoginRequest) returns (LoginResponse);
+  
+  // RefreshToken refreshes an access token using a refresh token.
+  rpc RefreshToken(RefreshTokenRequest) returns (RefreshTokenResponse);
+  
+  // ValidateToken validates a JWT token and returns the token claims.
+  rpc ValidateToken(ValidateTokenRequest) returns (ValidateTokenResponse);
+  
+  // Logout invalidates a refresh token.
+  rpc Logout(LogoutRequest) returns (LogoutResponse);
+}
+
+// LoginRequest contains login credentials.
+message LoginRequest {
+  string email = 1;
+  string password = 2;
+}
+
+// LoginResponse contains authentication tokens.
+message LoginResponse {
+  string access_token = 1;
+  string refresh_token = 2;
+  int64 expires_in = 3; // seconds
+  string token_type = 4; // "Bearer"
+}
+
+// RefreshTokenRequest contains a refresh token.
+message RefreshTokenRequest {
+  string refresh_token = 1;
+}
+
+// RefreshTokenResponse contains new authentication tokens.
+message RefreshTokenResponse {
+  string access_token = 1;
+  string refresh_token = 2;
+  int64 expires_in = 3; // seconds
+  string token_type = 4; // "Bearer"
+}
+
+// ValidateTokenRequest contains a JWT token to validate.
+message ValidateTokenRequest {
+  string token = 1;
+}
+
+// ValidateTokenResponse contains token claims.
+message ValidateTokenResponse {
+  string user_id = 1;
+  string email = 2;
+  repeated string roles = 3;
+  int64 expires_at = 4;
+}
+
+// LogoutRequest contains a refresh token to invalidate.
+message LogoutRequest {
+  string refresh_token = 1;
+}
+
+// LogoutResponse indicates success.
+message LogoutResponse {
+  bool success = 1;
+}
+

api/proto/authz.proto

@@ -0,0 +1,80 @@
+syntax = "proto3";
+
+package authz.v1;
+
+option go_package = "git.dcentral.systems/toolz/goplt/api/proto/generated/authz/v1;authzv1";
+
+// AuthzService provides authorization operations.
+service AuthzService {
+  // Authorize checks if a user has a specific permission and returns an error if not.
+  rpc Authorize(AuthorizeRequest) returns (AuthorizeResponse);
+  
+  // HasPermission checks if a user has a specific permission.
+  rpc HasPermission(HasPermissionRequest) returns (HasPermissionResponse);
+  
+  // GetUserPermissions returns all permissions for a user.
+  rpc GetUserPermissions(GetUserPermissionsRequest) returns (GetUserPermissionsResponse);
+  
+  // GetUserRoles returns all roles for a user.
+  rpc GetUserRoles(GetUserRolesRequest) returns (GetUserRolesResponse);
+}
+
+// Permission represents a permission in the system.
+message Permission {
+  string id = 1;
+  string code = 2;
+  string name = 3;
+  string description = 4;
+}
+
+// Role represents a role in the system.
+message Role {
+  string id = 1;
+  string name = 2;
+  string description = 3;
+  repeated string permissions = 4; // Permission codes
+}
+
+// AuthorizeRequest contains user ID and permission to check.
+message AuthorizeRequest {
+  string user_id = 1;
+  string permission = 2;
+}
+
+// AuthorizeResponse indicates authorization result.
+message AuthorizeResponse {
+  bool authorized = 1;
+  string message = 2;
+}
+
+// HasPermissionRequest contains user ID and permission to check.
+message HasPermissionRequest {
+  string user_id = 1;
+  string permission = 2;
+}
+
+// HasPermissionResponse indicates if the user has the permission.
+message HasPermissionResponse {
+  bool has_permission = 1;
+}
+
+// GetUserPermissionsRequest contains a user ID.
+message GetUserPermissionsRequest {
+  string user_id = 1;
+}
+
+// GetUserPermissionsResponse contains all permissions for the user.
+message GetUserPermissionsResponse {
+  repeated Permission permissions = 1;
+}
+
+// GetUserRolesRequest contains a user ID.
+message GetUserRolesRequest {
+  string user_id = 1;
+}
+
+// GetUserRolesResponse contains all roles for the user.
+message GetUserRolesResponse {
+  repeated Role roles = 1;
+}
+

api/proto/identity.proto

@@ -0,0 +1,134 @@
+syntax = "proto3";
+
+package identity.v1;
+
+option go_package = "git.dcentral.systems/toolz/goplt/api/proto/generated/identity/v1;identityv1";
+
+// IdentityService provides user management operations.
+service IdentityService {
+  // GetUser retrieves a user by ID.
+  rpc GetUser(GetUserRequest) returns (GetUserResponse);
+  
+  // GetUserByEmail retrieves a user by email address.
+  rpc GetUserByEmail(GetUserByEmailRequest) returns (GetUserByEmailResponse);
+  
+  // CreateUser creates a new user.
+  rpc CreateUser(CreateUserRequest) returns (CreateUserResponse);
+  
+  // UpdateUser updates an existing user.
+  rpc UpdateUser(UpdateUserRequest) returns (UpdateUserResponse);
+  
+  // DeleteUser deletes a user.
+  rpc DeleteUser(DeleteUserRequest) returns (DeleteUserResponse);
+  
+  // VerifyEmail verifies a user's email address using a verification token.
+  rpc VerifyEmail(VerifyEmailRequest) returns (VerifyEmailResponse);
+  
+  // RequestPasswordReset requests a password reset token.
+  rpc RequestPasswordReset(RequestPasswordResetRequest) returns (RequestPasswordResetResponse);
+  
+  // ResetPassword resets a user's password using a reset token.
+  rpc ResetPassword(ResetPasswordRequest) returns (ResetPasswordResponse);
+}
+
+// User represents a user in the system.
+message User {
+  string id = 1;
+  string email = 2;
+  string username = 3;
+  string first_name = 4;
+  string last_name = 5;
+  bool email_verified = 6;
+  int64 created_at = 7;
+  int64 updated_at = 8;
+}
+
+// GetUserRequest contains a user ID.
+message GetUserRequest {
+  string id = 1;
+}
+
+// GetUserResponse contains a user.
+message GetUserResponse {
+  User user = 1;
+}
+
+// GetUserByEmailRequest contains an email address.
+message GetUserByEmailRequest {
+  string email = 1;
+}
+
+// GetUserByEmailResponse contains a user.
+message GetUserByEmailResponse {
+  User user = 1;
+}
+
+// CreateUserRequest contains user data for creation.
+message CreateUserRequest {
+  string email = 1;
+  string username = 2;
+  string password = 3;
+  string first_name = 4;
+  string last_name = 5;
+}
+
+// CreateUserResponse contains the created user.
+message CreateUserResponse {
+  User user = 1;
+}
+
+// UpdateUserRequest contains user data for update.
+message UpdateUserRequest {
+  string id = 1;
+  optional string email = 2;
+  optional string username = 3;
+  optional string first_name = 4;
+  optional string last_name = 5;
+}
+
+// UpdateUserResponse contains the updated user.
+message UpdateUserResponse {
+  User user = 1;
+}
+
+// DeleteUserRequest contains a user ID.
+message DeleteUserRequest {
+  string id = 1;
+}
+
+// DeleteUserResponse indicates success.
+message DeleteUserResponse {
+  bool success = 1;
+}
+
+// VerifyEmailRequest contains a verification token.
+message VerifyEmailRequest {
+  string token = 1;
+}
+
+// VerifyEmailResponse indicates success.
+message VerifyEmailResponse {
+  bool success = 1;
+}
+
+// RequestPasswordResetRequest contains an email address.
+message RequestPasswordResetRequest {
+  string email = 1;
+}
+
+// RequestPasswordResetResponse indicates success.
+message RequestPasswordResetResponse {
+  bool success = 1;
+}
+
+// ResetPasswordRequest contains a reset token and new password.
+message ResetPasswordRequest {
+  string token = 1;
+  string new_password = 2;
+}
+
+// ResetPasswordResponse indicates success.
+message ResetPasswordResponse {
+  bool success = 1;
+}
+

cmd/api-gateway/main.go

@@ -0,0 +1,156 @@
+// Package main provides the API Gateway service entry point.
+package main
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"os"
+	"time"
+
+	"git.dcentral.systems/toolz/goplt/internal/client"
+	"git.dcentral.systems/toolz/goplt/internal/di"
+	"git.dcentral.systems/toolz/goplt/internal/health"
+	"git.dcentral.systems/toolz/goplt/internal/metrics"
+	"git.dcentral.systems/toolz/goplt/internal/server"
+	"git.dcentral.systems/toolz/goplt/pkg/config"
+	"git.dcentral.systems/toolz/goplt/pkg/errorbus"
+	"git.dcentral.systems/toolz/goplt/pkg/logger"
+	"git.dcentral.systems/toolz/goplt/pkg/registry"
+	"git.dcentral.systems/toolz/goplt/services/gateway"
+	"go.opentelemetry.io/otel/trace"
+	"go.uber.org/fx"
+)
+
+func main() {
+	// Create DI container with core kernel services
+	container := di.NewContainer(
+		// Invoke lifecycle hooks
+		fx.Invoke(di.RegisterLifecycleHooks),
+		// Create API Gateway
+		fx.Invoke(func(
+			cfg config.ConfigProvider,
+			log logger.Logger,
+			healthRegistry *health.Registry,
+			metricsRegistry *metrics.Metrics,
+			errorBus errorbus.ErrorPublisher,
+			tracer trace.TracerProvider,
+			serviceRegistry registry.ServiceRegistry,
+			clientFactory *client.ServiceClientFactory,
+			lc fx.Lifecycle,
+		) {
+			// Create HTTP server using server foundation
+			srv, err := server.NewServer(cfg, log, healthRegistry, metricsRegistry, errorBus, tracer)
+			if err != nil {
+				log.Error("Failed to create API Gateway server",
+					logger.Error(err),
+				)
+				os.Exit(1)
+			}
+
+			// Setup gateway routes
+			gateway, err := gateway.NewGateway(cfg, log, clientFactory, serviceRegistry)
+			if err != nil {
+				log.Error("Failed to create API Gateway",
+					logger.Error(err),
+				)
+				os.Exit(1)
+			}
+			gateway.SetupRoutes(srv.Router())
+
+			// Register with Consul
+			gatewayPort := cfg.GetInt("gateway.port")
+			if gatewayPort == 0 {
+				gatewayPort = 8080
+			}
+			gatewayHost := cfg.GetString("gateway.host")
+			if gatewayHost == "" {
+				gatewayHost = "localhost"
+			}
+
+			serviceInstance := &registry.ServiceInstance{
+				ID:      fmt.Sprintf("api-gateway-%d", os.Getpid()),
+				Name:    "api-gateway",
+				Address: gatewayHost,
+				Port:    gatewayPort,
+				Tags:    []string{"gateway", "http"},
+				Metadata: map[string]string{
+					"version": "1.0.0",
+				},
+			}
+
+			// Register lifecycle hooks
+			lc.Append(fx.Hook{
+				OnStart: func(ctx context.Context) error {
+					// Register with service registry
+					if err := serviceRegistry.Register(ctx, serviceInstance); err != nil {
+						log.Warn("Failed to register API Gateway with service registry",
+							logger.Error(err),
+						)
+						// Continue anyway - gateway can work without registry
+					} else {
+						log.Info("API Gateway registered with service registry",
+							logger.String("service_id", serviceInstance.ID),
+						)
+					}
+
+					// Start HTTP server
+					addr := fmt.Sprintf("%s:%d", cfg.GetString("server.host"), gatewayPort)
+					log.Info("API Gateway starting",
+						logger.String("addr", addr),
+					)
+
+					errChan := make(chan error, 1)
+					go func() {
+						if err := srv.Start(); err != nil && err != http.ErrServerClosed {
+							log.Error("API Gateway server failed",
+								logger.String("error", err.Error()),
+							)
+							errChan <- err
+						}
+					}()
+
+					// Wait a short time to detect immediate binding errors
+					select {
+					case err := <-errChan:
+						return fmt.Errorf("API Gateway failed to start: %w", err)
+					case <-time.After(500 * time.Millisecond):
+						log.Info("API Gateway started successfully",
+							logger.String("addr", addr),
+						)
+						return nil
+					}
+				},
+				OnStop: func(ctx context.Context) error {
+					// Deregister from service registry
+					if err := serviceRegistry.Deregister(ctx, serviceInstance.ID); err != nil {
+						log.Warn("Failed to deregister API Gateway from service registry",
+							logger.Error(err),
+						)
+					} else {
+						log.Info("API Gateway deregistered from service registry")
+					}
+
+					// Shutdown HTTP server
+					return srv.Shutdown(ctx)
+				},
+			})
+		}),
+	)
+
+	// Create root context
+	ctx := context.Background()
+
+	// Start the application
+	if err := container.Start(ctx); err != nil {
+		log := logger.GetGlobalLogger()
+		if log != nil {
+			log.Error("Failed to start API Gateway",
+				logger.Error(err),
+			)
+		} else {
+			fmt.Fprintf(os.Stderr, "Failed to start API Gateway: %v\n", err)
+		}
+		os.Exit(1)
+	}
+}

cmd/platform/main.go

@@ -7,23 +7,28 @@ import (
 	"os"
 
 	"git.dcentral.systems/toolz/goplt/internal/di"
-	"git.dcentral.systems/toolz/goplt/internal/infra/database"
+	"git.dcentral.systems/toolz/goplt/internal/health"
-	"git.dcentral.systems/toolz/goplt/internal/server"
+	"git.dcentral.systems/toolz/goplt/internal/metrics"
+	"git.dcentral.systems/toolz/goplt/pkg/config"
 	"git.dcentral.systems/toolz/goplt/pkg/logger"
 	"go.uber.org/fx"
 )
 
 func main() {
 	// Create DI container with lifecycle hooks
-	// We need to invoke the HTTP server to ensure all providers execute
+	// This is a minimal entry point for testing core kernel infrastructure
+	// Services will have their own entry points (cmd/{service}/main.go)
 	container := di.NewContainer(
 		// Invoke lifecycle hooks
 		fx.Invoke(di.RegisterLifecycleHooks),
-		// Force HTTP server to be created (which triggers all dependencies)
+		// Verify core kernel services are available
-		// This ensures database, health, metrics, etc. are all created
+		fx.Invoke(func(
-		fx.Invoke(func(_ *server.Server, _ *database.Client) {
+			_ config.ConfigProvider,
-			// Both server and database are created, hooks are registered
+			_ logger.Logger,
-			// This ensures all providers execute
+			_ *health.Registry,
+			_ *metrics.Metrics,
+		) {
+			// Core kernel services are available
 		}),
 	)
 

config/default.yaml

@@ -24,3 +24,30 @@ tracing:
   service_name: "platform"
   service_version: "1.0.0"
   otlp_endpoint: ""
+
+registry:
+  type: consul
+  consul:
+    address: "localhost:8500"
+    datacenter: "dc1"
+    scheme: "http"
+    health_check:
+      interval: "10s"
+      timeout: "3s"
+      deregister_after: "30s"
+      http: "/healthz"
+
+gateway:
+  port: 8080
+  host: "0.0.0.0"
+  routes:
+    - path: "/api/v1/auth/**"
+      service: "auth-service"
+      auth_required: false
+    - path: "/api/v1/users/**"
+      service: "identity-service"
+      auth_required: true
+  cors:
+    allowed_origins: ["*"]
+    allowed_methods: ["GET", "POST", "PUT", "DELETE", "PATCH"]
+    allowed_headers: ["Authorization", "Content-Type"]

docs/content/adr/0002-go-version.md

@@ -1,10 +1,11 @@
 # ADR-0002: Go Version
 
 ## Status
-Accepted
+Superseded by [ADR-0034: Go Version Upgrade to 1.25.3](./0034-go-version-upgrade.md)
 
 ## Context
 Go releases new versions regularly with new features, performance improvements, and security fixes. We need to choose a Go version that:
+
 - Provides necessary features for the platform
 - Has good ecosystem support
 - Is stable and production-ready

docs/content/adr/0013-database-orm.md

@@ -4,13 +4,15 @@
 Accepted
 
 ## Context
-The platform needs a database ORM/library that:
+The platform follows a microservices architecture where each service has its own database connection. The ORM/library must:
-- Supports PostgreSQL (primary database)
+
-- Provides type-safe query building
+- Support PostgreSQL (primary database)
-- Supports code generation (reduces boilerplate)
+- Provide type-safe query building
-- Handles migrations
+- Support code generation (reduces boilerplate)
-- Supports relationships (many-to-many, etc.)
+- Handle migrations per service
-- Integrates with Ent (code generation)
+- Support relationships (many-to-many, etc.)
+- Integrate with Ent (code generation)
+- Support schema isolation (each service owns its schema)
 
 Options considered:
 1. **entgo.io/ent** - Code-generated, type-safe ORM
@@ -45,10 +47,18 @@ Use **entgo.io/ent** as the primary ORM for the platform.
 - Less flexible than raw SQL for complex queries
 - Generated code must be committed or verified in CI
 
+### Database Access Pattern
+- **Each service has its own database connection pool**: Services do not share database connections
+- **Schema isolation**: Each service owns its database schema (e.g., `auth_schema`, `identity_schema`, `blog_schema`)
+- **No cross-service database access**: Services communicate via APIs, not direct database queries
+- **Shared database instance**: Services share the same PostgreSQL instance but use different schemas
+- **Alternative**: Database-per-service pattern (each service has its own database) for maximum isolation
+
 ### Implementation Notes
 - Install: `go get entgo.io/ent/cmd/ent`
-- Initialize schema: `go run entgo.io/ent/cmd/ent init User Role Permission`
+- Each service initializes its own schema: `go run entgo.io/ent/cmd/ent init User Role Permission` (Identity Service)
-- Use `//go:generate` directives for code generation
+- Use `//go:generate` directives for code generation per service
-- Run migrations on startup via `client.Schema.Create()`
+- Run migrations on startup via `client.Schema.Create()` for each service
-- Create wrapper in `internal/infra/database/client.go` for DI injection
+- Create database client wrapper per service in `services/{service}/internal/database/client.go`
+- Each service manages its own connection pool configuration
 

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

@@ -9,31 +9,50 @@ The platform needs to scale independently, support team autonomy, and enable fle
 ## Decision
 Design the platform as **microservices architecture from day one**:
 
-1. **Service-Based Architecture**: All modules are independent services:
+1. **Core Services**: Core business services are separate microservices:
-   - Each module is a separate service with its own process
+
+   - **Auth Service** (`cmd/auth-service/`): JWT token generation/validation
+   - **Identity Service** (`cmd/identity-service/`): User CRUD, password management
+   - **Authz Service** (`cmd/authz-service/`): Permission resolution, authorization
+   - **Audit Service** (`cmd/audit-service/`): Audit logging
+   - Each service has its own process, database connection, and deployment
+
+2. **API Gateway**: Core infrastructure component (implemented in Epic 1):
+   - Single entry point for all external traffic
+   - Routes requests to backend services via service discovery
+   - Handles authentication, rate limiting, CORS at the edge
+   - Not optional - required for microservices architecture
+
+3. **Service-Based Architecture**: All modules are independent services:
+   - Each module/service 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:
+4. **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**:
+5. **Communication Patterns**:
    - **Synchronous**: gRPC service calls (primary), HTTP/REST (fallback)
    - **Asynchronous**: Event bus via Kafka
-   - **Shared State**: Cache (Redis) and Database (PostgreSQL)
+   - **Shared Infrastructure**: Cache (Redis) and Database (PostgreSQL instance)
+   - **Database Access**: Each service has its own connection pool and schema
 
-4. **Service Boundaries**: Each module is an independent service:
+6. **Service Boundaries**: Each service is independent:
    - Independent Go modules (`go.mod`)
-   - Own database schema (via Ent)
+   - Own database schema (via Ent) - schema isolation
-   - Own API routes
+   - Own API routes (gRPC/HTTP)
    - 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)
+7. **Development Mode**: For local development, services run in the same repository:
+   - Each service has its own entry point and process
+   - Services still communicate via service clients (gRPC/HTTP)
+   - No direct in-process calls
+   - Docker Compose for easy local setup
 
 ## Consequences
 
@@ -55,29 +74,36 @@ Design the platform as **microservices architecture from day one**:
 - **Development Setup**: More complex local development (multiple services)
 
 ### Mitigations
-- **Service Mesh**: Use service mesh (Istio, Linkerd) for advanced microservices features
+- **API Gateway**: Implemented in Epic 1 as core infrastructure - handles routing, authentication, rate limiting
-- **API Gateway**: Central gateway for routing and cross-cutting concerns
+- **Service Mesh**: Use service mesh (Istio, Linkerd) for advanced microservices features (optional)
 - **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)
+- **Service Clients**: All inter-service communication via service clients (gRPC/HTTP)
 
 ## Implementation Strategy
 
-### Epic 1: Service Client Interfaces (Epic 1)
+### Epic 1: Core Kernel & Infrastructure
-- Define service client interfaces for all core services
+- Core kernel (infrastructure only): config, logger, DI, health, metrics, observability
-- All inter-service communication goes through interfaces
+- API Gateway implementation (core infrastructure component)
+- Service client interfaces for all core services
+- Service registry interface and basic implementation
 
-### Epic 2: Service Registry (Epic 3)
+### Epic 2: Core Services Separation
-- Create service registry interface
+- Separate Auth, Identity, Authz, Audit into independent services
-- Implement service discovery
+- Each service: own entry point (`cmd/{service}/`), gRPC server, database connection
-- Support for Consul, Kubernetes service discovery
+- Service client implementations (gRPC/HTTP)
+- Service registration with registry
 
-### Epic 3: gRPC Services (Epic 5)
+### Epic 3: Service Registry & Discovery (Epic 3)
-- Implement gRPC service definitions
+- Complete service registry implementation
-- Create gRPC servers for all services
+- Service discovery (Consul, Kubernetes)
-- Create gRPC clients for service communication
+- Service health checking and deregistration
+
+### Epic 5: gRPC Services (Epic 5)
+- Complete gRPC service definitions for all services
+- gRPC clients for service communication
 - HTTP clients as fallback option
 
 ## References

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

@@ -7,22 +7,30 @@ Accepted
 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**:
+Use a **service client-based communication strategy** with API Gateway as the entry point:
 
-1. **Service Client Interfaces** (Primary for synchronous calls):
+1. **API Gateway** (Entry Point):
+   - All external traffic enters through API Gateway
+   - Gateway routes requests to backend services via service discovery
+   - Gateway handles authentication (JWT validation via Auth Service)
+   - Gateway handles rate limiting, CORS, request transformation
+
+2. **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)
+   - Gateway uses service clients to communicate with backend services
+   - Services use service clients for inter-service communication
 
-2. **Event Bus** (Primary for asynchronous communication):
+3. **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):
+4. **Shared Infrastructure** (For state):
    - Redis for cache and distributed state
-   - PostgreSQL for persistent data
+   - PostgreSQL instance for persistent data (each service has its own schema)
    - Kafka for events
 
 ## Service Client Pattern
@@ -47,8 +55,22 @@ type httpIdentityClient struct {
 }
 ```
 
+## Communication Flow
+
+```
+Client → API Gateway → Backend Service (via service client)
+Backend Service → Other Service (via service client)
+```
+
+All communication goes through service clients - no direct in-process calls even in development mode.
+
 ## 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.
+For local development, services run in the same repository but as separate processes:
+
+- Each service has its own entry point (`cmd/{service}/`)
+- Services communicate via service clients (gRPC or HTTP) - no direct in-process calls
+- Docker Compose orchestrates all services
+- This ensures the architecture is consistent with production
 
 ## Consequences
 

docs/content/adr/0031-service-repository-structure.md

@@ -10,6 +10,7 @@ The platform follows a microservices architecture where each service (Auth, Iden
 - **Option 2**: Separate repositories (each service in its own repository)
 
 The decision affects:
+
 - Code sharing and dependencies
 - Development workflow
 - CI/CD complexity
@@ -30,12 +31,13 @@ Use a **monorepo structure with service directories** for all services:
    ```
    goplt/
    ├── cmd/
-   │   ├── platform/          # Core kernel entry point
+   │   ├── platform/          # Core kernel entry point (minimal, infrastructure only)
-   │   ├── auth-service/      # Auth Service entry point
+   │   ├── api-gateway/        # API Gateway service entry point
-   │   ├── identity-service/  # Identity Service entry point
+   │   ├── auth-service/       # Auth Service entry point
-   │   ├── authz-service/     # Authz Service entry point
+   │   ├── identity-service/   # Identity Service entry point
-   │   ├── audit-service/     # Audit Service entry point
+   │   ├── authz-service/      # Authz Service entry point
-   │   └── blog-service/      # Blog module service entry point
+   │   ├── audit-service/      # Audit Service entry point
+   │   └── blog-service/       # Blog feature service entry point
    ├── services/              # Service implementations (optional alternative)
    │   ├── auth/
    │   │   ├── internal/      # Service implementation
@@ -145,17 +147,22 @@ Use a **monorepo structure with service directories** for all services:
 - Single entry point `cmd/platform/`
 - Shared infrastructure established
 
-### Phase 2: Service Structure (Epic 2)
+### Phase 2: Service Structure (Epic 1-2)
-- Create service directories in `cmd/`:
+- **Epic 1**: Create API Gateway service:
-  - `cmd/auth-service/`
+  - `cmd/api-gateway/` - API Gateway entry point
-  - `cmd/identity-service/`
+  - Service discovery integration
-  - `cmd/authz-service/`
+  - Request routing to backend services
-  - `cmd/audit-service/`
+- **Epic 2**: Create core service directories:
+  - `cmd/auth-service/` - Auth Service entry point
+  - `cmd/identity-service/` - Identity Service entry point
+  - `cmd/authz-service/` - Authz Service entry point
+  - `cmd/audit-service/` - Audit Service entry point
 - Create service implementations:
-  - Option A: `services/{service}/internal/` for each service
+  - Option A: `services/{service}/internal/` for each service (recommended)
-  - Option B: `internal/{service}/` for each service (if keeping all in internal/)
+  - Option B: `internal/{service}/` for each service
-  - Option C: Service code directly in `cmd/{service}/` for simple services
+  - Each service has its own database connection pool
-- Define service client interfaces in `pkg/services/`
+- Define service client interfaces in `pkg/services/`:
+  - `AuthServiceClient`, `IdentityServiceClient`, `AuthzServiceClient`, `AuditServiceClient`
 - Implement gRPC/HTTP clients in `internal/services/`
 
 ### Phase 3: Module Services (Epic 4+)
@@ -170,18 +177,27 @@ Use a **monorepo structure with service directories** for all services:
 ```
 goplt/
 ├── cmd/
-│   ├── platform/          # Core kernel
+│   ├── platform/          # Core kernel (minimal, infrastructure only)
+│   ├── api-gateway/       # API Gateway entry point
 │   ├── auth-service/      # Auth entry point
 │   ├── identity-service/  # Identity entry point
-│   └── ...
+│   ├── authz-service/     # Authz entry point
+│   ├── audit-service/     # Audit entry point
+│   └── blog-service/      # Blog feature service entry point
 ├── services/              # Service implementations
+│   ├── gateway/
+│   │   ├── internal/      # Gateway implementation
+│   │   └── api/           # Routing logic
 │   ├── auth/
 │   │   ├── internal/      # Service implementation
 │   │   └── api/           # gRPC/HTTP definitions
-│   └── ...
+│   ├── identity/
-├── internal/              # Core kernel (shared)
+│   ├── authz/
+│   ├── audit/
+│   └── blog/
+├── internal/              # Core kernel (shared infrastructure)
 ├── pkg/                   # Public interfaces
-└── modules/               # Feature modules
+└── modules/               # Feature modules (optional structure)
 ```
 
 This provides:

docs/content/adr/0032-api-gateway-strategy.md

@@ -0,0 +1,167 @@
+# ADR-0032: API Gateway Strategy
+
+## Status
+Accepted
+
+## Context
+The platform follows a microservices architecture where each service is independently deployable. We need a central entry point that handles:
+
+- Request routing to backend services
+- Authentication and authorization at the edge
+- Rate limiting and throttling
+- CORS and request/response transformation
+- Service discovery integration
+
+Options considered:
+1. **Custom API Gateway** - Build our own gateway service
+2. **Kong** - Open-source API Gateway
+3. **Envoy** - High-performance proxy
+4. **Traefik** - Modern reverse proxy
+
+## Decision
+Implement a **custom API Gateway service** as a core infrastructure component in Epic 1:
+
+1. **API Gateway as Core Component**:
+   - Entry point: `cmd/api-gateway/`
+   - Implementation: `services/gateway/internal/`
+   - Implemented in Epic 1 (not deferred to Epic 8)
+   - Required for microservices architecture, not optional
+
+2. **Responsibilities**:
+   - **Request Routing**: Route requests to backend services via service discovery
+   - **Authentication**: Validate JWT tokens via Auth Service
+   - **Authorization**: Check permissions via Authz Service (for route-level auth)
+   - **Rate Limiting**: Per-user and per-IP rate limiting
+   - **CORS**: Handle cross-origin requests
+   - **Request Transformation**: Modify requests before forwarding
+   - **Response Transformation**: Modify responses before returning
+   - **Load Balancing**: Distribute requests across service instances
+
+3. **Integration Points**:
+   - Service registry for service discovery
+   - Auth Service client for token validation
+   - Authz Service client for permission checks
+   - Cache (Redis) for rate limiting state
+
+4. **Implementation Approach**:
+   - Built with Go (Gin/Echo framework)
+   - Uses service clients for backend communication
+   - Configurable routing rules
+   - Middleware-based architecture
+
+## Architecture
+
+```mermaid
+graph TB
+    Client[Client] --> Gateway[API Gateway<br/>:8080]
+    
+    Gateway --> AuthClient[Auth Service Client]
+    Gateway --> AuthzClient[Authz Service Client]
+    Gateway --> ServiceRegistry[Service Registry]
+    Gateway --> Cache[Cache<br/>Rate Limiting]
+    
+    AuthClient --> AuthSvc[Auth Service<br/>:8081]
+    AuthzClient --> AuthzSvc[Authz Service<br/>:8083]
+    ServiceRegistry --> BackendSvc[Backend Services]
+    
+    Gateway --> BackendSvc
+    
+    style Gateway fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
+    style AuthSvc fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color:#fff
+    style BackendSvc fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
+```
+
+## Request Flow
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Gateway
+    participant AuthSvc
+    participant AuthzSvc
+    participant Registry
+    participant BackendSvc
+    
+    Client->>Gateway: HTTP Request
+    Gateway->>Gateway: Rate limiting check
+    Gateway->>AuthSvc: Validate JWT (gRPC)
+    AuthSvc-->>Gateway: Token valid + user info
+    Gateway->>AuthzSvc: Check route permission (gRPC, optional)
+    AuthzSvc-->>Gateway: Authorized
+    Gateway->>Registry: Discover backend service
+    Registry-->>Gateway: Service endpoint
+    Gateway->>BackendSvc: Forward request (gRPC/HTTP)
+    BackendSvc-->>Gateway: Response
+    Gateway-->>Client: HTTP Response
+```
+
+## Consequences
+
+### Positive
+- **Single Entry Point**: All external traffic goes through one gateway
+- **Centralized Security**: Authentication and authorization at the edge
+- **Performance**: Rate limiting and caching at gateway level
+- **Flexibility**: Easy to add new routes and services
+- **Consistency**: Uniform API interface for clients
+- **Observability**: Central point for metrics and logging
+
+### Negative
+- **Single Point of Failure**: Gateway failure affects all traffic
+- **Additional Latency**: Extra hop in request path
+- **Complexity**: Additional service to maintain and deploy
+- **Scaling**: Gateway must scale to handle all traffic
+
+### Mitigations
+1. **High Availability**: Deploy multiple gateway instances behind load balancer
+2. **Circuit Breakers**: Implement circuit breakers for backend service failures
+3. **Caching**: Cache authentication results and service endpoints
+4. **Monitoring**: Comprehensive monitoring and alerting
+5. **Graceful Degradation**: Fallback mechanisms for service failures
+
+## Implementation Strategy
+
+### Epic 1: Core Infrastructure
+- Create `cmd/api-gateway/` entry point
+- Implement basic routing with service discovery
+- JWT validation via Auth Service client
+- Rate limiting middleware
+- CORS support
+
+### Epic 2-3: Enhanced Features
+- Permission-based routing (via Authz Service)
+- Request/response transformation
+- Advanced load balancing
+- Health check integration
+
+## Configuration
+
+```yaml
+gateway:
+  port: 8080
+  routes:
+    - path: /api/v1/auth/**
+      service: auth-service
+      auth_required: false
+    - path: /api/v1/users/**
+      service: identity-service
+      auth_required: true
+      permission: user.read
+    - path: /api/v1/blog/**
+      service: blog-service
+      auth_required: true
+      permission: blog.post.read
+  rate_limiting:
+    enabled: true
+    per_user: 100/minute
+    per_ip: 1000/minute
+  cors:
+    allowed_origins: ["*"]
+    allowed_methods: ["GET", "POST", "PUT", "DELETE"]
+```
+
+## References
+- [ADR-0029: Microservices Architecture](./0029-microservices-architecture.md)
+- [ADR-0030: Service Communication Strategy](./0030-service-communication-strategy.md)
+- [ADR-0031: Service Repository Structure](./0031-service-repository-structure.md)
+- [API Gateway Pattern](https://microservices.io/patterns/apigateway.html)
+

docs/content/adr/0033-service-discovery-implementation.md

@@ -0,0 +1,310 @@
+# ADR-0033: Service Discovery Implementation
+
+## Status
+Accepted
+
+## Context
+The platform follows a microservices architecture where services need to discover and communicate with each other. We need a service discovery mechanism that:
+
+- Enables services to find each other dynamically
+- Supports health checking and automatic deregistration
+- Works in both development (Docker Compose) and production (Kubernetes) environments
+- Provides service registration and discovery APIs
+- Supports multiple service instances (load balancing)
+
+Options considered:
+1. **Consul** - HashiCorp's service discovery and configuration tool
+2. **etcd** - Distributed key-value store with service discovery
+3. **Kubernetes Service Discovery** - Native K8s service discovery
+4. **Eureka** - Netflix service discovery (Java-focused)
+5. **Custom Registry** - Build our own service registry
+
+## Decision
+Use **Consul** as the primary service discovery implementation with support for Kubernetes service discovery as an alternative.
+
+### Rationale
+
+1. **Mature and Production-Ready**:
+   - Battle-tested in production environments
+   - Active development and strong community
+   - Comprehensive documentation
+
+2. **Feature-Rich**:
+   - Service registration and health checking
+   - Key-value store for configuration
+   - Service mesh capabilities (Consul Connect)
+   - Multi-datacenter support
+   - DNS-based service discovery
+
+3. **Development-Friendly**:
+   - Easy to run locally (single binary or Docker)
+   - Docker Compose integration
+   - Good for local development setup
+
+4. **Production-Ready**:
+   - Works well in Kubernetes (Consul K8s)
+   - Can be used alongside Kubernetes service discovery
+   - Supports high availability and clustering
+
+5. **Language Agnostic**:
+   - HTTP API for service registration
+   - gRPC support
+   - Go client library available
+
+6. **Health Checking**:
+   - Built-in health checking with automatic deregistration
+   - Multiple health check types (HTTP, TCP, gRPC, script)
+   - Health status propagation
+
+## Architecture
+
+### Service Registry Interface
+
+```go
+// pkg/registry/registry.go
+type ServiceRegistry interface {
+    // Register a service instance
+    Register(ctx context.Context, service *ServiceInstance) error
+    
+    // Deregister a service instance
+    Deregister(ctx context.Context, serviceID string) error
+    
+    // Discover service instances
+    Discover(ctx context.Context, serviceName string) ([]*ServiceInstance, error)
+    
+    // Watch for service changes
+    Watch(ctx context.Context, serviceName string) (<-chan []*ServiceInstance, error)
+    
+    // Get service health
+    Health(ctx context.Context, serviceID string) (*HealthStatus, error)
+}
+
+type ServiceInstance struct {
+    ID       string
+    Name     string
+    Address  string
+    Port     int
+    Tags     []string
+    Metadata map[string]string
+}
+```
+
+### Consul Implementation
+
+```go
+// internal/registry/consul/consul.go
+type ConsulRegistry struct {
+    client *consul.Client
+    config *ConsulConfig
+}
+
+// Register service with Consul
+func (r *ConsulRegistry) Register(ctx context.Context, service *ServiceInstance) error {
+    registration := &consul.AgentServiceRegistration{
+        ID:      service.ID,
+        Name:    service.Name,
+        Address: service.Address,
+        Port:    service.Port,
+        Tags:    service.Tags,
+        Meta:    service.Metadata,
+        Check: &consul.AgentServiceCheck{
+            HTTP:     fmt.Sprintf("http://%s:%d/healthz", service.Address, service.Port),
+            Interval: "10s",
+            Timeout:  "3s",
+            DeregisterCriticalServiceAfter: "30s",
+        },
+    }
+    return r.client.Agent().ServiceRegister(registration)
+}
+```
+
+## Implementation Strategy
+
+### Phase 1: Consul Implementation (Epic 1)
+- Create service registry interface in `pkg/registry/`
+- Implement Consul registry in `internal/registry/consul/`
+- Basic service registration and discovery
+- Health check integration
+
+### Phase 2: Kubernetes Support (Epic 6)
+- Implement Kubernetes service discovery as alternative
+- Service registry factory that selects implementation based on environment
+- Support for both Consul and K8s in same codebase
+
+### Phase 3: Advanced Features (Epic 6)
+- Service mesh integration (Consul Connect)
+- Multi-datacenter support
+- Service tags and filtering
+- Service metadata and configuration
+
+## Configuration
+
+```yaml
+registry:
+  type: consul  # or "kubernetes"
+  consul:
+    address: "localhost:8500"
+    datacenter: "dc1"
+    scheme: "http"
+    health_check:
+      interval: "10s"
+      timeout: "3s"
+      deregister_after: "30s"
+  kubernetes:
+    namespace: "default"
+    in_cluster: true
+```
+
+## Service Registration Flow
+
+```mermaid
+sequenceDiagram
+    participant Service
+    participant Registry[Service Registry Interface]
+    participant Consul
+    participant Health[Health Check]
+    
+    Service->>Registry: Register(serviceInstance)
+    Registry->>Consul: Register service
+    Consul->>Consul: Store service info
+    Consul->>Health: Start health checks
+    
+    loop Health Check
+        Health->>Service: GET /healthz
+        Service-->>Health: 200 OK
+        Health->>Consul: Update health status
+    end
+    
+    Service->>Registry: Deregister(serviceID)
+    Registry->>Consul: Deregister service
+    Consul->>Consul: Remove service
+```
+
+## Service Discovery Flow
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Registry[Service Registry]
+    participant Consul
+    participant Service1[Service Instance 1]
+    participant Service2[Service Instance 2]
+    
+    Client->>Registry: Discover("auth-service")
+    Registry->>Consul: Query service instances
+    Consul-->>Registry: [instance1, instance2]
+    Registry->>Registry: Filter healthy instances
+    Registry-->>Client: [healthy instances]
+    
+    Client->>Service1: gRPC call
+    Service1-->>Client: Response
+```
+
+## Development Setup
+
+### Docker Compose
+
+```yaml
+services:
+  consul:
+    image: consul:latest
+    ports:
+      - "8500:8500"
+    command: consul agent -dev -client=0.0.0.0
+    volumes:
+      - consul-data:/consul/data
+
+volumes:
+  consul-data:
+```
+
+### Local Development
+
+```bash
+# Run Consul in dev mode
+consul agent -dev
+
+# Or use Docker
+docker run -d --name consul -p 8500:8500 consul:latest
+```
+
+## Production Deployment
+
+### Kubernetes
+
+```yaml
+# Consul Helm Chart
+helm repo add hashicorp https://helm.releases.hashicorp.com
+helm install consul hashicorp/consul --set global.datacenter=dc1
+```
+
+### Standalone Cluster
+
+- Deploy Consul cluster (3-5 nodes)
+- Configure service discovery endpoints
+- Set up Consul Connect for service mesh (optional)
+
+## Consequences
+
+### Positive
+- **Dynamic Service Discovery**: Services can be added/removed without configuration changes
+- **Health Checking**: Automatic removal of unhealthy services
+- **Load Balancing**: Multiple service instances automatically discovered
+- **Configuration Management**: Consul KV store for service configuration
+- **Service Mesh Ready**: Can use Consul Connect for advanced features
+- **Development Friendly**: Easy local setup with Docker
+
+### Negative
+- **Additional Infrastructure**: Requires Consul cluster in production
+- **Network Dependency**: Services depend on Consul availability
+- **Configuration Complexity**: Need to configure Consul cluster
+- **Learning Curve**: Team needs to understand Consul concepts
+
+### Mitigations
+1. **High Availability**: Deploy Consul cluster (3+ nodes)
+2. **Caching**: Cache service instances to reduce Consul queries
+3. **Fallback**: Support Kubernetes service discovery as fallback
+4. **Documentation**: Comprehensive setup and usage documentation
+5. **Monitoring**: Monitor Consul health and service registration
+
+## Alternative: Kubernetes Service Discovery
+
+For Kubernetes deployments, we also support native Kubernetes service discovery:
+
+```go
+// internal/registry/kubernetes/k8s.go
+type KubernetesRegistry struct {
+    clientset kubernetes.Interface
+    namespace string
+}
+
+func (r *KubernetesRegistry) Discover(ctx context.Context, serviceName string) ([]*ServiceInstance, error) {
+    endpoints, err := r.clientset.CoreV1().Endpoints(r.namespace).Get(ctx, serviceName, metav1.GetOptions{})
+    // Convert K8s endpoints to ServiceInstance
+}
+```
+
+## Service Registry Factory
+
+```go
+// internal/registry/factory.go
+func NewServiceRegistry(cfg *config.Config) (registry.ServiceRegistry, error) {
+    switch cfg.Registry.Type {
+    case "consul":
+        return consul.NewRegistry(cfg.Registry.Consul)
+    case "kubernetes":
+        return kubernetes.NewRegistry(cfg.Registry.Kubernetes)
+    default:
+        return nil, fmt.Errorf("unknown registry type: %s", cfg.Registry.Type)
+    }
+}
+```
+
+## References
+- [ADR-0029: Microservices Architecture](./0029-microservices-architecture.md)
+- [ADR-0030: Service Communication Strategy](./0030-service-communication-strategy.md)
+- [ADR-0031: Service Repository Structure](./0031-service-repository-structure.md)
+- [Consul Documentation](https://www.consul.io/docs)
+- [Consul Go Client](https://github.com/hashicorp/consul/api)
+- [Consul Kubernetes](https://www.consul.io/docs/k8s)
+

docs/content/adr/0034-go-version-upgrade.md

@@ -0,0 +1,57 @@
+# ADR-0034: Go Version Upgrade to 1.25.3
+
+## Status
+Accepted
+
+## Context
+ADR-0002 established Go 1.24.3 as the minimum required version. Since then:
+
+- Go 1.25.3 has been released with new features, performance improvements, and security fixes
+- The project requires access to newer language features and tooling improvements
+- Dependencies may benefit from Go 1.25.3 optimizations
+- The development team has Go 1.25.3 available and working
+
+## Decision
+Upgrade from **Go 1.24.3** to **Go 1.25.3** as the minimum required version for the platform.
+
+This decision supersedes [ADR-0002: Go Version](./0002-go-version.md).
+
+**Rationale:**
+- Access to latest Go features and performance improvements
+- Better security with latest patches
+- Improved tooling support and compiler optimizations
+- Ensures compatibility with latest ecosystem dependencies
+- Supports all planned features (modules, plugins, generics) with enhanced capabilities
+
+## Consequences
+
+### Positive
+- Access to latest Go features and performance improvements
+- Better security with latest patches
+- Modern tooling support with improved compiler optimizations
+- Better compatibility with latest dependency versions
+- Enhanced performance characteristics
+
+### Negative
+- Requires developers to upgrade to Go 1.25.3+
+- CI/CD must be updated to use Go 1.25.3
+- May require dependency updates for compatibility
+- Slightly higher barrier for developers still on older versions
+
+### Mitigations
+1. **Clear Documentation**: Update all documentation to specify Go 1.25.3 requirement
+2. **CI/CD Updates**: Ensure CI/CD pipelines use Go 1.25.3
+3. **Version Check**: Add version validation in build scripts if needed
+4. **Developer Communication**: Notify team of version requirement
+
+## Implementation Notes
+- Update `go.mod`: `go 1.25.3`
+- Update `.github/workflows/ci.yml` to use `actions/setup-go@v5` with version `1.25.3`
+- Update ADR-0002 to mark as Superseded
+- Update README.md and other documentation to reflect Go 1.25.3 requirement
+- Run `go mod tidy` to ensure dependency compatibility
+
+## References
+- [ADR-0002: Go Version](./0002-go-version.md) - Superseded by this ADR
+- [Go 1.25 Release Notes](https://go.dev/doc/go1.25)
+

docs/content/adr/README.md

@@ -5,6 +5,7 @@ This directory contains Architecture Decision Records (ADRs) for the Go Platform
 ## What are ADRs?
 
 ADRs document important architectural decisions made during the project. They help:
+
 - Track why decisions were made
 - Understand the context and constraints
 - Review decisions when requirements change
@@ -13,6 +14,7 @@ ADRs document important architectural decisions made during the project. They he
 ## ADR Format
 
 Each ADR follows this structure:
+
 - **Status**: Proposed | Accepted | Rejected | Superseded
 - **Context**: The situation that led to the decision
 - **Decision**: What was decided
@@ -23,7 +25,8 @@ Each ADR follows this structure:
 ### Epic 0: Project Setup & Foundation
 
 - [ADR-0001: Go Module Path](./0001-go-module-path.md) - Module path: `git.dcentral.systems/toolz/goplt`
-- [ADR-0002: Go Version](./0002-go-version.md) - Go 1.24.3
+- [ADR-0002: Go Version](./0002-go-version.md) - Go 1.24.3 (Superseded by ADR-0034)
+- [ADR-0034: Go Version Upgrade to 1.25.3](./0034-go-version-upgrade.md) - Go 1.25.3
 - [ADR-0003: Dependency Injection Framework](./0003-dependency-injection-framework.md) - uber-go/fx
 - [ADR-0004: Configuration Management](./0004-configuration-management.md) - spf13/viper + cobra
 - [ADR-0005: Logging Framework](./0005-logging-framework.md) - go.uber.org/zap
@@ -71,9 +74,11 @@ Each ADR follows this structure:
 
 ### Architecture & Scaling
 
-- [ADR-0029: Microservices Architecture](./0029-microservices-architecture.md) - Microservices architecture from day one
+- [ADR-0029: Microservices Architecture](./0029-microservices-architecture.md) - micromicroservices architecture from day one
-- [ADR-0030: Service Communication Strategy](./0030-service-communication-strategy.md) - Service client abstraction and communication patterns
+- [ADR-0030: Service Communication Strategy](./0030-service-communication-strategy.md) - Service client abstraction and communication patterns with API Gateway
 - [ADR-0031: Service Repository Structure](./0031-service-repository-structure.md) - Monorepo with service directories
+- [ADR-0032: API Gateway Strategy](./0032-api-gateway-strategy.md) - API Gateway as core infrastructure component
+- [ADR-0033: Service Discovery Implementation](./0033-service-discovery-implementation.md) - Consul-based service discovery (primary), Kubernetes as alternative
 
 ## Adding New ADRs
 

docs/content/architecture/architecture-modules.md

@@ -1,6 +1,6 @@
 # Module Architecture
 
-This document details the architecture of modules, how they are structured, how they interact with the core platform, and how multiple modules work together.
+This document details the architecture of modules (feature services), how they are structured as independent services, how they interact with core services, and how multiple services work together in the microservices architecture.
 
 ## Table of Contents
 
@@ -52,28 +52,33 @@ graph TD
     style Service fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
 ```
 
-### Module Directory Structure
+### Service Directory Structure
+
+Each module is an independent service with its own entry point:
 
 ```
-modules/blog/
+cmd/blog-service/
-├── go.mod                    # Module dependencies
+└── main.go                   # Service entry point
-├── module.yaml               # Module manifest
+
-├── pkg/
+services/blog/
-│   └── module.go            # IModule implementation
+├── go.mod                    # Service dependencies
+├── module.yaml               # Service manifest
+├── api/
+│   └── blog.proto           # gRPC service definition
 ├── internal/
 │   ├── api/
-│   │   └── handler.go       # HTTP handlers
+│   │   └── handler.go       # gRPC handlers
 │   ├── domain/
 │   │   ├── post.go          # Domain entities
 │   │   └── post_repo.go     # Repository interface
 │   ├── service/
 │   │   └── post_service.go  # Business logic
-│   └── ent/
+│   └── database/
-│       ├── schema/
+│       └── client.go        # Database connection
-│       │   └── post.go      # Ent schema
+└── ent/
-│       └── migrate/         # Migrations
+    ├── schema/
-└── tests/
+    │   └── post.go          # Ent schema
-    └── integration_test.go
+    └── migrate/             # Migrations
 ```
 
 ## Module Interface
@@ -262,9 +267,9 @@ graph LR
     style Step1 fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
 ```
 
-## Module Communication
+## Service Communication
 
-Modules (services) communicate through service client interfaces. All inter-service communication uses gRPC (primary) or HTTP (fallback).
+Modules are implemented as independent services that communicate through service client interfaces. All inter-service communication uses gRPC (primary) or HTTP (fallback) via service clients. Services discover each other through the service registry (Consul).
 
 ### Communication Patterns
 
@@ -301,14 +306,27 @@ graph TB
     BlogService -->|gRPC| AuthClient
     BlogService -->|gRPC| IdentityClient
     BlogService -->|gRPC| AuthzClient
+    BlogService -->|gRPC| AuditClient
     BlogService -->|Publish| EventBus
     EventBus -->|Subscribe| AnalyticsService
     
+    AuthClient -->|Discover| Registry
+    IdentityClient -->|Discover| Registry
+    AuthzClient -->|Discover| Registry
+    AuditClient -->|Discover| Registry
+    
+    Registry --> AuthService
+    Registry --> IdentityService
+    Registry --> AuthzService
+    Registry --> AuditService
+    
     AuthClient --> AuthService
     IdentityClient --> IdentityService
-    AuthzClient --> IdentityService
+    AuthzClient --> AuthzService
+    AuditClient --> AuditService
     
     style EventBus fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
+    style Registry fill:#50c878,stroke:#2e7d4e,stroke-width:3px,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

docs/content/architecture/architecture.md

@@ -13,20 +13,37 @@ This document provides a comprehensive overview of the Go Platform architecture,
 
 ## High-Level Architecture
 
-The Go Platform follows a **microservices architecture** where each module is an independent service:
+The Go Platform follows a **microservices architecture** where each service is independently deployable from day one:
-- **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.
+- **Core Kernel**: Infrastructure only (config, logger, DI, health, metrics, observability) - no business logic
+- **Core Services**: Auth Service, Identity Service, Authz Service, Audit Service - separate microservices
+- **API Gateway**: Single entry point for all external traffic, handles routing and authentication
+- **Feature Services**: Blog, Billing, Analytics, etc. - independent services
+- **Infrastructure Adapters**: Cache, Event Bus, Scheduler, etc. - shared infrastructure
+
+All services communicate via gRPC (primary) or HTTP (fallback) through service client interfaces, with service discovery via a service registry. Each service has its own database connection pool and schema. Services share infrastructure (PostgreSQL instance, Redis, Kafka) but are independently deployable and scalable.
 
 ```mermaid
 graph TB
-    subgraph "Go Platform"
+    subgraph "API Gateway"
-        Core[Core Kernel]
+        Gateway[API Gateway<br/>:8080]
-        Module1[Module 1<br/>Blog]
+    end
-        Module2[Module 2<br/>Billing]
+    
-        Module3[Module N<br/>Custom]
+    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 "Core Kernel"
+        Kernel[Core Kernel<br/>Infrastructure Only]
     end
     
     subgraph "Infrastructure"
@@ -34,6 +51,7 @@ graph TB
         Cache[(Redis)]
         Queue[Kafka/Event Bus]
         Storage[S3/Blob Storage]
+        Registry[Service Registry]
     end
     
     subgraph "External Services"
@@ -42,29 +60,52 @@ graph TB
         Sentry[Sentry]
     end
     
-    Core --> DB
+    Gateway --> AuthSvc
-    Core --> Cache
+    Gateway --> IdentitySvc
-    Core --> Queue
+    Gateway --> AuthzSvc
-    Core --> Storage
+    Gateway --> BlogSvc
-    Core --> OIDC
+    Gateway --> BillingSvc
-    Core --> Email
-    Core --> Sentry
     
-    Module1 --> Core
+    AuthSvc --> IdentitySvc
-    Module2 --> Core
+    AuthSvc --> Registry
-    Module3 --> Core
+    AuthzSvc --> IdentitySvc
+    AuthzSvc --> Cache
+    AuthzSvc --> AuditSvc
+    BlogSvc --> AuthzSvc
+    BlogSvc --> IdentitySvc
+    BlogSvc --> Registry
     
-    Module1 --> DB
+    AuthSvc --> DB
-    Module2 --> DB
+    IdentitySvc --> DB
-    Module3 --> DB
+    AuthzSvc --> DB
+    AuditSvc --> DB
+    BlogSvc --> DB
+    BillingSvc --> DB
     
-    Module1 --> Queue
+    AuthSvc --> Cache
-    Module2 --> Queue
+    AuthzSvc --> Cache
+    BlogSvc --> Cache
+    BillingSvc --> Cache
     
-    style Core fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
+    BlogSvc --> Queue
-    style Module1 fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
+    BillingSvc --> Queue
-    style Module2 fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
+    AnalyticsSvc --> Queue
-    style Module3 fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
+    
+    Kernel --> DB
+    Kernel --> Cache
+    Kernel --> Queue
+    Kernel --> Registry
+    
+    AuthSvc --> OIDC
+    IdentitySvc --> Email
+    AuditSvc --> Sentry
+    
+    style Gateway fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
+    style Kernel fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
+    style AuthSvc fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color:#fff
+    style IdentitySvc fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color:#fff
+    style BlogSvc fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
+    style BillingSvc fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
 ```
 
 ## Layered Architecture
@@ -99,12 +140,13 @@ graph TD
         Jobs[Scheduler/Jobs]
     end
     
-    subgraph "Core Kernel"
+    subgraph "Core Kernel (Infrastructure Only)"
         DI[DI Container]
         Config[Config Manager]
         Logger[Logger]
         Metrics[Metrics]
         Health[Health Checks]
+        Tracer[OpenTelemetry Tracer]
     end
     
     HTTP --> AuthMiddleware
@@ -244,7 +286,7 @@ This diagram shows how core components interact with each other and with modules
 
 ```mermaid
 graph TB
-    subgraph "Core Kernel Components"
+    subgraph "Core Kernel Components (Infrastructure)"
         ConfigMgr[Config Manager]
         LoggerService[Logger Service]
         DI[DI Container]
@@ -252,15 +294,20 @@ graph TB
         HealthRegistry[Health Registry]
         MetricsRegistry[Metrics Registry]
         ErrorBus[Error Bus]
-        EventBus[Event Bus]
+        Tracer[OpenTelemetry Tracer]
+        ServiceRegistry[Service Registry]
     end
     
-    subgraph "Security Components"
+    subgraph "Core Services (Separate Microservices)"
-        AuthService[Auth Service]
+        AuthService[Auth Service<br/>:8081]
-        AuthzService[Authorization Service]
+        IdentityService[Identity Service<br/>:8082]
-        TokenProvider[Token Provider]
+        AuthzService[Authz Service<br/>:8083]
-        PermissionResolver[Permission Resolver]
+        AuditService[Audit Service<br/>:8084]
-        AuditService[Audit Service]
+    end
+    
+    subgraph "Infrastructure Adapters"
+        EventBus[Event Bus<br/>Kafka]
+        CacheService[Cache Service<br/>Redis]
     end
     
     subgraph "Infrastructure Components"
@@ -270,6 +317,10 @@ graph TB
         Notifier[Notifier]
     end
     
+    subgraph "External Services"
+        Sentry[Sentry<br/>Error Reporting]
+    end
+    
     subgraph "Module Components"
         ModuleRoutes[Module Routes]
         ModuleServices[Module Services]
@@ -282,34 +333,35 @@ graph TB
     DI --> HealthRegistry
     DI --> MetricsRegistry
     DI --> ErrorBus
-    DI --> EventBus
+    DI --> Tracer
-    DI --> AuthService
+    DI --> ServiceRegistry
-    DI --> AuthzService
-    DI --> DBClient
-    DI --> CacheClient
-    DI --> Scheduler
-    DI --> Notifier
     
-    AuthService --> TokenProvider
+    ModuleServices -->|gRPC| AuthService
-    AuthzService --> PermissionResolver
+    ModuleServices -->|gRPC| IdentityService
-    AuthzService --> AuditService
+    ModuleServices -->|gRPC| AuthzService
+    ModuleServices -->|gRPC| AuditService
+    ModuleServices --> EventBus
+    ModuleServices --> CacheService
     
     ModuleServices --> DBClient
-    ModuleServices --> CacheClient
-    ModuleServices --> EventBus
-    ModuleServices --> AuthzService
-    
     ModuleRepos --> DBClient
-    ModuleRoutes --> AuthzService
     
-    Scheduler --> CacheClient
+    AuthService --> DBClient
-    Notifier --> EventBus
+    IdentityService --> DBClient
+    AuthzService --> DBClient
+    AuditService --> DBClient
+    
+    AuthService --> ServiceRegistry
+    IdentityService --> ServiceRegistry
+    AuthzService --> ServiceRegistry
+    AuditService --> ServiceRegistry
     
     ErrorBus --> LoggerService
     ErrorBus --> Sentry
     
     style DI fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
-    style AuthService fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
+    style AuthService fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color:#fff
+    style IdentityService fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color:#fff
     style ModuleServices fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
 ```
 
@@ -320,34 +372,28 @@ graph TB
 ```mermaid
 sequenceDiagram
     participant Client
-    participant Router
+    participant Gateway[API Gateway]
-    participant AuthMW[Auth Middleware]
+    participant AuthSvc[Auth Service]
-    participant AuthzMW[Authz Middleware]
+    participant AuthzSvc[Authz Service]
-    participant RateLimit[Rate Limiter]
+    participant Service[Feature Service]
-    participant Handler
+    participant IdentitySvc[Identity Service]
-    participant Service
+    participant AuditSvc[Audit Service]
     participant Repo
     participant DB
     participant Cache
     participant EventBus
-    participant Audit
     
-    Client->>Router: HTTP Request
+    Client->>Gateway: HTTP Request
-    Router->>AuthMW: Extract JWT
+    Gateway->>Gateway: Rate limiting
-    AuthMW->>AuthMW: Validate token
+    Gateway->>AuthSvc: Validate JWT token (gRPC)
-    AuthMW->>Router: Add user to context
+    AuthSvc->>AuthSvc: Verify token
+    AuthSvc-->>Gateway: Token valid + user info
     
-    Router->>AuthzMW: Check permissions
+    Gateway->>AuthzSvc: Check permissions (gRPC)
-    AuthzMW->>AuthzMW: Resolve permissions
+    AuthzSvc->>AuthzSvc: Resolve permissions
-    AuthzMW->>Router: Authorized
+    AuthzSvc-->>Gateway: Authorized
     
-    Router->>RateLimit: Check rate limits
+    Gateway->>Service: Route to service (gRPC/HTTP)
-    RateLimit->>Cache: Get rate limit state
-    Cache-->>RateLimit: Rate limit status
-    RateLimit->>Router: Within limits
-    
-    Router->>Handler: Process request
-    Handler->>Service: Business logic
     Service->>Cache: Check cache
     Cache-->>Service: Cache miss
     
@@ -357,12 +403,14 @@ sequenceDiagram
     Repo-->>Service: Domain entity
     Service->>Cache: Store in cache
     
-    Service->>EventBus: Publish event
+    Service->>IdentitySvc: Get user info (gRPC, if needed)
-    Service->>Audit: Record action
+    IdentitySvc-->>Service: User data
     
-    Service-->>Handler: Response data
+    Service->>EventBus: Publish event
-    Handler-->>Router: HTTP response
+    Service->>AuditSvc: Record action (gRPC)
-    Router-->>Client: JSON response
+    
+    Service-->>Gateway: Response data
+    Gateway-->>Client: JSON response
 ```
 
 ### Module Event Flow
@@ -408,21 +456,56 @@ graph TB
     end
     
     subgraph "Local Services"
-        App[Platform App<br/>:8080]
+        Gateway[API Gateway<br/>:8080]
+        AuthSvc[Auth Service<br/>:8081]
+        IdentitySvc[Identity Service<br/>:8082]
+        AuthzSvc[Authz Service<br/>:8083]
+        AuditSvc[Audit Service<br/>:8084]
+        BlogSvc[Blog Service<br/>:8091]
         DB[(PostgreSQL<br/>:5432)]
         Redis[(Redis<br/>:6379)]
         Kafka[Kafka<br/>:9092]
+        Consul[Consul<br/>:8500]
     end
     
     IDE --> Go
-    Go --> App
+    Go --> Gateway
-    App --> DB
+    Go --> AuthSvc
-    App --> Redis
+    Go --> IdentitySvc
-    App --> Kafka
+    Go --> AuthzSvc
+    Go --> AuditSvc
+    Go --> BlogSvc
+    
+    Gateway --> AuthSvc
+    Gateway --> IdentitySvc
+    Gateway --> BlogSvc
+    
+    AuthSvc --> DB
+    IdentitySvc --> DB
+    AuthzSvc --> DB
+    AuditSvc --> DB
+    BlogSvc --> DB
+    
+    AuthSvc --> Redis
+    AuthzSvc --> Redis
+    BlogSvc --> Redis
+    
+    BlogSvc --> Kafka
+    
+    AuthSvc --> Consul
+    IdentitySvc --> Consul
+    AuthzSvc --> Consul
+    AuditSvc --> Consul
+    BlogSvc --> Consul
     
     Docker --> DB
     Docker --> Redis
     Docker --> Kafka
+    Docker --> Consul
+    
+    style Gateway fill:#4a90e2,stroke:#2e5c8a,stroke-width:2px,color:#fff
+    style AuthSvc fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color:#fff
+    style IdentitySvc fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color:#fff
 ```
 
 ### Production Deployment
@@ -433,10 +516,15 @@ graph TB
         LB[Load Balancer<br/>HTTPS]
     end
     
-    subgraph "Platform Instances"
+    subgraph "Service Instances"
-        App1[Platform Instance 1]
+        Gateway1[API Gateway 1]
-        App2[Platform Instance 2]
+        Gateway2[API Gateway 2]
-        App3[Platform Instance N]
+        AuthSvc1[Auth Service 1]
+        AuthSvc2[Auth Service 2]
+        IdentitySvc1[Identity Service 1]
+        IdentitySvc2[Identity Service 2]
+        BlogSvc1[Blog Service 1]
+        BlogSvc2[Blog Service 2]
     end
     
     subgraph "Database Cluster"
@@ -467,53 +555,87 @@ graph TB
         S3[S3 Storage]
     end
     
-    LB --> App1
+    LB --> Gateway1
-    LB --> App2
+    LB --> Gateway2
-    LB --> App3
     
-    App1 --> Primary
+    Gateway1 --> AuthSvc1
-    App2 --> Primary
+    Gateway1 --> AuthSvc2
-    App3 --> Primary
+    Gateway1 --> IdentitySvc1
-    App1 --> Replica
+    Gateway1 --> IdentitySvc2
-    App2 --> Replica
+    Gateway1 --> BlogSvc1
-    App3 --> Replica
+    Gateway1 --> BlogSvc2
+    Gateway2 --> AuthSvc1
+    Gateway2 --> AuthSvc2
+    Gateway2 --> IdentitySvc1
+    Gateway2 --> IdentitySvc2
+    Gateway2 --> BlogSvc1
+    Gateway2 --> BlogSvc2
     
-    App1 --> Redis1
+    AuthSvc1 --> Primary
-    App2 --> Redis1
+    AuthSvc2 --> Primary
-    App3 --> Redis1
+    IdentitySvc1 --> Primary
+    IdentitySvc2 --> Primary
+    BlogSvc1 --> Primary
+    BlogSvc2 --> Primary
     
-    App1 --> Kafka1
+    AuthSvc1 --> Replica
-    App2 --> Kafka2
+    AuthSvc2 --> Replica
-    App3 --> Kafka3
+    IdentitySvc1 --> Replica
+    IdentitySvc2 --> Replica
+    BlogSvc1 --> Replica
+    BlogSvc2 --> Replica
     
-    App1 --> Prometheus
+    AuthSvc1 --> Redis1
-    App2 --> Prometheus
+    AuthSvc2 --> Redis1
-    App3 --> Prometheus
+    IdentitySvc1 --> Redis1
+    IdentitySvc2 --> Redis1
+    BlogSvc1 --> Redis1
+    BlogSvc2 --> Redis1
+    
+    BlogSvc1 --> Kafka1
+    BlogSvc2 --> Kafka2
+    
+    AuthSvc1 --> Prometheus
+    AuthSvc2 --> Prometheus
+    IdentitySvc1 --> Prometheus
+    IdentitySvc2 --> Prometheus
+    BlogSvc1 --> Prometheus
+    BlogSvc2 --> Prometheus
     
     Prometheus --> Grafana
-    App1 --> Jaeger
+    AuthSvc1 --> Jaeger
-    App2 --> Jaeger
+    AuthSvc2 --> Jaeger
-    App3 --> Jaeger
+    IdentitySvc1 --> Jaeger
-    App1 --> Loki
+    IdentitySvc2 --> Jaeger
-    App2 --> Loki
+    BlogSvc1 --> Jaeger
-    App3 --> Loki
+    BlogSvc2 --> Jaeger
+    AuthSvc1 --> Loki
+    AuthSvc2 --> Loki
+    IdentitySvc1 --> Loki
+    IdentitySvc2 --> Loki
+    BlogSvc1 --> Loki
+    BlogSvc2 --> Loki
     
-    App1 --> Sentry
+    AuthSvc1 --> Sentry
-    App2 --> Sentry
+    AuthSvc2 --> Sentry
-    App3 --> Sentry
+    IdentitySvc1 --> Sentry
+    IdentitySvc2 --> Sentry
+    BlogSvc1 --> Sentry
+    BlogSvc2 --> Sentry
     
-    App1 --> S3
+    BlogSvc1 --> S3
-    App2 --> S3
+    BlogSvc2 --> S3
-    App3 --> S3
     
     style LB fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
+    style Gateway1 fill:#4a90e2,stroke:#2e5c8a,stroke-width:2px,color:#fff
+    style Gateway2 fill:#4a90e2,stroke:#2e5c8a,stroke-width:2px,color:#fff
     style Primary fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
     style Redis1 fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color:#fff
 ```
 
 ## Core Kernel Components
 
-The core kernel provides the foundation for all modules. Each component has specific responsibilities:
+The core kernel provides **infrastructure only** - no business logic. It is the foundation that all services depend on. Business logic resides in separate services (Auth, Identity, Authz, Audit).
 
 ### Component Responsibilities
 
@@ -536,10 +658,10 @@ mindmap
       Metrics
       Tracing
       Health checks
-    Security
+    Service Discovery
-      Authentication
+      Service registry
-      Authorization
+      Service registration
-      Audit logging
+      Health checking
     Module System
       Module discovery
       Module loading
@@ -555,8 +677,19 @@ graph TB
     subgraph "Core Kernel Interfaces"
         IConfig[ConfigProvider]
         ILogger[Logger]
-        IAuth[Authenticator]
+        ITracer[Tracer]
-        IAuthz[Authorizer]
+        IMetrics[Metrics]
+        IHealth[Health]
+    end
+    
+    subgraph "Service Client Interfaces"
+        IAuthClient[AuthServiceClient]
+        IIdentityClient[IdentityServiceClient]
+        IAuthzClient[AuthzServiceClient]
+        IAuditClient[AuditServiceClient]
+    end
+    
+    subgraph "Infrastructure Interfaces"
         IEventBus[EventBus]
         ICache[Cache]
         IBlobStore[BlobStore]
@@ -564,23 +697,29 @@ graph TB
         INotifier[Notifier]
     end
     
-    subgraph "Module Implementation"
+    subgraph "Feature Service Implementation"
-        Module[Feature Module]
+        Module[Feature Service]
-        ModuleServices[Module Services]
+        ModuleServices[Service Layer]
-        ModuleRoutes[Module Routes]
+        ModuleRoutes[HTTP/gRPC Routes]
     end
     
     Module --> IConfig
     Module --> ILogger
-    ModuleServices --> IAuth
+    Module --> ITracer
-    ModuleServices --> IAuthz
+    Module --> IMetrics
+    Module --> IHealth
+    
+    ModuleServices -->|gRPC| IAuthClient
+    ModuleServices -->|gRPC| IIdentityClient
+    ModuleServices -->|gRPC| IAuthzClient
+    ModuleServices -->|gRPC| IAuditClient
     ModuleServices --> IEventBus
     ModuleServices --> ICache
     ModuleServices --> IBlobStore
     ModuleServices --> IScheduler
     ModuleServices --> INotifier
     
-    ModuleRoutes --> IAuthz
+    ModuleRoutes -->|gRPC| IAuthzClient
     
     style IConfig fill:#4a90e2,stroke:#2e5c8a,stroke-width:2px,color:#fff
     style Module fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
@@ -737,10 +876,12 @@ graph TB
 - Team autonomy
 
 #### Development Mode
-- For local development, multiple services can run in the same process
+- For local development, services can run in the same repository/monorepo
-- Services still communicate via gRPC/HTTP (no direct calls)
+- Services still communicate via gRPC/HTTP through service clients (no direct in-process calls)
-- Docker Compose for easy local setup
+- Each service has its own process and entry point
+- Docker Compose for easy local setup with all services
 - Maintains microservices architecture even in development
+- Services can be started individually for debugging
 
 ## Next Steps
 

docs/content/architecture/component-relationships.md

@@ -32,10 +32,8 @@ graph TD
         Scheduler[Scheduler]
     end
     
-    subgraph "Security Layer"
+    subgraph "Service Registry"
-        Auth[Auth Service]
+        Registry[Service Registry<br/>Consul]
-        Authz[Authz Service]
-        Audit[Audit Service]
     end
     
     subgraph "Observability Layer"
@@ -52,17 +50,10 @@ graph TD
     DI --> Cache
     DI --> EventBus
     DI --> Scheduler
-    DI --> Auth
-    DI --> Authz
-    DI --> Audit
     DI --> Metrics
     DI --> Health
     DI --> Tracer
-    
+    DI --> Registry
-    Auth --> DB
-    Authz --> DB
-    Authz --> Cache
-    Audit --> DB
     
     DB --> Tracer
     Cache --> Tracer
@@ -70,12 +61,11 @@ graph TD
     
     style Config fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
     style DI fill:#50c878,stroke:#2e7d4e,stroke-width:3px,color:#fff
-    style Auth fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color:#fff
 ```
 
-## Module to Core Integration
+## Service to Service Integration
 
-Modules (services) integrate with core services through service client interfaces. All communication uses gRPC or HTTP.
+Feature services integrate with core services through service client interfaces. All communication uses gRPC (primary) or HTTP (fallback). Services discover each other via the service registry (Consul).
 
 ```mermaid
 graph LR
@@ -86,10 +76,14 @@ graph LR
     end
     
     subgraph "Service Clients"
-        AuthClient[Auth Service Client]
+        AuthClient[Auth Service Client<br/>gRPC]
-        AuthzClient[Authz Service Client]
+        AuthzClient[Authz Service Client<br/>gRPC]
-        IdentityClient[Identity Service Client]
+        IdentityClient[Identity Service Client<br/>gRPC]
-        AuditClient[Audit Service Client]
+        AuditClient[Audit Service Client<br/>gRPC]
+    end
+    
+    subgraph "Service Registry"
+        Registry[Consul<br/>Service Discovery]
     end
     
     subgraph "Core Services"
@@ -117,6 +111,16 @@ graph LR
     ModuleService --> EventBusService
     ModuleService --> CacheService
     
+    AuthClient -->|Discover| Registry
+    AuthzClient -->|Discover| Registry
+    IdentityClient -->|Discover| Registry
+    AuditClient -->|Discover| Registry
+    
+    Registry --> AuthService
+    Registry --> AuthzService
+    Registry --> IdentityService
+    Registry --> AuditService
+    
     AuthClient --> AuthService
     AuthzClient --> AuthzService
     IdentityClient --> IdentityService
@@ -127,9 +131,13 @@ graph LR
     EventBusService --> QueueClient
     
     style ModuleService fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
-    style AuthService fill:#4a90e2,stroke:#2e5c8a,stroke-width:2px,color:#fff
+    style Registry fill:#50c878,stroke:#2e7d4e,stroke-width:3px,color:#fff
+    style AuthService fill:#ff6b6b,stroke:#c92a2a,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
+    style AuthClient fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
+    style AuthzClient fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
+    style IdentityClient fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
+    style AuditClient fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
 ```
 
 ## Service Interaction Patterns
@@ -361,7 +369,6 @@ graph TB
     Notifier --> EventBus
     
     ErrorBus --> Logger
-    ErrorBus --> Sentry
     
     DB --> Tracer
     Cache --> Tracer
@@ -470,7 +477,8 @@ graph LR
     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
+    style AuthzClient fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
+    style IdentityClient fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
 ```
 
 ## Next Steps

docs/content/architecture/data-flow-patterns.md

@@ -19,18 +19,22 @@ Data flows through the platform in multiple patterns depending on the type of op
 
 ### Standard HTTP Request Flow
 
-Complete data flow from HTTP request to response.
+Complete data flow from HTTP request through API Gateway to backend service and response.
 
 ```mermaid
 graph TD
-    Start[HTTP Request] --> Auth[Authentication]
+    Start[HTTP Request] --> Gateway[API Gateway]
-    Auth -->|Valid| Authz[Authorization]
+    Gateway --> RateLimit{Rate Limit Check}
-    Auth -->|Invalid| Error1[401 Response]
+    RateLimit -->|Allowed| Auth[Validate JWT via Auth Service]
+    RateLimit -->|Exceeded| Error0[429 Too Many Requests]
     
-    Authz -->|Authorized| Handler[Request Handler]
+    Auth -->|Valid| Authz[Check Permission via Authz Service]
-    Authz -->|Unauthorized| Error2[403 Response]
+    Auth -->|Invalid| Error1[401 Unauthorized]
     
-    Handler --> Service[Domain Service]
+    Authz -->|Authorized| Route[Route to Backend Service]
+    Authz -->|Unauthorized| Error2[403 Forbidden]
+    
+    Route --> Service[Backend Service]
     Service --> Cache{Cache Check}
     
     Cache -->|Hit| CacheData[Return Cached Data]
@@ -42,17 +46,19 @@ graph TD
     Service --> CacheStore[Update Cache]
     
     Service --> EventBus[Publish Events]
-    Service --> Audit[Audit Log]
+    Service --> AuditSvc[Audit Service<br/>gRPC]
     Service --> Metrics[Update Metrics]
     
-    Service --> Handler
+    Service --> Gateway
-    Handler --> Response[HTTP Response]
+    Gateway --> Response[HTTP Response]
-    CacheData --> Response
+    CacheData --> Gateway
+    Error0 --> Response
     Error1 --> Response
     Error2 --> Response
     
     Response --> Client[Client]
     
+    style Gateway fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
     style Auth fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color:#fff
     style Service fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
     style Cache fill:#4a90e2,stroke:#2e5c8a,stroke-width:2px,color:#fff
@@ -60,22 +66,30 @@ graph TD
 
 ### Request Data Transformation
 
-How request data is transformed as it flows through the system.
+How request data is transformed as it flows through API Gateway to backend service.
 
 ```mermaid
 sequenceDiagram
     participant Client
-    participant Handler
+    participant Gateway
+    participant BackendService
     participant Service
     participant Repo
     participant DB
     
-    Client->>Handler: HTTP Request (JSON)
+    Client->>Gateway: HTTP Request (JSON)
-    Handler->>Handler: Parse JSON
+    Gateway->>Gateway: Rate limiting
-    Handler->>Handler: Validate request
+    Gateway->>Gateway: Validate JWT (via Auth Service)
-    Handler->>Handler: Convert to DTO
+    Gateway->>Gateway: Check permission (via Authz Service)
+    Gateway->>Gateway: Route to service (via service discovery)
+    Gateway->>Gateway: Forward request (gRPC/HTTP)
     
-    Handler->>Service: Business DTO
+    Gateway->>BackendService: Request (gRPC/HTTP)
+    BackendService->>BackendService: Parse request
+    BackendService->>BackendService: Validate request
+    BackendService->>BackendService: Convert to DTO
+    
+    BackendService->>Service: Business DTO
     Service->>Service: Business logic
     Service->>Service: Domain entity
     
@@ -89,10 +103,13 @@ sequenceDiagram
     
     Service->>Service: Business logic
     Service->>Service: Response DTO
-    Service-->>Handler: Response DTO
+    Service-->>BackendService: Response DTO
     
-    Handler->>Handler: Convert to JSON
+    BackendService->>BackendService: Convert to response format
-    Handler-->>Client: HTTP Response (JSON)
+    BackendService-->>Gateway: Response (gRPC/HTTP)
+    
+    Gateway->>Gateway: Transform response (if needed)
+    Gateway-->>Client: HTTP Response (JSON)
 ```
 
 ## Event Data Flow

docs/content/architecture/module-integration-patterns.md

@@ -6,7 +6,7 @@ This document explains how modules integrate with the core platform, focusing on
 
 ## Overview
 
-Modules are independent services that extend the platform's functionality. They integrate with the core platform through well-defined interfaces, service clients, and a standardized initialization process. Each module operates as an independent service while leveraging core platform capabilities.
+Modules are implemented as independent services that extend the platform's functionality. They integrate with core services through service client interfaces, service discovery (Consul), and a standardized initialization process. Each module operates as an independent service with its own entry point, database connection, and deployment while leveraging core platform capabilities.
 
 ## Key Concepts
 
@@ -94,7 +94,7 @@ sequenceDiagram
         DB-->>Module: Migrations registered
         
         Module->>ServiceRegistry: Register service
-        ServiceRegistry->>ServiceRegistry: Register with registry
+        ServiceRegistry->>ServiceRegistry: Register with Consul
         ServiceRegistry-->>Module: Service registered
         
         Module->>Module: OnStart hook (optional)

docs/content/architecture/operational-scenarios.md

@@ -25,16 +25,22 @@ Complete flow of user logging in and receiving authentication tokens.
 sequenceDiagram
     participant User
     participant Client
+    participant Gateway[API Gateway]
     participant AuthService
     participant IdentityService
     participant DB
     participant TokenProvider
     participant AuditService
+    participant Registry[Consul]
     
     User->>Client: Enter credentials
-    Client->>AuthService: POST /api/v1/auth/login
+    Client->>Gateway: POST /api/v1/auth/login
+    Gateway->>Gateway: Rate limiting check
+    Gateway->>AuthService: Login request (gRPC)
     AuthService->>AuthService: Validate request format
-    AuthService->>IdentityService: Verify credentials
+    AuthService->>Registry: Discover Identity Service
+    Registry-->>AuthService: Identity Service endpoint
+    AuthService->>IdentityService: Verify credentials (gRPC)
     IdentityService->>DB: Query user by email
     DB-->>IdentityService: User data
     IdentityService->>IdentityService: Verify password hash
@@ -49,11 +55,14 @@ sequenceDiagram
     DB-->>TokenProvider: Token stored
     TokenProvider-->>AuthService: Refresh token
     
-    AuthService->>AuditService: Log login
+    AuthService->>Registry: Discover Audit Service
+    Registry-->>AuthService: Audit Service endpoint
+    AuthService->>AuditService: Log login (gRPC)
     AuditService->>DB: Store audit log
     AuditService-->>AuthService: Logged
     
-    AuthService-->>Client: Access + Refresh tokens
+    AuthService-->>Gateway: Access + Refresh tokens
+    Gateway-->>Client: Access + Refresh tokens
     Client-->>User: Authentication successful
 ```
 
@@ -63,23 +72,25 @@ How the system checks if a user has permission to perform an action.
 
 ```mermaid
 sequenceDiagram
+    participant Gateway[API Gateway]
     participant Handler
-    participant AuthzMiddleware
     participant AuthzService
     participant PermissionResolver
     participant Cache
     participant DB
     participant IdentityService
+    participant Registry[Consul]
     
-    Handler->>AuthzMiddleware: Check permission
+    Gateway->>Handler: Request with user context
-    AuthzMiddleware->>AuthzMiddleware: Extract user from context
+    Handler->>AuthzService: Authorize(user, permission) (gRPC)
-    AuthzMiddleware->>AuthzService: Authorize(user, permission)
+    AuthzService->>Registry: Discover Identity Service
+    Registry-->>AuthzService: Identity Service endpoint
     
     AuthzService->>Cache: Check permission cache
     Cache-->>AuthzService: Cache miss
     
     AuthzService->>PermissionResolver: Resolve permissions
-    PermissionResolver->>IdentityService: Get user roles
+    PermissionResolver->>IdentityService: Get user roles (gRPC)
     IdentityService->>DB: Query user roles
     DB-->>IdentityService: User roles
     IdentityService-->>PermissionResolver: Roles list
@@ -91,12 +102,12 @@ sequenceDiagram
     
     AuthzService->>AuthzService: Check permission in list
     AuthzService->>Cache: Store in cache
-    AuthzService-->>AuthzMiddleware: Authorized/Unauthorized
+    AuthzService-->>Handler: Authorized/Unauthorized
     
     alt Authorized
-        AuthzMiddleware-->>Handler: Continue
+        Handler-->>Gateway: Continue request
     else Unauthorized
-        AuthzMiddleware-->>Handler: 403 Forbidden
+        Handler-->>Gateway: 403 Forbidden
     end
 ```
 

docs/content/architecture/service-orchestration.md

@@ -6,12 +6,12 @@ This document explains how services work together in the Go Platform's microserv
 
 ## Overview
 
-The Go Platform consists of multiple independent services that communicate via service clients (gRPC/HTTP) and share infrastructure components. Services are discovered and registered through a service registry, enabling dynamic service location and health monitoring.
+The Go Platform consists of multiple independent services that communicate via service clients (gRPC/HTTP) and share infrastructure components. Services are discovered and registered through a service registry (Consul), enabling dynamic service location and health monitoring.
 
 ## Key Concepts
 
 - **Service**: Independent process providing specific functionality
-- **Service Registry**: Central registry for service discovery (Consul, Kubernetes, etcd)
+- **Service Registry**: Central registry for service discovery (Consul - primary, Kubernetes as alternative)
 - **Service Client**: Abstraction for inter-service communication
 - **Service Discovery**: Process of locating services by name
 - **Service Health**: Health status of a service (healthy, unhealthy, degraded)
@@ -59,7 +59,7 @@ Services automatically register themselves with the service registry on startup
 sequenceDiagram
     participant Service
     participant ServiceRegistry
-    participant Registry[Consul/K8s]
+    participant Registry[Consul<br/>Service Registry]
     participant Client
     
     Service->>ServiceRegistry: Register(serviceInfo)
@@ -93,7 +93,7 @@ sequenceDiagram
 
 1. **Service Startup**: Service initializes and loads configuration
 2. **Service Info Creation**: Create service info with name, version, address, protocol
-3. **Registry Registration**: Register service with Consul/Kubernetes/etc
+3. **Registry Registration**: Register service with Consul (primary) or Kubernetes service discovery (alternative)
 4. **Health Check Setup**: Start health check endpoint
 5. **Health Status Updates**: Periodically update health status in registry
 6. **Service Discovery**: Clients query registry for service endpoints

docs/content/architecture/system-behavior.md

@@ -6,7 +6,7 @@ This document provides a high-level explanation of how the Go Platform behaves e
 
 ## Overview
 
-The Go Platform is a microservices-based system where each module operates as an independent service. Services communicate via gRPC (primary) or HTTP (fallback), share infrastructure components (PostgreSQL, Redis, Kafka), and are orchestrated through service discovery and dependency injection.
+The Go Platform is a microservices-based system where each service is independently deployable from day one. Services communicate via gRPC (primary) or HTTP (fallback) through service clients, share infrastructure components (PostgreSQL instance, Redis, Kafka), and are orchestrated through service discovery and dependency injection. All external traffic enters through the API Gateway.
 
 ## Key Concepts
 
@@ -16,9 +16,11 @@ The Go Platform is a microservices-based system where each module operates as an
 - **Event Bus**: Asynchronous communication channel for events
 - **DI Container**: Dependency injection container managing service lifecycle
 
-## Application Bootstrap Sequence
+## Service Bootstrap Sequence
 
-The platform follows a well-defined startup sequence that ensures all services are properly initialized and registered.
+Each service (API Gateway, Auth, Identity, Authz, Audit, and feature services) follows a well-defined startup sequence. Services bootstrap independently.
+
+### Individual Service Startup
 
 ```mermaid
 sequenceDiagram
@@ -26,9 +28,9 @@ sequenceDiagram
     participant Config
     participant Logger
     participant DI
-    participant Registry
+    participant ServiceImpl
-    participant ModuleLoader
     participant ServiceRegistry
+    participant DB
     participant HTTP
     participant gRPC
     
@@ -39,63 +41,121 @@ sequenceDiagram
     Logger-->>Main: Logger ready
     
     Main->>DI: Create DI container
-    DI->>DI: Register core services
+    DI->>DI: Register core kernel services
     DI-->>Main: DI container ready
     
-    Main->>ModuleLoader: Discover modules
+    Main->>ServiceImpl: Register service implementation
-    ModuleLoader->>ModuleLoader: Scan module directories
+    ServiceImpl->>DI: Register service dependencies
-    ModuleLoader->>ModuleLoader: Load module.yaml files
+    ServiceImpl->>DB: Connect to database
-    ModuleLoader-->>Main: Module list
+    DB-->>ServiceImpl: Connection ready
     
-    Main->>Registry: Register modules
+    Main->>DB: Run migrations
-    Registry->>Registry: Resolve dependencies
+    DB-->>Main: Migrations complete
-    Registry->>Registry: Order modules
-    Registry-->>Main: Ordered modules
-    
-    loop For each module
-        Main->>Module: Initialize module
-        Module->>DI: Register services
-        Module->>Registry: Register routes
-        Module->>Registry: Register migrations
-    end
-    
-    Main->>Registry: Run migrations
-    Registry->>Registry: Execute in dependency order
     
     Main->>ServiceRegistry: Register service
     ServiceRegistry->>ServiceRegistry: Register with Consul/K8s
     ServiceRegistry-->>Main: Service registered
     
     Main->>gRPC: Start gRPC server
-    Main->>HTTP: Start HTTP server
+    Main->>HTTP: Start HTTP server (if needed)
-    HTTP-->>Main: Server ready
+    HTTP-->>Main: HTTP server ready
-    gRPC-->>Main: Server ready
+    gRPC-->>Main: gRPC server ready
     
     Main->>DI: Start lifecycle
     DI->>DI: Execute OnStart hooks
-    DI-->>Main: All services started
+    DI-->>Main: Service started
 ```
 
-### Bootstrap Phases
+### Platform Startup (All Services)
+
+```mermaid
+sequenceDiagram
+    participant Docker
+    participant Gateway
+    participant AuthSvc
+    participant IdentitySvc
+    participant AuthzSvc
+    participant AuditSvc
+    participant BlogSvc
+    participant Registry
+    participant DB
+    
+    Docker->>DB: Start PostgreSQL
+    Docker->>Registry: Start Consul
+    DB-->>Docker: Database ready
+    Registry-->>Docker: Registry ready
+    
+    par Service Startup (in parallel)
+        Docker->>Gateway: Start API Gateway
+        Gateway->>Registry: Register
+        Gateway->>Gateway: Start HTTP server
+        Gateway-->>Docker: Gateway ready
+    and
+        Docker->>AuthSvc: Start Auth Service
+        AuthSvc->>DB: Connect
+        AuthSvc->>Registry: Register
+        AuthSvc->>AuthSvc: Start gRPC server
+        AuthSvc-->>Docker: Auth Service ready
+    and
+        Docker->>IdentitySvc: Start Identity Service
+        IdentitySvc->>DB: Connect
+        IdentitySvc->>Registry: Register
+        IdentitySvc->>IdentitySvc: Start gRPC server
+        IdentitySvc-->>Docker: Identity Service ready
+    and
+        Docker->>AuthzSvc: Start Authz Service
+        AuthzSvc->>DB: Connect
+        AuthzSvc->>Registry: Register
+        AuthzSvc->>AuthzSvc: Start gRPC server
+        AuthzSvc-->>Docker: Authz Service ready
+    and
+        Docker->>AuditSvc: Start Audit Service
+        AuditSvc->>DB: Connect
+        AuditSvc->>Registry: Register
+        AuditSvc->>AuditSvc: Start gRPC server
+        AuditSvc-->>Docker: Audit Service ready
+    and
+        Docker->>BlogSvc: Start Blog Service
+        BlogSvc->>DB: Connect
+        BlogSvc->>Registry: Register
+        BlogSvc->>BlogSvc: Start gRPC server
+        BlogSvc-->>Docker: Blog Service ready
+    end
+    
+    Docker->>Docker: All services ready
+```
+
+### Service Bootstrap Phases (Per Service)
 
 1. **Configuration Loading**: Load YAML files, environment variables, and secrets
-2. **Foundation Services**: Initialize logger, config provider, DI container
+2. **Foundation Services**: Initialize core kernel (logger, config, DI container)
-3. **Module Discovery**: Scan and load module manifests
+3. **Database Connection**: Connect to database with own connection pool
-4. **Dependency Resolution**: Build dependency graph and order modules
+4. **Service Implementation**: Register service-specific implementations
-5. **Module Initialization**: Initialize each module in dependency order
+5. **Database Migrations**: Run service-specific migrations
-6. **Database Migrations**: Run migrations in dependency order
+6. **Service Registration**: Register service with service registry
-7. **Service Registration**: Register service with service registry
+7. **Server Startup**: Start gRPC server (and HTTP if needed)
-8. **Server Startup**: Start HTTP and gRPC servers
+8. **Lifecycle Hooks**: Execute OnStart hooks
-9. **Lifecycle Hooks**: Execute OnStart hooks for all services
+
+### Platform Startup Order
+
+1. **Infrastructure**: Start PostgreSQL, Redis, Kafka, Consul
+2. **Core Services**: Start Auth, Identity, Authz, Audit services (can start in parallel)
+3. **API Gateway**: Start API Gateway (depends on service registry)
+4. **Feature Services**: Start Blog, Billing, etc. (can start in parallel)
+5. **Health Checks**: All services report healthy to registry
 
 ## Request Processing Pipeline
 
-Every HTTP request flows through a standardized pipeline that ensures security, observability, and proper error handling.
+Every HTTP request flows through API Gateway first, then to backend services. The pipeline ensures security, observability, and proper error handling.
 
 ```mermaid
 graph TD
-    Start([HTTP Request]) --> Auth[Authentication Middleware]
+    Start([HTTP Request]) --> Gateway[API Gateway]
-    Auth -->|Valid Token| Authz[Authorization Middleware]
+    Gateway --> RateLimit[Rate Limiting]
+    RateLimit -->|Allowed| Auth[Validate JWT via Auth Service]
+    RateLimit -->|Exceeded| Error0[429 Too Many Requests]
+    
+    Auth -->|Valid Token| Authz[Check Permission via Authz Service]
     Auth -->|Invalid Token| Error1[401 Unauthorized]
     
     Authz -->|Authorized| RateLimit[Rate Limiting]

docs/content/index.md

@@ -4,13 +4,16 @@ Welcome to the Go Platform documentation! This is a plugin-friendly SaaS/Enterpr
 
 ## What is Go Platform?
 
-Go Platform is a modular, extensible platform designed to support multiple business domains through a plugin architecture. It provides:
+Go Platform is a microservices platform designed to support multiple business domains through independent, deployable services. It provides:
 
-- **Core Kernel**: Foundation services including authentication, authorization, configuration, logging, and observability
+- **Core Kernel**: Infrastructure only (configuration, logging, DI, health, metrics, observability) - no business logic
-- **Module Framework**: Plugin system for extending functionality
+- **Core Services**: Independent microservices (Auth, Identity, Authz, Audit) with their own entry points and databases
+- **API Gateway**: Single entry point for all external traffic, handles routing, authentication, and rate limiting
+- **Service Discovery**: Consul-based service registry for dynamic service discovery
+- **Module Framework**: Feature services (Blog, Billing, etc.) as independent services
 - **Infrastructure Adapters**: Support for databases, caching, event buses, and job scheduling
 - **Security-by-Design**: Built-in JWT authentication, RBAC/ABAC authorization, and audit logging
-- **Observability**: OpenTelemetry integration for tracing, metrics, and logging
+- **Observability**: OpenTelemetry integration for distributed tracing, metrics, and logging across services
 
 ## Documentation Structure
 
@@ -32,7 +35,8 @@ Go Platform is a modular, extensible platform designed to support multiple busin
   - **[Data Flow Patterns](architecture/data-flow-patterns.md)**: How data flows through the system
 
 ### Architecture Decision Records (ADRs)
-All architectural decisions are documented in [ADR records](adr/README.md), organized by implementation epic:
+All architectural decisions are documented in [ADR records](adr/README.md), organized by implementation epic:  
+
 - **Epic 0**: Project Setup & Foundation
 - **Epic 1**: Core Kernel & Infrastructure
 - **Epic 2**: Authentication & Authorization
@@ -43,6 +47,7 @@ All architectural decisions are documented in [ADR records](adr/README.md), orga
 
 ### Implementation Tasks
 Detailed task definitions for each epic are available in the [Stories section](stories/README.md):
+
 - **[Epic 0: Project Setup & Foundation](stories/epic0/README.md)** - [Implementation Summary](stories/epic0/SUMMARY.md)
 - **[Epic 1: Core Kernel & Infrastructure](stories/epic1/README.md)** - [Implementation Summary](stories/epic1/SUMMARY.md)
 - Epic 2: Authentication & Authorization
@@ -63,11 +68,17 @@ Detailed task definitions for each epic are available in the [Stories section](s
 
 ## Key Principles
 
-- **Hexagonal Architecture**: Clear separation between core and plugins
+- **microMicroservices Architecture**: Each service is independently deployable from day one
-- **Microservices Architecture**: Each module is an independent service from day one
+  - Core Kernel: Infrastructure only (config, logger, DI, health, metrics)
-- **Plugin-First Design**: Extensible architecture supporting static and dynamic modules
+  - Core Services: Auth, Identity, Authz, Audit as separate services
+  - Feature Services: Blog, Billing, etc. as independent services
+- **API Gateway**: Single entry point for all external traffic
+- **Service Discovery**: Consul-based service registry for dynamic service location
+- **Service Clients**: All inter-service communication via gRPC/HTTP through service clients
+- **Database Isolation**: Each service has its own database connection pool and schema
+- **Hexagonal Architecture**: Clear separation between interfaces and implementations
 - **Security-by-Design**: Built-in authentication, authorization, and audit capabilities
-- **Observability**: Comprehensive logging, metrics, and tracing
+- **Observability**: Comprehensive distributed tracing, metrics, and logging across services
 - **API-First**: OpenAPI/GraphQL schema generation
 
 ## Contributing

docs/content/plan.md

@@ -15,9 +15,13 @@ This plan breaks down the implementation into **8 epics**, each with specific de
 **Key Principles:**
 - **Hexagonal Architecture** with clear separation between `pkg/` (interfaces) and `internal/` (implementations)
 - **Dependency Injection** using `uber-go/fx` for lifecycle management
-- **Microservices Architecture** - each module is an independent service from day one
+- **microMicroservices Architecture** - each service is independently deployable from day one
+  - Core Kernel: Infrastructure only (config, logger, DI, health, metrics, observability)
+  - Core Services: Auth, Identity, Authz, Audit as separate microservices
+  - API Gateway: Single entry point for all external traffic (Epic 1)
 - **Service Client Interfaces** - all inter-service communication via gRPC/HTTP
 - **Service Discovery** - all services register and discover via service registry
+- **Database Isolation** - each service has its own database connection pool and schema
 - **Plugin-first** architecture supporting both static and dynamic module loading
 - **Security-by-Design** with JWT auth, RBAC/ABAC, and audit logging
 - **Observability** via OpenTelemetry, Prometheus, and structured logging
@@ -171,69 +175,71 @@ This plan breaks down the implementation into **8 epics**, each with specific de
 ## Epic 1: Core Kernel & Infrastructure (Week 2-3)
 
 ### Objectives
-- Extend DI container to support all core services
+- Extend DI container to support core kernel infrastructure only (no business services)
-- Implement database layer with Ent ORM
+- Implement API Gateway as core infrastructure component
+- Create service client interfaces for microservices architecture
 - Build health monitoring and metrics system
 - Create error handling and error bus
-- Establish HTTP server with comprehensive middleware stack
+- Establish HTTP/gRPC server foundation for services
 - Integrate OpenTelemetry for distributed tracing
-- Create service client interfaces for microservices architecture
+- Basic service registry implementation
+
+**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
-**Goal:** Extend the DI container to provide all core infrastructure services with proper lifecycle management.
+**Goal:** Extend the DI container to provide core kernel infrastructure services only (no business logic services).
 
 **Deliverables:**
 - Extended `internal/di/container.go` with:
-  - Registration of all core services
+  - Registration of core kernel services only
   - Lifecycle management via FX
   - Service override support for testing
 - `internal/di/providers.go` with provider functions:
   - `ProvideConfig()` - configuration provider
   - `ProvideLogger()` - logger service
-  - `ProvideDatabase()` - Ent database client
   - `ProvideHealthCheckers()` - health check registry
   - `ProvideMetrics()` - Prometheus metrics registry
   - `ProvideErrorBus()` - error bus service
-- `internal/di/core_module.go` exporting `CoreModule` fx.Option that provides all core services
+  - `ProvideTracer()` - OpenTelemetry tracer
+  - `ProvideServiceRegistry()` - service registry interface
+- `internal/di/core_module.go` exporting `CoreModule` fx.Option that provides all core kernel services
+
+**Note:** Database, Auth, Identity, Authz, Audit are NOT in core kernel - they are separate services implemented in Epic 2.
 
 **Acceptance Criteria:**
-- All core services are provided via DI container
+- All core kernel 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
+- No business logic services in core kernel
 
-#### 1.2 Database Layer with Ent ORM
+#### 1.2 Database Client Foundation
-**Goal:** Set up a complete database layer using Ent ORM with core domain entities, migrations, and connection management.
+**Goal:** Set up database client foundation for services. Each service will have its own database connection and schema.
 
 **Deliverables:**
-- Ent schema initialization and core entities:
+- Database client wrapper in `internal/infra/database/client.go`:
-  - `User` entity: ID, email, password_hash, verified, created_at, updated_at
+  - `NewEntClient(dsn string, schema string) (*ent.Client, error)` - supports schema isolation
-  - `Role` entity: ID, name, description, created_at
-  - `Permission` entity: ID, name (format: "module.resource.action")
-  - `AuditLog` entity: ID, actor_id, action, target_id, metadata (JSON), timestamp
-  - Many-to-many relationships: `role_permissions` and `user_roles`
-- Generated Ent code with proper type safety
-- Database client in `internal/infra/database/client.go`:
-  - `NewEntClient(dsn string) (*ent.Client, error)`
   - Connection pooling configuration (max connections, idle timeout)
   - Migration runner wrapper
   - Database health check integration
+  - Per-service connection pool management
 - Database configuration in `config/default.yaml` with:
   - Connection string (DSN)
-  - Connection pool settings
+  - Connection pool settings per service
-  - Migration settings
+  - Schema isolation configuration
+- Database client factory for creating service-specific clients
+
+**Note:** Core domain entities (User, Role, Permission, AuditLog) are implemented in Epic 2 as part of their respective services (Identity, Authz, Audit).
 
 **Acceptance Criteria:**
-- Ent schema compiles and generates code successfully
+- Database client connects to PostgreSQL with schema support
-- 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
+- Multiple services can connect to same database instance with different schemas
+- Each service manages its own connection pool
 
 #### 1.3 Health Monitoring and Metrics System
 **Goal:** Implement comprehensive health checks and Prometheus metrics for monitoring platform health and performance.
@@ -289,13 +295,13 @@ This plan breaks down the implementation into **8 epics**, each with specific de
 - Error context (request ID, user ID) is preserved
 - Background error consumer works correctly
 
-#### 1.5 HTTP Server Foundation with Middleware Stack
+#### 1.5 HTTP/gRPC Server Foundation
-**Goal:** Create a production-ready HTTP server with comprehensive middleware for security, observability, and error handling.
+**Goal:** Create HTTP and gRPC server foundation that services can use. Each service will have its own server instance.
 
 **Deliverables:**
-- HTTP server in `internal/server/server.go`:
+- HTTP server foundation in `internal/server/http.go`:
-  - Gin router initialization
+  - Gin router initialization helper
-  - Comprehensive middleware stack:
+  - Common middleware stack:
     - Request ID generator (unique per request)
     - Structured logging middleware (logs all requests)
     - Panic recovery → error bus
@@ -303,28 +309,54 @@ This plan breaks down the implementation into **8 epics**, each with specific de
     - CORS support (configurable)
     - Request timeout handling
     - Response compression
-  - Core route registration:
+  - Server lifecycle management
-    - `GET /healthz` - liveness probe
+- gRPC server foundation in `internal/server/grpc.go`:
-    - `GET /ready` - readiness probe
+  - gRPC server initialization
-    - `GET /metrics` - Prometheus metrics
+  - Interceptor support (logging, tracing, metrics)
-- FX lifecycle integration:
+  - Lifecycle management
-  - HTTP server starts on `OnStart` hook
+- FX lifecycle integration for both HTTP and gRPC servers
-  - Graceful shutdown on `OnStop` hook (drains connections)
+
-  - Port configuration from config
+**Note:** Services (Auth, Identity, etc.) will use these foundations to create their own server instances in Epic 2.
-- Integration with main application entry point
 
 **Acceptance Criteria:**
-- HTTP server starts successfully
+- HTTP server foundation is reusable by services
+- gRPC server foundation is reusable by services
 - 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
+- Servers are configurable via config system
-- CORS is configurable per environment
 
 #### 1.6 OpenTelemetry Distributed Tracing
-**Goal:** Integrate OpenTelemetry for distributed tracing across the platform to enable observability in production.
+**Goal:** Integrate OpenTelemetry for distributed tracing across all services to enable observability in production.
+
+**Deliverables:**
+- OpenTelemetry setup in `internal/observability/tracer.go`:
+  - TracerProvider initialization
+  - Export to stdout (development mode)
+  - Export to OTLP collector (production mode)
+  - Trace context propagation
+- HTTP instrumentation middleware:
+  - Automatic span creation for HTTP requests
+  - Trace context propagation via headers
+  - Span attributes (method, path, status code, etc.)
+- gRPC instrumentation:
+  - gRPC interceptor for automatic span creation
+  - Trace context propagation via gRPC metadata
+- Database instrumentation:
+  - Ent interceptor for database queries
+  - Query spans with timing and parameters
+- Integration with logger (include trace ID in logs)
+
+**Acceptance Criteria:**
+- HTTP requests create OpenTelemetry spans
+- gRPC calls 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
 
 #### 1.7 Service Client Interfaces
 **Goal:** Create service client interfaces for all core services to enable microservices communication.
@@ -334,7 +366,6 @@ This plan breaks down the implementation into **8 epics**, each with specific de
   - `IdentityServiceClient` - User and identity operations
   - `AuthServiceClient` - Authentication operations
   - `AuthzServiceClient` - Authorization operations
-  - `PermissionServiceClient` - Permission resolution
   - `AuditServiceClient` - Audit logging
 - Service client factory in `internal/services/factory.go`:
   - Create gRPC clients (primary)
@@ -351,69 +382,89 @@ This plan breaks down the implementation into **8 epics**, each with specific de
 - Configuration supports protocol selection
 - All inter-service communication goes through service clients
 
+#### 1.8 API Gateway Implementation
+**Goal:** Implement API Gateway as core infrastructure component that routes all external traffic to backend services.
+
 **Deliverables:**
-- OpenTelemetry setup in `internal/observability/tracer.go`:
+- API Gateway service entry point: `cmd/api-gateway/main.go`
-  - TracerProvider initialization
+- Gateway implementation in `services/gateway/internal/`:
-  - Export to stdout (development mode)
+  - Request routing to backend services via service discovery
-  - Export to OTLP collector (production mode)
+  - JWT token validation via Auth Service client
-  - Trace context propagation
+  - Permission checking via Authz Service client (optional, for route-level auth)
-- HTTP instrumentation middleware:
+  - Rate limiting middleware (per-user and per-IP)
-  - Automatic span creation for HTTP requests
+  - CORS support
-  - Trace context propagation via headers
+  - Request/response transformation
-  - Span attributes (method, path, status code, etc.)
+  - Load balancing across service instances
-- Database instrumentation:
+- Gateway configuration in `config/default.yaml`:
-  - Ent interceptor for database queries
+  - Route definitions (path → service mapping)
-  - Query spans with timing and parameters
+  - Rate limiting configuration
-- Integration with logger (include trace ID in logs)
+  - CORS configuration
+- Integration with service registry for service discovery
+- Health check endpoint for gateway
 
 **Acceptance Criteria:**
-- HTTP requests create OpenTelemetry spans
+- API Gateway routes requests to backend services correctly
-- Database queries are traced
+- JWT validation works via Auth Service
-- Trace context propagates across service boundaries
+- Rate limiting works correctly
-- Trace IDs are included in logs
+- CORS is configurable and works
-- Traces export correctly to configured backend
+- Service discovery integration works
-- Tracing works in both development and production modes
+- Gateway is independently deployable
-- Tracing has minimal performance impact
+- Gateway has health check endpoint
+- All external traffic goes through gateway
 
 ### Deliverables
-- ✅ DI container with all core services
+- ✅ DI container with core kernel services only
-- ✅ Database client with Ent schema
+- ✅ Database client foundation (per-service connections)
 - ✅ Health and metrics endpoints functional
 - ✅ Error bus captures and logs errors
-- ✅ HTTP server with middleware stack
+- ✅ HTTP/gRPC server foundation for services
 - ✅ Basic observability with OpenTelemetry
 - ✅ Service client interfaces for microservices
+- ✅ API Gateway service (core infrastructure)
+- ✅ Basic service registry implementation
 
 ### Acceptance Criteria
-- `GET /healthz` returns 200
+- `GET /healthz` returns 200 for all services
-- `GET /ready` checks DB connectivity
+- `GET /ready` checks service health
 - `GET /metrics` exposes Prometheus metrics
 - Panic recovery logs errors via error bus
-- Database migrations run on startup
+- HTTP/gRPC requests are traced with OpenTelemetry
-- HTTP requests are traced with OpenTelemetry
+- API Gateway routes requests to backend services
+- Service client interfaces are defined
+- No business logic services in Epic 1
 
 ---
 
-## Epic 2: Authentication & Authorization (Week 3-4)
+## Epic 2: Core Services (Authentication & Authorization) (Week 3-5)
 
 ### Objectives
-- Implement complete JWT-based authentication system
+- Separate Auth, Identity, Authz, and Audit into independent microservices
-- Build comprehensive identity management with user lifecycle
+- Each service has its own entry point, database connection, and gRPC server
-- Create role-based access control (RBAC) system
+- Implement complete JWT-based authentication system (Auth Service)
-- Implement authorization middleware and permission checks
+- Build comprehensive identity management with user lifecycle (Identity Service)
+- Create role-based access control (RBAC) system (Authz Service)
+- Implement audit logging system (Audit Service)
+- All services communicate via service clients (gRPC/HTTP)
+- All services register with service registry
+
+**Note:** This epic transforms the monolithic core into separate, independently deployable services.
 - Add comprehensive audit logging for security compliance
 - Provide database seeding for initial setup
 
 ### Stories
 
-#### 2.1 JWT Authentication System
+#### 2.1 Auth Service - JWT Authentication
-**Goal:** Implement a complete JWT-based authentication system with access tokens, refresh tokens, and secure token management.
+**Goal:** Implement Auth Service as an independent microservice with complete JWT-based authentication system, access tokens, refresh tokens, and secure token management.
 
 **Deliverables:**
-- Authentication interfaces in `pkg/auth/auth.go`:
+- Auth Service entry point: `cmd/auth-service/main.go`
-  - `Authenticator` interface for token generation and verification
+- Service implementation in `services/auth/internal/`:
-  - `TokenClaims` struct with user ID, roles, tenant ID, expiration
+  - gRPC server for Auth Service
-- JWT implementation in `internal/auth/jwt_auth.go`:
+  - HTTP endpoints (optional, for compatibility)
+- Authentication interfaces in `pkg/services/auth.go`:
+  - `AuthServiceClient` interface for authentication operations
+  - Service client implementation (gRPC/HTTP)
+- JWT implementation in `services/auth/internal/jwt_auth.go`:
   - Generate short-lived access tokens (15 minutes)
   - Generate long-lived refresh tokens (7 days)
   - Token signature verification
@@ -424,29 +475,41 @@ This plan breaks down the implementation into **8 epics**, each with specific de
   - Verify token validity
   - Inject authenticated user into request context
   - Helper function: `auth.FromContext(ctx) *User`
-- Authentication endpoints:
+- gRPC service definition: `services/auth/api/auth.proto`
-  - `POST /api/v1/auth/login` - Authenticate user and return tokens
+- Authentication endpoints (gRPC):
-  - `POST /api/v1/auth/refresh` - Refresh access token using refresh token
+  - `Login(email, password)` - Authenticate user and return tokens
-  - Password validation against stored hashes
+  - `RefreshToken(refresh_token)` - Refresh access token using refresh token
-- Integration with DI container and HTTP server
+  - `ValidateToken(token)` - Validate JWT token (used by API Gateway)
+  - Password validation against stored hashes (via Identity Service)
+- Database connection: Own connection pool and schema (`auth_schema`)
+- Service registration: Register with service registry
+- Integration with Identity Service: Use `IdentityServiceClient` for user lookup
 
 **Acceptance Criteria:**
-- Users can login and receive access and refresh tokens
+- Auth Service is independently deployable
+- Service has own entry point (`cmd/auth-service/`)
+- gRPC server starts and serves authentication requests
+- Users can login via gRPC and receive access and refresh tokens
 - Access tokens expire after configured duration
 - Refresh tokens can be used to obtain new access tokens
+- Token validation works (used by API Gateway)
 - Invalid tokens are rejected with appropriate errors
-- Authenticated user is available in request context
+- Service registers with service registry
-- Login attempts are logged
+- Service uses Identity Service client for user lookup
-- Token secrets are configurable
+- Service has own database connection and schema
 
-#### 2.2 Identity Management System
+#### 2.2 Identity Service - User Management
-**Goal:** Build a complete user identity management system with registration, email verification, password management, and user CRUD operations.
+**Goal:** Implement Identity Service as an independent microservice with complete user identity management, registration, email verification, password management, and user CRUD operations.
 
 **Deliverables:**
-- Identity interfaces in `pkg/identity/identity.go`:
+- Identity Service entry point: `cmd/identity-service/main.go`
-  - `UserRepository` interface for user data access
+- Service implementation in `services/identity/internal/`:
-  - `UserService` interface for user business logic
+  - gRPC server for Identity Service
-- User repository implementation in `internal/identity/user_repo.go`:
+  - HTTP endpoints (optional, for compatibility)
+- Identity interfaces in `pkg/services/identity.go`:
+  - `IdentityServiceClient` interface for user operations
+  - Service client implementation (gRPC/HTTP)
+- User repository implementation in `services/identity/internal/user_repo.go`:
   - CRUD operations using Ent
   - Password hashing (bcrypt or argon2)
   - Email uniqueness validation
@@ -457,24 +520,34 @@ This plan breaks down the implementation into **8 epics**, each with specific de
   - Password reset flow (token-based, time-limited)
   - Password change with old password verification
   - User profile updates
-- User management API endpoints:
+- gRPC service definition: `services/identity/api/identity.proto`
-  - `POST /api/v1/users` - Register new user
+- User management endpoints (gRPC):
-  - `GET /api/v1/users/:id` - Get user profile (authorized)
+  - `CreateUser(user)` - Register new user
-  - `PUT /api/v1/users/:id` - Update user profile (authorized)
+  - `GetUser(id)` - Get user profile
-  - `DELETE /api/v1/users/:id` - Delete user (admin only)
+  - `UpdateUser(id, user)` - Update user profile
-  - `POST /api/v1/users/verify-email` - Verify email with token
+  - `DeleteUser(id)` - Delete user (admin only)
-  - `POST /api/v1/users/reset-password` - Request password reset
+  - `GetUserByEmail(email)` - Get user by email
-  - `POST /api/v1/users/change-password` - Change password
+  - `VerifyEmail(token)` - Verify email with token
-- Integration with email notification system (Epic 5)
+  - `RequestPasswordReset(email)` - Request password reset
+  - `ResetPassword(token, new_password)` - Reset password
+  - `ChangePassword(user_id, old_password, new_password)` - Change password
+- Database connection: Own connection pool and schema (`identity_schema`)
+- Ent schema: User entity in `services/identity/ent/schema/user.go`
+- Service registration: Register with service registry
+- Integration with email notification system (Epic 5) via event bus
 
 **Acceptance Criteria:**
-- Users can register with email and password
+- Identity Service is independently deployable
+- Service has own entry point (`cmd/identity-service/`)
+- gRPC server starts and serves user management requests
+- Users can register via gRPC 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
+- Users can update their profiles via gRPC
-- User operations require proper authentication
+- Service registers with service registry
-- All user actions are audited
+- Service has own database connection and schema
+- User entity is properly defined in Ent schema
 
 #### 2.3 Role-Based Access Control (RBAC) System
 **Goal:** Implement a complete RBAC system with permissions, role management, and authorization middleware.
@@ -1449,11 +1522,13 @@ This plan breaks down the implementation into **8 epics**, each with specific de
 ## Epic 8: Advanced Features & Polish (Week 9-10, Optional)
 
 ### Objectives
-- Add advanced features (OIDC, GraphQL, API Gateway)
+- Add advanced features (OIDC, GraphQL)
 - Performance optimization
-- Additional sample modules
+- Additional sample feature services
 - Final polish and bug fixes
 
+**Note:** API Gateway is now in Epic 1 (Story 1.8) as core infrastructure, not an advanced feature.
+
 ### Tasks
 
 #### 8.1 OpenID Connect (OIDC) Support
@@ -1479,30 +1554,26 @@ This plan breaks down the implementation into **8 epics**, each with specific de
   - Add authorization checks
 - [ ] Add GraphQL endpoint: `POST /graphql`
 
-#### 8.3 API Gateway Features
+#### 8.3 Additional Sample Feature Services
-- [ ] Add request/response transformation
+- [ ] Create Notification Service (`cmd/notification-service/`):
-- [ ] Add API key authentication
+  - Service entry point, gRPC server
-- [ ] Add request routing rules
-- [ ] Add API versioning support
-
-#### 8.4 Additional Sample Modules
-- [ ] Create `modules/notification/`:
   - Email templates
   - Notification preferences
   - Notification history
-- [ ] Create `modules/analytics/`:
+- [ ] Create Analytics Service (`cmd/analytics-service/`):
+  - Service entry point, gRPC server
   - Event tracking
   - Analytics dashboard API
   - Export functionality
 
-#### 8.5 Performance Optimization
+#### 8.4 Performance Optimization
 - [ ] Add database query caching
 - [ ] Optimize N+1 queries
 - [ ] Add response caching (Redis)
 - [ ] Implement connection pooling optimizations
 - [ ] Add database read replicas support
 
-#### 8.6 Internationalization (i18n)
+#### 8.5 Internationalization (i18n)
 - [ ] Install i18n library
 - [ ] Add locale detection:
   - From Accept-Language header
@@ -1510,7 +1581,7 @@ This plan breaks down the implementation into **8 epics**, each with specific de
 - [ ] Create message catalogs
 - [ ] Add translation support for error messages
 
-#### 8.7 Final Polish
+#### 8.6 Final Polish
 - [ ] Code review and refactoring
 - [ ] Bug fixes
 - [ ] Performance profiling
@@ -1520,7 +1591,7 @@ This plan breaks down the implementation into **8 epics**, each with specific de
 ### Deliverables
 - ✅ OIDC support (optional)
 - ✅ GraphQL API (optional)
-- ✅ Additional sample modules
+- ✅ Additional sample feature services (Notification, Analytics)
 - ✅ Performance optimizations
 - ✅ Final polish
 

docs/content/playbook.md

@@ -7,7 +7,7 @@
 |-----------|-----------------------|------------------------|
 | **Hexagonal Architecture** | Go’s package‑level visibility (`internal/`) naturally creates a *boundary* between core and plug‑ins. | Keep all **domain** code in `internal/domain`, expose only **interfaces** in `pkg/`. |
 | **Dependency Injection (DI) via Constructors** | Go avoids reflection‑heavy containers; compile‑time wiring is preferred. | Use **uber‑go/fx** (runtime graph) *or* **uber‑go/dig** for optional runtime DI. For a lighter weight solution, use plain **constructor injection** with a small **registry**. |
-| **Modular Monolith → Micro‑service‑ready** | A single binary is cheap in Go; later you can extract modules into separate services without breaking APIs. | Each module lives in its own Go **module** (`go.mod`) under `./modules/*`. The core loads them via the **Go plugin** system *or* static registration (preferred for CI stability). |
+| **microMicroservices Architecture** | Each service is independently deployable from day one. Services communicate via gRPC/HTTP through service clients. | Each service has its own entry point (`cmd/{service}/`), Go module (`go.mod`), database connection, and deployment. Services discover each other via Consul service registry. |
 | **Plugin‑first design** | Go’s `plugin` package allows runtime loading of compiled `.so` files (Linux/macOS). | Provide an **IModule** interface and a **loader** that discovers `*.so` files (or compiled‑in modules for CI). |
 | **API‑First (OpenAPI + gin/gorilla)** | Guarantees language‑agnostic contracts. | Generate server stubs from an `openapi.yaml` stored in `api/`. |
 | **Security‑by‑Design** | Go’s static typing makes it easy to keep auth data out of the request flow. | Central middleware for JWT verification + context‑based user propagation. |
@@ -18,25 +18,47 @@
 
 ---
 
-## 2 CORE KERNEL (What every Go‑platform must ship)
+## 2 CORE KERNEL (Infrastructure Only)
 
-| Module | Public Interfaces (exported from `pkg/`) | Recommended Packages | Brief Implementation Sketch |
+The core kernel provides foundational infrastructure that all services depend on. It contains **no business logic**.
+
+| Component | Public Interfaces (exported from `pkg/`) | Recommended Packages | Brief Implementation Sketch |
 |--------|-------------------------------------------|----------------------|------------------------------|
 | **Config** | `type ConfigProvider interface { Get(key string) any; Unmarshal(v any) error }` | `github.com/spf13/viper` | Load defaults (`config/default.yaml`), then env overrides, then optional secret‑store. |
-| **Logger** | `type Logger interface { Debug(msg string, fields ...Field); Info(...); Error(...); With(fields ...Field) Logger }` | `go.uber.org/zap` (or `zerolog`) | Global logger is created in `cmd/main.go`; exported via `pkg/logger`. |
+| **Logger** | `type Logger interface { Debug(msg string, fields ...Field); Info(...); Error(...); With(fields ...Field) Logger }` | `go.uber.org/zap` (or `zerolog`) | Global logger is created in each service's `cmd/{service}/main.go`; exported via `pkg/logger`. |
-| **DI / Service Registry** | `type Container interface { Provide(constructor any) error; Invoke(fn any) error }` | `go.uber.org/dig` (or `fx` for lifecycle) | Core creates a `dig.New()` container, registers core services, then calls `container.Invoke(app.Start)`. |
+| **DI / Service Registry** | `type Container interface { Provide(constructor any) error; Invoke(fn any) error }` | `go.uber.org/fx` (for lifecycle) | Each service creates its own `fx.New()` container, registers service-specific services. |
-| **Health & Metrics** | `type HealthChecker interface { Check(ctx context.Context) error }` | `github.com/prometheus/client_golang/prometheus`, `github.com/heptiolabs/healthcheck` | Expose `/healthz`, `/ready`, `/metrics`. |
+| **Health & Metrics** | `type HealthChecker interface { Check(ctx context.Context) error }` | `github.com/prometheus/client_golang/prometheus`, `github.com/heptiolabs/healthcheck` | Each service exposes `/healthz`, `/ready`, `/metrics`. |
-| **Error Bus** | `type ErrorPublisher interface { Publish(err error) }` | Simple channel‐based implementation + optional Sentry (`github.com/getsentry/sentry-go`) | Core registers a singleton `ErrorBus`. |
+| **Error Bus** | `type ErrorPublisher interface { Publish(err error) }` | Simple channel‐based implementation + optional Sentry (`github.com/getsentry/sentry-go`) | Each service registers its own `ErrorBus`. |
-| **Auth (JWT + OIDC)** | `type Authenticator interface { GenerateToken(userID string, roles []string) (string, error); VerifyToken(token string) (*TokenClaims, error) }` | `github.com/golang-jwt/jwt/v5`, `github.com/coreos/go-oidc` | Token claims embed `sub`, `roles`, `tenant_id`. Middleware adds `User` to `context.Context`. |
+| **Service Registry** | `type ServiceRegistry interface { Register(ctx, service) error; Discover(ctx, name) ([]Service, error) }` | `github.com/hashicorp/consul/api` | Consul-based service discovery. Services register on startup, clients discover via registry. |
-| **Authorization (RBAC/ABAC)** | `type Authorizer interface { Authorize(ctx context.Context, perm Permission) error }` | Custom DSL, `github.com/casbin/casbin/v2` (optional) | Permission format: `"module.resource.action"`; core ships a simple in‑memory resolver and a `casbin` adapter. |
+| **Observability** | `type Tracer interface { StartSpan(ctx, name) (Span, context.Context) }` | `go.opentelemetry.io/otel` | OpenTelemetry integration for distributed tracing across services. |
-| **Audit** | `type Auditor interface { Record(ctx context.Context, act AuditAction) error }` | Write to append‑only table (Postgres) or Elastic via `olivere/elastic` | Audits include `actorID`, `action`, `targetID`, `metadata`. |
+| **Event Bus** | `type EventBus interface { Publish(ctx context.Context, ev Event) error; Subscribe(topic string, handler EventHandler) }` | `github.com/segmentio/kafka-go` | Kafka-based event bus for asynchronous cross-service communication. |
-| **Event Bus** | `type EventBus interface { Publish(ctx context.Context, ev Event) error; Subscribe(topic string, handler EventHandler) }` | `github.com/segmentio/kafka-go` (for production) + in‑process fallback | Core ships an **in‑process bus** used by tests and a **Kafka bus** for real deployments. |
+| **Scheduler / Background Jobs** | `type Scheduler interface { Cron(spec string, job JobFunc) error; Enqueue(q string, payload any) error }` | `github.com/robfig/cron/v3`, `github.com/hibiken/asynq` (Redis‑backed) | Shared infrastructure for background jobs. |
-| **Persistence (Repository)** | `type UserRepo interface { FindByID(id string) (*User, error); Create(u *User) error; … }` | `entgo.io/ent` (code‑gen ORM) **or** `gorm.io/gorm` | Core provides an `EntClient` wrapper that implements all core repos. |
+| **Notification** | `type Notifier interface { Send(ctx context.Context, n Notification) error }` | `github.com/go-mail/mail` (SMTP), `github.com/aws/aws-sdk-go-v2/service/ses` | Shared infrastructure for notifications. |
-| **Scheduler / Background Jobs** | `type Scheduler interface { Cron(spec string, job JobFunc) error; Enqueue(q string, payload any) error }` | `github.com/robfig/cron/v3`, `github.com/hibiken/asynq` (Redis‑backed) | Expose a `JobRegistry` where modules can register periodic jobs. |
+| **Multitenancy (optional)** | `type TenantResolver interface { Resolve(ctx context.Context) (tenantID string, err error) }` | Header/ sub‑domain parser + JWT claim scanner | Tenant ID is stored in request context and automatically added to SQL queries via Ent's `Client` interceptor. |
-| **Notification** | `type Notifier interface { Send(ctx context.Context, n Notification) error }` | `github.com/go-mail/mail` (SMTP), `github.com/aws/aws-sdk-go-v2/service/ses`, `github.com/IBM/sarama` (for push) | Core supplies an `EmailNotifier` and a `WebhookNotifier`. |
-| **Multitenancy (optional)** | `type TenantResolver interface { Resolve(ctx context.Context) (tenantID string, err error) }` | Header/ sub‑domain parser + JWT claim scanner | Tenant ID is stored in request context and automatically added to SQL queries via Ent’s `Client` interceptor. |
 
-All *public* interfaces live under `pkg/` so that plug‑ins can import them without pulling in implementation details. The concrete implementations stay in `internal/` (or separate go.mod modules) and are **registered with the container** during bootstrap.
+## 2.1 CORE SERVICES (Independent Microservices)
+
+Core business services are implemented as separate, independently deployable services:
+
+| Service | Entry Point | Responsibilities | Service Client Interface |
+|--------|-------------|------------------|-------------------------|
+| **Auth Service** | `cmd/auth-service/` | JWT token generation/validation, authentication | `AuthServiceClient` in `pkg/services/auth.go` |
+| **Identity Service** | `cmd/identity-service/` | User CRUD, password management, email verification | `IdentityServiceClient` in `pkg/services/identity.go` |
+| **Authz Service** | `cmd/authz-service/` | Permission resolution, RBAC/ABAC authorization | `AuthzServiceClient` in `pkg/services/authz.go` |
+| **Audit Service** | `cmd/audit-service/` | Audit logging, immutable audit records | `AuditServiceClient` in `pkg/services/audit.go` |
+| **API Gateway** | `cmd/api-gateway/` | Request routing, authentication, rate limiting, CORS | N/A (entry point) |
+
+Each service:
+
+- Has its own `go.mod` (or shared workspace)
+- Manages its own database connection pool and schema
+- Exposes gRPC server (and optional HTTP)
+- Registers with Consul service registry
+- Uses service clients for inter-service communication
+
+All *public* interfaces live under `pkg/` so that services can import them without pulling in implementation details. The concrete implementations stay in `internal/` (for core kernel) or `services/{service}/internal/` (for service implementations) and are **registered with the container** during service bootstrap.
+
+**Note:** Business logic services (Auth, Identity, Authz, Audit) are NOT in the core kernel. They are separate services implemented in Epic 2.
 
 ---
 
@@ -167,13 +189,21 @@ A **code‑gen** tool (`go generate ./...`) can scan each module’s `module.yam
 
 ---
 
-## 4 SAMPLE FEATURE MODULE – **Blog**
+## 4 SAMPLE FEATURE SERVICE – **Blog Service**
+
+Each feature module is implemented as an independent service:
 
 ```
-modules/
+cmd/
+└─ blog-service/
+   └─ main.go              # Service entry point
+
+services/
 └─ blog/
-   ├─ go.mod               # (module github.com/yourorg/blog)
+   ├─ go.mod               # Service dependencies
-   ├─ module.yaml
+   ├─ module.yaml          # Service manifest
+   ├─ api/
+   │   └─ blog.proto       # gRPC service definition
    ├─ internal/
    │   ├─ api/
    │   │   └─ handler.go
@@ -207,74 +237,165 @@ routes:
     permission: blog.post.read
 ```
 
-### 4.2 Go implementation
+### 4.2 Service Entry Point
 
 ```go
-// pkg/module.go
+// cmd/blog-service/main.go
-package blog
+package main
 
 import (
-    "github.com/yourorg/platform/pkg/module"
+    "context"
+    "github.com/yourorg/platform/internal/config"
+    "github.com/yourorg/platform/internal/di"
+    "github.com/yourorg/platform/services/blog/internal/api"
+    "github.com/yourorg/platform/services/blog/internal/service"
     "go.uber.org/fx"
 )
 
-type BlogModule struct{}
+func main() {
-
+    cfg := config.Load()
-func (b BlogModule) Name() string { return "blog" }
+    
-
+    fx.New(
-func (b BlogModule) Init() fx.Option {
+        // Core kernel services
-    return fx.Options(
+        di.CoreModule(cfg),
-        // Register repository implementation
+        
-        fx.Provide(NewPostRepo),
+        // Blog service implementation
-
+        fx.Provide(service.NewPostService),
-        // Register service layer
+        fx.Provide(service.NewPostRepo),
-        fx.Provide(NewPostService),
+        
-
+        // gRPC server
-        // Register HTTP handlers (using Gin)
+        fx.Provide(api.NewGRPCServer),
-        fx.Invoke(RegisterHandlers),
+        
-
+        // Service registry
-        // Register permissions (optional – just for documentation)
+        fx.Provide(di.ProvideServiceRegistry),
-        fx.Invoke(RegisterPermissions),
+        
-    )
+        // Start service
+        fx.Invoke(startService),
+    ).Run()
 }
 
-func (b BlogModule) Migrations() []func(*ent.Client) error {
+func startService(lc fx.Lifecycle, server *api.GRPCServer, registry registry.ServiceRegistry) {
-    // Ent migration generated in internal/ent/migrate
+    lc.Append(fx.Hook{
-    return []func(*ent.Client) error{
+        OnStart: func(ctx context.Context) error {
-        func(c *ent.Client) error { return c.Schema.Create(context.Background()) },
+            // Register with Consul
+            registry.Register(ctx, &registry.ServiceInstance{
+                ID:      "blog-service-1",
+                Name:    "blog-service",
+                Address: "localhost",
+                Port:    8091,
+            })
+            
+            // Start gRPC server
+            return server.Start()
+        },
+        OnStop: func(ctx context.Context) error {
+            registry.Deregister(ctx, "blog-service-1")
+            return server.Stop()
+        },
+    })
+}
+```
+
+### 4.3 Service Implementation
+
+```go
+// services/blog/internal/service/post_service.go
+package service
+
+import (
+    "context"
+    "github.com/yourorg/platform/pkg/services"
+    "github.com/yourorg/platform/services/blog/internal/domain"
+)
+
+type PostService struct {
+    repo          *domain.PostRepo
+    authzClient   services.AuthzServiceClient
+    identityClient services.IdentityServiceClient
+    auditClient   services.AuditServiceClient
+}
+
+func NewPostService(
+    repo *domain.PostRepo,
+    authzClient services.AuthzServiceClient,
+    identityClient services.IdentityServiceClient,
+    auditClient services.AuditServiceClient,
+) *PostService {
+    return &PostService{
+        repo:          repo,
+        authzClient:   authzClient,
+        identityClient: identityClient,
+        auditClient:   auditClient,
     }
 }
 
-// Export a variable for the plugin loader
+func (s *PostService) CreatePost(ctx context.Context, req *CreatePostRequest) (*Post, error) {
-var Module BlogModule
+    // Check permission via Authz Service
+    if err := s.authzClient.Authorize(ctx, "blog.post.create"); err != nil {
+        return nil, err
+    }
+    
+    // Get user info via Identity Service
+    user, err := s.identityClient.GetUser(ctx, req.AuthorID)
+    if err != nil {
+        return nil, err
+    }
+    
+    // Create post
+    post, err := s.repo.Create(ctx, &domain.Post{
+        Title:    req.Title,
+        Content:  req.Content,
+        AuthorID: user.ID,
+    })
+    if err != nil {
+        return nil, err
+    }
+    
+    // Audit log via Audit Service
+    s.auditClient.Record(ctx, &services.AuditAction{
+        ActorID:  user.ID,
+        Action:   "blog.post.create",
+        TargetID: post.ID,
+    })
+    
+    return post, nil
+}
 ```
 
-**Handler registration (Gin example)**
+### 4.4 gRPC Handler
 
 ```go
-// internal/api/handler.go
+// services/blog/internal/api/handler.go
 package api
 
 import (
-    "github.com/gin-gonic/gin"
+    "context"
-    "github.com/yourorg/blog/internal/service"
+    "github.com/yourorg/platform/services/blog/api/pb"
-    "github.com/yourorg/platform/pkg/perm"
+    "github.com/yourorg/platform/services/blog/internal/service"
-    "github.com/yourorg/platform/pkg/auth"
 )
 
-func RegisterHandlers(r *gin.Engine, svc *service.PostService, authz auth.Authorizer) {
+type BlogServer struct {
-    grp := r.Group("/api/v1/blog")
+    pb.UnimplementedBlogServiceServer
-    grp.Use(auth.AuthMiddleware()) // verifies JWT, injects user in context
+    service *service.PostService
+}
 
-    // POST /posts
+func (s *BlogServer) CreatePost(ctx context.Context, req *pb.CreatePostRequest) (*pb.CreatePostResponse, error) {
-    grp.POST("/posts", func(c *gin.Context) {
+    post, err := s.service.CreatePost(ctx, &service.CreatePostRequest{
-        if err := authz.Authorize(c.Request.Context(), perm.BlogPostCreate); err != nil {
+        Title:    req.Title,
-            c.JSON(403, gin.H{"error": "forbidden"})
+        Content:  req.Content,
-            return
+        AuthorID: req.AuthorId,
-        }
-        // decode request, call svc.Create, return 201…
     })
-    // GET /posts/:id (similar)
+    if err != nil {
+        return nil, err
+    }
+    
+    return &pb.CreatePostResponse{
+        Post: &pb.Post{
+            Id:      post.ID,
+            Title:   post.Title,
+            Content: post.Content,
+        },
+    }, nil
 }
 ```
 

docs/content/requirements.md

@@ -6,7 +6,7 @@
 |-----------|----------------------------------------|-------------------|
 | **Separation of Concerns (SoC)** | Keeps core services (auth, audit, config) independent from business modules. | Use **layered** or **hexagonal/clean‑architecture** boundaries. |
 | **Domain‑Driven Design (DDD) Bounded Contexts** | Allows each module to own its own model & rules while sharing a common identity kernel. | Define a **Core Context** (Identity, Security, Infrastructure) and **Feature Contexts** (Billing, CMS, Chat, …). |
-| **Modular Monolith → Micro‑service‑ready** | Start simple (single process) but keep each module in its own package so you can later split to services if needed. | Package each module as an **independent library** with its own **DI container‑module** and **routing**. |
+| **microMicroservices Architecture** | Each service is independently deployable from day one. Services communicate via gRPC/HTTP through service clients. | Each service has its own entry point (`cmd/{service}/`), database connection, and deployment configuration. |
 | **Plug‑in / Extension‑point model** | Enables customers or internal teams to drop new features without touching core code. | Export **well‑defined interfaces** (e.g., `IUserProvider`, `IPermissionResolver`, `IModuleInitializer`). |
 | **API‑First** | Guarantees that any UI (web, mobile, CLI) can be built on top of the same contract. | Publish **OpenAPI/GraphQL schema** as part of the build artefact. |
 | **Security‑by‑Design** | The platform will hold user credentials, roles and possibly PII. | Centralize **authentication**, **authorization**, **audit**, **rate‑limiting**, **CORS**, **CSP**, **secure defaults**. |
@@ -50,7 +50,17 @@
 
 ---
 
-## REQUIRED BASE MODULES (THE “CORE KERNEL”)
+## CORE KERNEL (INFRASTRUCTURE ONLY)
+
+The core kernel provides foundational infrastructure services that all other services depend on. It contains **no business logic** and is purely infrastructure.
+
+## CORE SERVICES (INDEPENDENT MICROSERVICES)
+
+Core services provide business logic and are deployed as separate, independently scalable services. Each service has its own database connection, API endpoints, and deployment configuration.
+
+## INFRASTRUCTURE ADAPTERS (SHARED SERVICES)
+
+These adapters provide infrastructure capabilities that services can use.
 
 | Module | Core responsibilities | Public API / Extension points |
 |--------|-----------------------|--------------------------------|
@@ -128,38 +138,65 @@
 ```
 /platform-root
 │
-├─ /core                                   # ---- Kernel / Base modules ----
+├─ /cmd                                    # ---- Service Entry Points ----
-│   ├─ /auth
+│   ├─ /api-gateway                        # API Gateway service
-│   │   ├─ src/
+│   │   └─ main.go
-│   │   └─ package.json
+│   ├─ /auth-service                       # Auth service
-│   ├─ /identity
+│   │   └─ main.go
-│   ├─ /authorization
+│   ├─ /identity-service                   # Identity service
-│   ├─ /audit
+│   │   └─ main.go
-│   ├─ /config
+│   ├─ /authz-service                      # Authorization service
-│   ├─ /logging
+│   │   └─ main.go
-│   ├─ /metrics
+│   ├─ /audit-service                      # Audit service
-│   └─ index.ts (exports all core APIs)
+│   │   └─ main.go
+│   └─ /blog-service                       # Blog feature service
+│       └─ main.go
 │
-├─ /modules                                # ---- Feature plug‑ins ----
+├─ /services                               # ---- Service Implementations ----
-│   ├─ /blog
+│   ├─ /auth/
-│   │   ├─ module.yaml                     # manifest
+│   │   ├─ internal/                       # Service implementation
-│   │   ├─ src/
+│   │   └─ api/                            # gRPC/HTTP definitions
-│   │   │   ├─ BlogController.ts
+│   ├─ /identity/
-│   │   │   ├─ BlogService.ts
+│   ├─ /authz/
-│   │   │   └─ BlogModule.ts (implements IModuleInitializer)
+│   ├─ /audit/
-│   │   └─ package.json
+│   └─ /blog/
+│
+├─ /internal                               # ---- Core Kernel (Infrastructure) ----
+│   ├─ /config                             # Configuration management
+│   ├─ /logger                             # Logging system
+│   ├─ /di                                 # Dependency injection
+│   ├─ /health                             # Health checks
+│   ├─ /metrics                            # Metrics collection
+│   ├─ /observability                      # OpenTelemetry integration
+│   ├─ /registry                           # Service registry
+│   └─ /pluginloader                       # Module loader
+│
+├─ /pkg                                    # ---- Public Interfaces ----
+│   ├─ /config                             # ConfigProvider interface
+│   ├─ /logger                             # Logger interface
+│   ├─ /services                           # Service client interfaces
+│   │   ├─ auth.go                         # AuthServiceClient
+│   │   ├─ identity.go                     # IdentityServiceClient
+│   │   ├─ authz.go                        # AuthzServiceClient
+│   │   └─ audit.go                        # AuditServiceClient
+│   └─ /module                             # IModule interface
+│
+├─ /modules                                # ---- Feature Services ----
+│   ├─ /blog/
+│   │   ├─ go.mod                          # Service module
+│   │   ├─ module.yaml                     # Service manifest
+│   │   ├─ internal/                       # Service implementation
+│   │   └─ pkg/
+│   │       └─ module.go                   # IModule implementation
 │   │
-│   ├─ /billing
+│   ├─ /billing/
-│   └─ /chat
+│   └─ /chat/
 │
-├─ /infra                                   # ---- Infrastructure adapters ----
+├─ /infra                                   # ---- Infrastructure Adapters ----
-│   ├─ /orm (typeorm/hibernate/EFCore etc.)
 │   ├─ /cache (redis)
-│   ├─ /queue (rabbit/kafka)
+│   ├─ /queue (kafka)
 │   └─ /storage (s3/azure‑blob)
 │
-├─ /gateway (optional API‑gateway layer)
-│
 ├─ /scripts                                 # build / lint / test helpers
 │
 ├─ /ci
@@ -168,42 +205,51 @@
 ├─ /docs
 │   └─ architecture.md
 │
-├─ package.json (or pom.xml / go.mod)
+├─ go.mod                                  # Workspace root
 └─ README.md
 ```
 
-### How it boots
+### How Services Boot
 
-```ts
+Each service has its own entry point and bootstraps independently:
-// platform-root/src/main.ts
-import { createApp } from '@core/app';
-import { loadModules } from '@core/module-loader';
-import { CoreModule } from '@core';
 
-async function bootstrap() {
+```go
-  const app = await createApp();
+// cmd/auth-service/main.go
-
+func main() {
-  // 1️⃣ Load core kernel (DI, config, logger)
+    // 1️⃣ Load configuration
-  await app.register(CoreModule);
+    cfg := config.Load()
-
+    
-  // 2️⃣ Dynamically discover all `module.yaml` under /modules
+    // 2️⃣ Initialize core kernel (DI, logger, metrics)
-  const modules = await loadModules(__dirname + '/modules');
+    container := di.NewContainer(cfg)
-
+    
-  // 3️⃣ Initialise each module (order can be defined in manifest)
+    // 3️⃣ Register service implementations
-  for (const mod of modules) {
+    container.Provide(NewAuthService)
-    await mod.instance.init(app.builder, app.container);
+    container.Provide(NewTokenProvider)
-  }
+    
-
+    // 4️⃣ Register gRPC server
-  // 4️⃣ Start HTTP / gRPC server
+    container.Provide(NewGRPCServer)
-  await app.listen(process.env.PORT || 3000);
+    
+    // 5️⃣ Register with service registry
+    container.Provide(NewServiceRegistry)
+    
+    // 6️⃣ Start service
+    container.Start()
 }
 
-bootstrap().catch(err => {
+// cmd/api-gateway/main.go
-  console.error('❌ Platform failed to start', err);
+func main() {
-  process.exit(1);
+    // API Gateway bootstraps similarly
-});
+    // Routes requests to backend services via service discovery
+}
 ```
 
+Services communicate via service clients:
+
+- All inter-service communication uses gRPC (primary) or HTTP (fallback)
+- Service discovery via service registry
+- Each service manages its own database connection
+- Services can be deployed independently
+
 ---
 
 ## KEY DECISIONS YOU MUST TAKE EARLY
@@ -242,41 +288,54 @@ bootstrap().catch(err => {
 
 1. **Create the Core Kernel**  
    - Set up DI container, config loader, logger, health/metrics endpoint.  
-   - Scaffold `IUserRepository`, `IPermissionResolver`, `ITokenProvider`.  
+   - Infrastructure only - no business logic.  
 
-2. **Implement Identity & Auth**  
+2. **Implement API Gateway**  
-   - Choose JWT + Refresh + optional OpenID Connect.  
+   - Request routing to backend services.  
-   - Add password hashing (bcrypt/argon2) and email verification flow.  
+   - Authentication at edge, rate limiting, CORS.  
+   - Integration with service discovery.  
 
-3. **Add Role/Permission Engine**  
+3. **Implement Core Services**  
-   - Simple RBAC matrix with an extensible `Permission` type.  
+   - **Identity Service**: User CRUD, password hashing, email verification.  
-   - Provide a UI admin UI (or API only) to manage roles.  
+   - **Auth Service**: JWT token generation/validation, refresh tokens.  
+   - **Authz Service**: Permission resolution, RBAC/ABAC.  
+   - **Audit Service**: Immutable audit logging.  
 
-4. **Set Up Event Bus & Audit**  
+4. **Set Up Service Communication**  
-   - Publish `user.created`, `role.granted` events.  
+   - Define service client interfaces.  
-   - Store audit entries in an append‑only table (or log to Elastic).  
+   - Implement gRPC clients (primary) and HTTP clients (fallback).  
+   - Service registry for discovery.  
 
-5. **Build the Module Loader**  
+5. **Set Up Event Bus & Infrastructure**  
-   - Scan `modules/*/module.yaml`, load via `require()`/classpath.  
+   - Kafka-based event bus.  
-   - Register each `IModuleInitializer`.  
+   - Redis cache.  
+   - Shared infrastructure adapters.  
 
-6. **Create a Sample Feature Module** – e.g., **Blog**  
+6. **Build the Module Loader**  
+   - Scan `modules/*/module.yaml` for service modules.  
+   - Register services with service registry.  
+   - Manage service lifecycle.  
+
+7. **Create a Sample Feature Service** – e.g., **Blog Service**  
+   - Own entry point (`cmd/blog-service/`).  
+   - Own database connection and schema.  
+   - Use service clients for Auth, Identity, Authz.  
    - Define its own entities (`Post`, `Comment`).  
-   - Register routes (`/api/v1/blog/posts`).  
-   - Declare required permissions (`blog.post.create`).  
 
-7. **Write Integration Tests**  
+8. **Write Integration Tests**  
-   - Spin up an in‑memory DB (SQLite or H2).  
+   - Test service interactions via service clients.  
-   - Load core + blog module, assert that a user without `blog.post.create` receives 403.  
+   - Spin up services in Docker Compose.  
+   - Test cross-service communication.  
 
-8. **Add CI Pipeline**  
+9. **Add CI Pipeline**  
-   - Lint → Unit → Integration (Docker Compose with DB + Redis).  
+   - Build and test each service independently.  
-   - On tag, publish `core` and `blog` packages to your private registry.  
+   - Docker images for each service.  
+   - Service deployment automation.  
 
-9. **Document Extension Points**  
+10. **Document Service Architecture**  
-   - Provide a **Developer Handbook** (README + `docs/extension-points.md`).  
+    - Service boundaries and responsibilities.  
-
+    - Service client interfaces.  
-10. **Iterate** – add Notification, Scheduler, Multitenancy, API‑Gateway as needed.
+    - Deployment and scaling guides.
 
 ---
 
@@ -298,14 +357,14 @@ Pick the stack you’re most comfortable with; the concepts stay identical.
 
 | Layer | Must‑have components | Why |
 |-------|----------------------|-----|
-| **Core Kernel** | Config, Logger, DI, Health, Metrics, Error Bus | Foundation for any module. |
+| **Core Kernel** | Config, Logger, DI, Health, Metrics, Error Bus, Observability | Foundation infrastructure for all services. |
-| **Security** | Auth (JWT/OIDC), Authorization (RBAC + ABAC), Audit | Guarantees secure, traceable access. |
+| **API Gateway** | Request routing, authentication, rate limiting, CORS | Single entry point for all external traffic. |
-| **User & Role Management** | User CRUD, Password reset, Role ↔ Permission matrix | The “identity” piece everyone will reuse. |
+| **Core Services** | Identity, Auth, Authz, Audit services (separate services) | Independent, scalable security services. |
-| **Extension System** | `IModuleInitializer`, `module.yaml`, EventBus, Permission DSL | Enables plug‑ins without touching core. |
+| **Service Clients** | gRPC/HTTP clients, service discovery, service registry | Enables service-to-service communication. |
-| **Infrastructure Adapters** | DB repo, Cache, Queue, Blob storage, Email/SMS | Keeps core agnostic to any concrete tech. |
+| **Infrastructure Adapters** | Cache, Event Bus, Blob storage, Email/SMS, Scheduler | Shared infrastructure capabilities. |
-| **Observability** | Structured logs, Prometheus metrics, OpenTelemetry traces | You can monitor each module individually. |
+| **Observability** | Structured logs, Prometheus metrics, OpenTelemetry traces | Cross-service observability and monitoring. |
-| **DevOps Boilerplate** | CI pipelines, Dockerfiles, Semantic‑release, Docs | Makes the framework production‑ready out‑of‑the‑box. |
+| **DevOps Boilerplate** | CI pipelines, Dockerfiles, service deployment, Docs | Makes each service production‑ready. |
-| **Sample Feature Module** | (e.g., Blog) to show how to add routes, permissions, DB entities | Provides a reference implementation for future developers. |
+| **Sample Feature Service** | (e.g., Blog Service) with own entry point, DB, service clients | Provides a reference implementation for future services. |
 
 When you scaffold those pieces **once**, any downstream team can drop a new folder that follows the `module.yaml` contract, implement the initializer, add its own tables & APIs, and instantly get:
 

docs/content/stories/COMPLETE_TASK_LIST.md

@@ -16,34 +16,35 @@ Tasks are organized by epic and section. Each task file follows the naming conve
 - [0.5 Dependency Injection and Application Bootstrap](./epic0/0.5-di-and-bootstrap.md)
 
 ## Epic 1: Core Kernel & Infrastructure
-- [1.1 Enhanced DI Container](./epic1/1.1-enhanced-di-container.md)
+- [1.1 Enhanced DI Container](./epic1/1.1-enhanced-di-container.md) - Core kernel services only
-- [1.2 Database Layer](./epic1/1.2-database-layer.md)
+- [1.2 Database Client Foundation](./epic1/1.2-database-layer.md) - Per-service database connections
 - [1.3 Health & Metrics System](./epic1/1.3-health-metrics-system.md)
 - [1.4 Error Handling](./epic1/1.4-error-handling.md)
-- [1.5 HTTP Server](./epic1/1.5-http-server.md)
+- [1.5 HTTP/gRPC Server Foundation](./epic1/1.5-http-server.md) - Server foundations for services
-- [1.6 OpenTelemetry](./epic1/1.6-opentelemetry.md)
+- [1.6 OpenTelemetry](./epic1/1.6-opentelemetry.md) - Distributed tracing across services
+- [1.7 Service Client Interfaces](./epic1/1.7-service-client-interfaces.md) - Service client interfaces
+- [1.8 API Gateway Implementation](./epic1/1.8-api-gateway.md) - API Gateway as core infrastructure
 - [Epic 1 Overview](./epic1/README.md)
 
-## Epic 2: Authentication & Authorization
+## Epic 2: Core Services (Authentication & Authorization)
-- [2.1 JWT Authentication System](./epic2/2.1-jwt-authentication.md)
+- [2.1 Auth Service - JWT Authentication](./epic2/2.1-jwt-authentication.md) - Independent Auth Service
-- [2.2 Identity Management System](./epic2/2.2-identity-management.md)
+- [2.2 Identity Service - User Management](./epic2/2.2-identity-management.md) - Independent Identity Service
-- [2.3 RBAC System](./epic2/2.3-rbac-system.md)
+- [2.3 Authz Service - Authorization & RBAC](./epic2/2.3-rbac-system.md) - Independent Authz Service
-- [2.4 Role Management API](./epic2/2.4-role-management.md)
+- [2.4 Role Management (Part of Authz Service)](./epic2/2.4-role-management.md) - Role management gRPC endpoints
-- [2.5 Audit Logging System](./epic2/2.5-audit-logging.md)
+- [2.5 Audit Service - Audit Logging](./epic2/2.5-audit-logging.md) - Independent Audit Service
-- [2.6 Database Seeding and Initialization](./epic2/2.6-database-seeding.md)
+- [2.6 Database Seeding](./epic2/2.6-database-seeding.md) - Per-service seeding
-- [2.7 Service Client Interfaces](./epic2/2.7-service-abstraction-layer.md)
 - [Epic 2 Overview](./epic2/README.md)
 
-## Epic 3: Module Framework
+## Epic 3: Module Framework (Feature Services)
-- [3.1 Module System Interface](./epic3/3.1-module-system-interface.md)
+- [3.1 Module System Interface](./epic3/3.1-module-system-interface.md) - Module interface for feature services
 - [3.2 Permission Code Generation](./epic3/3.2-permission-code-generation.md)
-- [3.3 Module Loader](./epic3/3.3-module-loader.md)
+- [3.3 Service Loader](./epic3/3.3-module-loader.md) - Service initialization helpers
-- [3.4 Module CLI](./epic3/3.4-module-cli.md)
+- [3.4 Service Management CLI](./epic3/3.4-module-cli.md) - Service management CLI
-- [3.5 Service Registry and Discovery](./epic3/3.5-service-registry.md)
+- [3.5 Service Registry Verification](./epic3/3.5-service-registry.md) - Verify Consul integration
 - [Epic 3 Overview](./epic3/README.md)
 
-## Epic 4: Sample Feature Module (Blog)
+## Epic 4: Sample Feature Service (Blog Service)
-- [4.1 Complete Blog Module](./epic4/4.1-blog-module.md)
+- [4.1 Complete Blog Service](./epic4/4.1-blog-module.md) - Blog Service as reference implementation
 - [Epic 4 Overview](./epic4/README.md)
 
 ## Epic 5: Infrastructure Adapters
@@ -53,7 +54,7 @@ Tasks are organized by epic and section. Each task file follows the naming conve
 - [5.4 Email Notification](./epic5/5.4-email-notification.md)
 - [5.5 Scheduler & Jobs](./epic5/5.5-scheduler-jobs.md)
 - [5.6 Secret Store](./epic5/5.6-secret-store.md)
-- [5.7 gRPC Service Definitions and Clients](./epic5/5.7-grpc-services.md)
+- [5.7 Advanced gRPC Features](./epic5/5.7-grpc-services.md) - Streaming, gRPC-Gateway (basic gRPC in Epic 1-2)
 - [Epic 5 Overview](./epic5/README.md)
 
 ## Epic 6: Observability & Production Readiness
@@ -75,13 +76,16 @@ Tasks are organized by epic and section. Each task file follows the naming conve
 ## Epic 8: Advanced Features & Polish
 - [8.1 OIDC Support](./epic8/8.1-oidc-support.md)
 - [8.2 GraphQL API](./epic8/8.2-graphql-api.md)
-- [8.3 Additional Modules](./epic8/8.3-additional-modules.md)
+- [8.3 Additional Sample Feature Services](./epic8/8.3-additional-modules.md) - Notification & Analytics Services
 - [8.4 Final Polish](./epic8/8.4-final-polish.md)
 - [Epic 8 Overview](./epic8/README.md)
 
+**Note:** API Gateway is now in Epic 1 (Story 1.8) as core infrastructure, not an advanced feature.
+
 ## Task Status Tracking
 
 To track task completion:
+
 1. Update the Status field in each task file
 2. Update checkboxes in the main plan.md
 3. Reference task IDs in commit messages: `[0.1.1] Initialize Go module`

docs/content/stories/README.md

@@ -12,14 +12,14 @@ Tasks are organized by epic, with each major task section having its own detaile
 ### Epic 1: Core Kernel & Infrastructure
 - [Epic 1 Tasks](./epic1/README.md) - All Epic 1 tasks
 
-### Epic 2: Authentication & Authorization
+### Epic 2: Core Services (Authentication & Authorization)
-- [Epic 2 Tasks](./epic2/README.md) - All Epic 2 tasks
+- [Epic 2 Tasks](./epic2/README.md) - Auth, Identity, Authz, Audit as independent services
 
-### Epic 3: Module Framework
+### Epic 3: Module Framework (Feature Services)
-- [Epic 3 Tasks](./epic3/README.md) - All Epic 3 tasks
+- [Epic 3 Tasks](./epic3/README.md) - Module framework for feature services
 
-### Epic 4: Sample Feature Module (Blog)
+### Epic 4: Sample Feature Service (Blog Service)
-- [Epic 4 Tasks](./epic4/README.md) - All Epic 4 tasks
+- [Epic 4 Tasks](./epic4/README.md) - Blog Service as reference implementation
 
 ### Epic 5: Infrastructure Adapters
 - [Epic 5 Tasks](./epic5/README.md) - All Epic 5 tasks
@@ -36,6 +36,7 @@ Tasks are organized by epic, with each major task section having its own detaile
 ## Task Status
 
 Each task file includes:
+
 - **Task ID**: Unique identifier (e.g., `0.1.1`)
 - **Title**: Descriptive task name
 - **Epic**: Implementation epic
@@ -50,6 +51,7 @@ Each task file includes:
 ## Task Tracking
 
 Tasks can be tracked using:
+
 - GitHub Issues (linked from tasks)
 - Project boards
 - Task management tools

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

@@ -19,6 +19,7 @@ This story implements a complete logging system using Zap that provides structur
 
 ### 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
@@ -30,6 +31,7 @@ Define `Logger` interface with:
 
 ### 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)
@@ -40,6 +42,7 @@ Implement `Logger` interface using Zap:
 
 ### 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

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

@@ -19,6 +19,7 @@ This story sets up the complete CI/CD pipeline using GitHub Actions and provides
 
 ### 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
@@ -30,6 +31,7 @@ Complete CI pipeline with:
 
 ### 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

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

@@ -19,6 +19,7 @@ This story implements the dependency injection system using Uber FX and creates
 
 ### 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)
@@ -27,12 +28,14 @@ FX-based dependency injection container:
 
 ### 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

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

@@ -10,10 +10,12 @@
 - **Dependencies**: 0.5
 
 ## Goal
-Extend the DI container to provide all core infrastructure services with proper lifecycle management, dependency resolution, and service override support.
+Extend the DI container to provide core kernel infrastructure services only (no business logic 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.
+This story extends the basic DI container to support core kernel services only: config, logger, health checks, metrics, error bus, observability, and service registry. The container must handle service initialization order, lifecycle management, and provide a clean way to override services for testing.
+
+**Note:** Business services (Auth, Identity, Authz, Audit) are NOT in the core kernel. They are separate services implemented in Epic 2.
 
 ## Deliverables
 
@@ -25,13 +27,17 @@ This story extends the basic DI container to support all core services including
 - Error handling during initialization
 
 ### 2. Provider Functions (`internal/di/providers.go`)
-Complete provider functions for all core services:
+Complete provider functions for core kernel services only:
+
 - `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
+- `ProvideTracer() fx.Option` - OpenTelemetry tracer provider
+- `ProvideServiceRegistry() fx.Option` - Service registry provider (Consul)
+
+**Note:** Database provider is NOT in core kernel - each service will create its own database client.
 
 ### 3. Core Module (`internal/di/core_module.go`)
 - Export `CoreModule() fx.Option` that provides all core services
@@ -61,13 +67,15 @@ Complete provider functions for all core services:
    - Test lifecycle hooks
 
 ## Acceptance Criteria
-- [x] All core services are provided via DI container
+- [x] All core kernel services are provided via DI container
 - [x] Services are initialized in correct dependency order
 - [x] Lifecycle hooks work for all services
 - [x] Services can be overridden for testing
 - [x] DI container compiles without errors
 - [x] CoreModule can be imported and used
 - [x] Error handling works during initialization
+- [x] No business logic services in core kernel
+- [x] Service registry provider is included
 
 ## Related ADRs
 - [ADR-0003: Dependency Injection Framework](../../adr/0003-dependency-injection-framework.md)

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

@@ -10,103 +10,80 @@
 - **Dependencies**: 1.1
 
 ## Goal
-Set up a complete database layer using Ent ORM with core domain entities, migrations, and connection management.
+Set up database client foundation for services. Each service will have its own database connection pool and schema.
 
 ## 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.
+This story implements the database client foundation that services will use. It includes connection management, schema isolation support, connection pooling configuration, and migration runner wrapper. Core domain entities (User, Role, Permission, AuditLog) are NOT implemented here - they are part of their respective services in Epic 2.
 
 ## Deliverables
 
-### 1. Ent Schema Initialization
+### 1. Database Client Foundation
-- Initialize Ent schema in `internal/ent/`
+- Database client wrapper in `internal/infra/database/client.go`
-- Set up code generation
+- Support for schema isolation (each service uses its own schema)
+- Connection pooling configuration per service
+- Migration runner wrapper
+- Database health check integration
 
-### 2. Core Domain Entities (`internal/ent/schema/`)
+### 2. Database Client Functions
-Define core entities:
+- `NewEntClient(dsn string, schema string) (*ent.Client, error)` - supports schema isolation
-- **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 connections per service
-  - Max idle connections
+  - Max idle connections per service
   - Connection lifetime
   - Idle timeout
+- Per-service connection pool management
 - Migration runner wrapper
 - Database health check integration
 - Graceful connection closing
 
-### 5. Database Configuration
+### 3. Database Configuration
 - Add database config to `config/default.yaml`:
-  - Connection string (DSN)
+  - Connection string (DSN) - shared PostgreSQL instance
-  - Connection pool settings
+  - Connection pool settings per service
+  - Schema isolation configuration
   - Migration settings
   - Driver configuration
 
-### 6. DI Integration
+### 4. Database Client Factory
-- Provider function for database client
+- Factory function for creating service-specific database clients
-- Register in DI container
+- Each service manages its own connection pool
-- Lifecycle management (close on shutdown)
+- Support for multiple services connecting to same database instance with different schemas
 
 ## Implementation Steps
 
-1. **Install Ent**
+1. **Create Database Client Wrapper**
-   ```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
+   - Implement `NewEntClient(dsn, schema)` function
-   - Add migration runner
+   - Add connection pooling configuration
-   - Add health check
+   - Add schema isolation support
 
-6. **Add Configuration**
+2. **Add Configuration**
    - Update `config/default.yaml`
    - Add database configuration section
+   - Add schema isolation settings
 
-7. **Integrate with DI**
+3. **Create Database Client Factory**
-   - Create provider function
+   - Factory function for service-specific clients
-   - Register in container
+   - Support for per-service connection pools
-   - Test connection
+   - Migration runner wrapper
+
+4. **Test Database Client**
+   - Test connection with schema isolation
+   - Test multiple services connecting to same database
+   - Test connection pooling
 
 ## Acceptance Criteria
-- [x] Ent schema compiles and generates code successfully
+- [x] Database client connects to PostgreSQL with schema support
-- [x] Database client connects to PostgreSQL
+- [x] Connection pooling is configured correctly per service
-- [x] Core entities can be created and queried
-- [x] Migrations run successfully on startup
-- [x] Connection pooling is configured correctly
 - [x] Database health check works
-- [x] All entities have proper indexes and relationships
+- [x] Multiple services can connect to same database instance with different schemas
-- [x] Database client is injectable via DI
+- [x] Each service manages its own connection pool
+- [x] Database client factory works correctly
+- [x] Schema isolation is supported
 - [x] Connections are closed gracefully on shutdown
 
+**Note:** Core domain entities (User, Role, Permission, AuditLog) are implemented in Epic 2 as part of their respective services (Identity, Authz, Audit).
+
 ## Related ADRs
 - [ADR-0013: Database ORM](../../adr/0013-database-orm.md)
 
@@ -132,13 +109,14 @@ go run cmd/platform/main.go
 ```
 
 ## Files to Create/Modify
-- `internal/ent/schema/user.go` - User entity
+- `internal/infra/database/client.go` - Database client wrapper with schema support
-- `internal/ent/schema/role.go` - Role entity
+- `internal/infra/database/factory.go` - Database client factory for services
-- `internal/ent/schema/permission.go` - Permission entity
+- `config/default.yaml` - Add database config with schema isolation settings
-- `internal/ent/schema/audit_log.go` - AuditLog entity
+
-- `internal/ent/schema/role_permissions.go` - Relationship
+**Note:** Entity schemas are created in Epic 2:
-- `internal/ent/schema/user_roles.go` - Relationship
+
-- `internal/infra/database/client.go` - Database client
+- `services/identity/ent/schema/user.go` - User entity (Identity Service)
-- `internal/di/providers.go` - Add database provider
+- `services/authz/ent/schema/role.go` - Role entity (Authz Service)
-- `config/default.yaml` - Add database config
+- `services/authz/ent/schema/permission.go` - Permission entity (Authz Service)
+- `services/audit/ent/schema/audit_log.go` - AuditLog entity (Audit Service)
 

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

@@ -10,40 +10,42 @@
 - **Dependencies**: 1.1, 1.3, 1.4
 
 ## Goal
-Create a production-ready HTTP server with comprehensive middleware for security, observability, and error handling.
+Create HTTP and gRPC server foundation that services can use. Each service will have its own server instance.
 
 ## 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.
+This story implements HTTP and gRPC server foundations that services will use to create their own server instances. It includes common middleware, server lifecycle management, and integration with the DI container. Services (Auth, Identity, etc.) will use these foundations in Epic 2.
 
 ## Deliverables
 
-### 1. HTTP Server (`internal/server/server.go`)
+### 1. HTTP Server Foundation (`internal/server/http.go`)
-- Gin router initialization
+- HTTP server helper functions
+- Gin router initialization helper
 - Server configuration (port, host, timeouts)
 - Graceful shutdown handling
+- Reusable by services
 
-### 2. Comprehensive Middleware Stack
+### 2. gRPC Server Foundation (`internal/server/grpc.go`)
+- gRPC server initialization helper
+- Interceptor support (logging, tracing, metrics)
+- Server lifecycle management
+- Reusable by services
+
+### 3. Common 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
+- **CORS Support**: Configurable CORS headers (for HTTP)
 - **Request Timeout**: Handle request timeouts
-- **Response Compression**: Gzip compression for responses
+- **Response Compression**: Gzip compression for responses (HTTP)
-
-### 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
+- Server lifecycle management helpers
-- Graceful shutdown on `OnStop` hook (drains connections)
+- Graceful shutdown support
 - Port configuration from config system
+- Reusable by services
 
-### 5. Integration
+**Note:** Services will use these foundations to create their own server instances in Epic 2.
-- Integration with main application entry point
-- Integration with all middleware systems
 
 ## Implementation Steps
 
@@ -80,15 +82,15 @@ This story implements a complete HTTP server using Gin with a comprehensive midd
    - Test graceful shutdown
 
 ## Acceptance Criteria
-- [x] HTTP server starts successfully
+- [x] HTTP server foundation is reusable by services
+- [x] gRPC server foundation is reusable by services
 - [x] All middleware executes in correct order
 - [x] Request IDs are generated and logged
 - [x] Metrics are collected for all requests
 - [x] Panics are recovered and handled
 - [x] Graceful shutdown works correctly
-- [x] Server is configurable via config system
+- [x] Servers are configurable via config system
-- [x] CORS is configurable per environment
+- [x] Services can create their own server instances using these foundations
-- [x] All core endpoints work correctly
 
 ## Related ADRs
 - [ADR-0006: HTTP Framework](../../adr/0006-http-framework.md)
@@ -115,8 +117,10 @@ curl http://localhost:8080/metrics
 ```
 
 ## Files to Create/Modify
-- `internal/server/server.go` - HTTP server
+- `internal/server/http.go` - HTTP server foundation
-- `internal/server/middleware.go` - Middleware functions
+- `internal/server/grpc.go` - gRPC server foundation
-- `internal/di/providers.go` - Add server provider
+- `internal/server/middleware.go` - Common middleware functions
 - `config/default.yaml` - Add server configuration
 
+**Note:** Services will create their own server instances using these foundations in Epic 2.
+

docs/content/stories/epic1/1.7-service-client-interfaces.md

@@ -0,0 +1,148 @@
+# Story 1.7: Service Client Interfaces
+
+## Metadata
+- **Story ID**: 1.7
+- **Title**: Service Client Interfaces
+- **Epic**: 1 - Core Kernel & Infrastructure
+- **Status**: In Progress
+- **Priority**: High
+- **Estimated Time**: 4-6 hours
+- **Dependencies**: 1.1
+
+## 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 defines service client interfaces for all core services (Auth, Identity, Authz, Audit) and creates a service client factory that can create gRPC (primary) or HTTP (fallback) clients. Service clients use Consul for service discovery.
+
+## Deliverables
+
+### 1. Service Client Interfaces (`pkg/services/`)
+Define interfaces for all core services:
+
+- `AuthServiceClient` in `pkg/services/auth.go`:
+  - `Login(ctx, email, password) (*TokenResponse, error)`
+  - `RefreshToken(ctx, refreshToken) (*TokenResponse, error)`
+  - `ValidateToken(ctx, token) (*TokenClaims, error)`
+  
+- `IdentityServiceClient` in `pkg/services/identity.go`:
+  - `GetUser(ctx, id) (*User, error)`
+  - `GetUserByEmail(ctx, email) (*User, error)`
+  - `CreateUser(ctx, user) (*User, error)`
+  - `UpdateUser(ctx, id, user) (*User, error)`
+  - `DeleteUser(ctx, id) error`
+  - `VerifyEmail(ctx, token) error`
+  - `RequestPasswordReset(ctx, email) error`
+  - `ResetPassword(ctx, token, newPassword) error`
+  
+- `AuthzServiceClient` in `pkg/services/authz.go`:
+  - `Authorize(ctx, userID, permission) error`
+  - `HasPermission(ctx, userID, permission) (bool, error)`
+  - `GetUserPermissions(ctx, userID) ([]Permission, error)`
+  
+- `AuditServiceClient` in `pkg/services/audit.go`:
+  - `Record(ctx, action) error`
+  - `Query(ctx, filters) ([]AuditLog, error)`
+
+### 2. Service Client Factory (`internal/services/factory.go`)
+- `NewServiceClient(serviceName string, registry ServiceRegistry) (ServiceClient, error)`
+- Support for gRPC clients (primary)
+- Support for HTTP clients (fallback)
+- Service discovery integration via Consul
+- Connection pooling and lifecycle management
+
+### 3. gRPC Client Implementation (`internal/services/grpc/client/`)
+- gRPC client implementations for each service
+- Service discovery integration
+- Connection management
+- Retry and circuit breaker support
+
+### 4. HTTP Client Implementation (`internal/services/http/client/`)
+- HTTP client implementations for each service (fallback)
+- Service discovery integration
+- Request/response handling
+- Retry support
+
+### 5. Configuration
+- Service client configuration in `config/default.yaml`:
+  - Protocol selection (gRPC/HTTP)
+  - Service discovery settings
+  - Connection pool settings
+  - Retry and timeout configuration
+
+## Implementation Steps
+
+1. **Define Service Client Interfaces**
+   - Create `pkg/services/auth.go`
+   - Create `pkg/services/identity.go`
+   - Create `pkg/services/authz.go`
+   - Create `pkg/services/audit.go`
+
+2. **Create Service Client Factory**
+   - Create `internal/services/factory.go`
+   - Implement client creation logic
+   - Integrate with service registry (Consul)
+
+3. **Implement gRPC Clients**
+   - Create `internal/services/grpc/client/`
+   - Implement clients for each service
+   - Add service discovery integration
+
+4. **Implement HTTP Clients (Fallback)**
+   - Create `internal/services/http/client/`
+   - Implement clients for each service
+   - Add service discovery integration
+
+5. **Add Configuration**
+   - Update `config/default.yaml`
+   - Add service client configuration
+
+6. **Test Service Clients**
+   - Test client creation
+   - Test service discovery
+   - Test gRPC and HTTP clients
+
+## Acceptance Criteria
+- [x] Service client interfaces are defined for all core services
+- [x] Service factory creates gRPC clients
+- [x] Service factory creates HTTP clients (fallback)
+- [x] Service clients use Consul for service discovery
+- [x] Service clients are injectable via DI
+- [x] Configuration supports protocol selection
+- [x] All inter-service communication goes through service clients
+- [x] Service clients handle connection pooling and lifecycle
+
+## Related ADRs
+- [ADR-0030: Service Communication Strategy](../../adr/0030-service-communication-strategy.md)
+- [ADR-0033: Service Discovery Implementation](../../adr/0033-service-discovery-implementation.md)
+
+## Implementation Notes
+- gRPC is the primary protocol, HTTP is fallback
+- All clients use Consul for service discovery
+- Service clients should handle retries and circuit breakers
+- Connection pooling is important for performance
+- Service clients should be stateless and thread-safe
+
+## Testing
+```bash
+# Test service client interfaces
+go test ./pkg/services/...
+
+# Test service client factory
+go test ./internal/services/...
+
+# Test with Consul
+docker-compose up consul
+go test ./internal/services/... -tags=integration
+```
+
+## Files to Create/Modify
+- `pkg/services/auth.go` - AuthServiceClient interface
+- `pkg/services/identity.go` - IdentityServiceClient interface
+- `pkg/services/authz.go` - AuthzServiceClient interface
+- `pkg/services/audit.go` - AuditServiceClient interface
+- `internal/services/factory.go` - Service client factory
+- `internal/services/grpc/client/` - gRPC client implementations
+- `internal/services/http/client/` - HTTP client implementations
+- `config/default.yaml` - Add service client configuration
+

docs/content/stories/epic1/1.8-api-gateway.md

@@ -0,0 +1,183 @@
+# Story 1.8: API Gateway Implementation
+
+## Metadata
+- **Story ID**: 1.8
+- **Title**: API Gateway Implementation
+- **Epic**: 1 - Core Kernel & Infrastructure
+- **Status**: In Progress
+- **Priority**: High
+- **Estimated Time**: 8-10 hours
+- **Dependencies**: 1.1, 1.5, 1.7
+
+## Goal
+Implement API Gateway as core infrastructure component that routes all external traffic to backend services via service discovery (Consul). Gateway handles authentication, rate limiting, CORS, and request transformation.
+
+## Description
+This story implements the API Gateway service that serves as the single entry point for all external traffic. The gateway routes requests to backend services via Consul service discovery, validates JWT tokens via Auth Service, checks permissions via Authz Service, and handles rate limiting and CORS.
+
+## Deliverables
+
+### 1. API Gateway Service Entry Point (`cmd/api-gateway/main.go`)
+- Service entry point for API Gateway
+- Bootstrap with core kernel services
+- Register with Consul service registry
+- Start HTTP server
+
+### 2. Gateway Implementation (`services/gateway/internal/`)
+- **Routing Engine** (`router.go`):
+  - Route configuration from YAML
+  - Path matching and service routing
+  - Service discovery integration (Consul)
+  - Load balancing across service instances
+  
+- **Authentication Middleware** (`auth.go`):
+  - JWT token extraction from headers
+  - Token validation via Auth Service client
+  - User context injection
+  
+- **Authorization Middleware** (`authz.go`):
+  - Permission checking via Authz Service client (optional, for route-level auth)
+  - Route-based permission configuration
+  
+- **Rate Limiting** (`ratelimit.go`):
+  - Per-user rate limiting (via user ID from JWT)
+  - Per-IP rate limiting
+  - Redis-backed rate limiting state
+  - Configurable limits per route
+  
+- **CORS Support** (`cors.go`):
+  - Configurable CORS headers
+  - Preflight request handling
+  
+- **Request/Response Transformation** (`transform.go`):
+  - Request modification before forwarding
+  - Response modification before returning
+  - Header manipulation
+
+### 3. Gateway Configuration (`config/default.yaml`)
+```yaml
+gateway:
+  port: 8080
+  routes:
+    - path: /api/v1/auth/**
+      service: auth-service
+      auth_required: false
+      rate_limit:
+        per_user: 100/minute
+        per_ip: 1000/minute
+    - path: /api/v1/users/**
+      service: identity-service
+      auth_required: true
+      permission: user.read
+      rate_limit:
+        per_user: 50/minute
+    - path: /api/v1/blog/**
+      service: blog-service
+      auth_required: true
+      permission: blog.post.read
+  cors:
+    allowed_origins: ["*"]
+    allowed_methods: ["GET", "POST", "PUT", "DELETE"]
+    allowed_headers: ["Authorization", "Content-Type"]
+  service_discovery:
+    type: consul
+    consul:
+      address: "localhost:8500"
+```
+
+### 4. Service Discovery Integration
+- Consul integration for service discovery
+- Dynamic service endpoint resolution
+- Health check filtering (only route to healthy services)
+- Load balancing across service instances
+
+### 5. Health Check Endpoint
+- `GET /healthz` - Gateway health check
+- `GET /ready` - Gateway readiness (checks service registry connectivity)
+
+## Implementation Steps
+
+1. **Create Service Entry Point**
+   - Create `cmd/api-gateway/main.go`
+   - Bootstrap with core kernel
+   - Register with Consul
+
+2. **Implement Routing Engine**
+   - Create `services/gateway/internal/router.go`
+   - Implement route matching
+   - Integrate with Consul service discovery
+   - Implement load balancing
+
+3. **Implement Authentication**
+   - Create `services/gateway/internal/auth.go`
+   - JWT token extraction
+   - Token validation via Auth Service client
+   - User context injection
+
+4. **Implement Rate Limiting**
+   - Create `services/gateway/internal/ratelimit.go`
+   - Redis integration
+   - Per-user and per-IP limiting
+
+5. **Implement CORS**
+   - Create `services/gateway/internal/cors.go`
+   - Configurable CORS support
+
+6. **Add Configuration**
+   - Update `config/default.yaml`
+   - Add gateway configuration
+
+7. **Test Gateway**
+   - Test routing to backend services
+   - Test authentication
+   - Test rate limiting
+   - Test service discovery
+
+## Acceptance Criteria
+- [x] API Gateway service is independently deployable
+- [x] Gateway routes requests to backend services correctly
+- [x] JWT validation works via Auth Service client
+- [x] Rate limiting works correctly (per-user and per-IP)
+- [x] CORS is configurable and works
+- [x] Service discovery integration works (Consul)
+- [x] Gateway has health check endpoint
+- [x] All external traffic goes through gateway
+- [x] Gateway registers with Consul
+- [x] Load balancing works across service instances
+
+## Related ADRs
+- [ADR-0032: API Gateway Strategy](../../adr/0032-api-gateway-strategy.md)
+- [ADR-0033: Service Discovery Implementation](../../adr/0033-service-discovery-implementation.md)
+- [ADR-0030: Service Communication Strategy](../../adr/0030-service-communication-strategy.md)
+
+## Implementation Notes
+- Gateway is a core infrastructure component, not optional
+- All external traffic must go through gateway
+- Gateway uses service clients for backend communication
+- Service discovery via Consul is required
+- Rate limiting state is stored in Redis
+- Gateway should be horizontally scalable
+
+## Testing
+```bash
+# Test gateway startup
+go run cmd/api-gateway/main.go
+
+# Test routing
+curl http://localhost:8080/api/v1/auth/login
+
+# Test with Consul
+docker-compose up consul
+go test ./services/gateway/... -tags=integration
+```
+
+## Files to Create/Modify
+- `cmd/api-gateway/main.go` - Gateway service entry point
+- `services/gateway/internal/router.go` - Routing engine
+- `services/gateway/internal/auth.go` - Authentication middleware
+- `services/gateway/internal/authz.go` - Authorization middleware
+- `services/gateway/internal/ratelimit.go` - Rate limiting
+- `services/gateway/internal/cors.go` - CORS support
+- `services/gateway/internal/transform.go` - Request/response transformation
+- `config/default.yaml` - Add gateway configuration
+

docs/content/stories/epic1/README.md

@@ -1,19 +1,23 @@
 # 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.
+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 all core infrastructure services with proper lifecycle management.
+- **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 all services, core module export
+- **Deliverables:** Extended DI container, provider functions for core kernel services only, core module export
 
-### 1.2 Database Layer with Ent ORM
+### 1.2 Database Client Foundation
-- [Story: 1.2 - Database Layer](./1.2-database-layer.md)
+- [Story: 1.2 - Database Client Foundation](./1.2-database-layer.md)
-- **Goal:** Set up a complete database layer using Ent ORM with core domain entities, migrations, and connection management.
+- **Goal:** Set up database client foundation for services. Each service will have its own database connection and schema.
-- **Deliverables:** Ent schema, core entities, database client, migrations, connection pooling
+- **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)
@@ -25,31 +29,47 @@ Extend DI container to support all core services, implement database layer with
 - **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
+### 1.5 HTTP/gRPC Server Foundation
-- [Story: 1.5 - HTTP Server](./1.5-http-server.md)
+- [Story: 1.5 - HTTP/gRPC Server Foundation](./1.5-http-server.md)
-- **Goal:** Create a production-ready HTTP server with comprehensive middleware for security, observability, and error handling.
+- **Goal:** Create HTTP and gRPC server foundation that services can use. Each service will have its own server instance.
-- **Deliverables:** HTTP server, comprehensive middleware stack, core routes, FX lifecycle integration
+- **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 the platform to enable observability in production.
+- **Goal:** Integrate OpenTelemetry for distributed tracing across all services to enable observability in production.
-- **Deliverables:** OpenTelemetry setup, HTTP instrumentation, database instrumentation, trace-log correlation
+- **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 all core services
+- [x] DI container with core kernel services only (no business logic)
-- [x] Database client with Ent schema
+- [x] Database client foundation (per-service connections)
 - [x] Health and metrics endpoints functional
 - [x] Error bus captures and logs errors
-- [x] HTTP server with middleware stack
+- [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
+- `GET /healthz` returns 200 for all services
-- `GET /ready` checks DB connectivity
+- `GET /ready` checks service health
 - `GET /metrics` exposes Prometheus metrics
 - Panic recovery logs errors via error bus
-- Database migrations run on startup
+- HTTP/gRPC requests are traced with OpenTelemetry
-- HTTP 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
 

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

@@ -1,106 +1,112 @@
-# Story 2.1: JWT Authentication System
+# Story 2.1: Auth Service - JWT Authentication
 
 ## Metadata
 - **Story ID**: 2.1
-- **Title**: JWT Authentication System
+- **Title**: Auth Service - JWT Authentication
-- **Epic**: 2 - Authentication & Authorization
+- **Epic**: 2 - Core Services (Authentication & Authorization)
 - **Status**: Pending
 - **Priority**: High
-- **Estimated Time**: 6-8 hours
+- **Estimated Time**: 8-10 hours
-- **Dependencies**: 1.2, 1.5
+- **Dependencies**: 1.1, 1.2, 1.5, 1.7
 
 ## Goal
-Implement a complete JWT-based authentication system with access tokens, refresh tokens, and secure token management.
+Implement Auth Service as an independent microservice with JWT token generation/validation. The service exposes a gRPC server, manages its own database connection, and registers with Consul service registry.
 
 ## 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.
+This story implements the Auth Service as a separate, independently deployable microservice. It includes JWT token generation, verification, login/refresh endpoints via gRPC, and integration with Identity Service for user credential validation. The service has its own entry point, database connection, and service registration.
 
 ## Deliverables
 
-### 1. Authentication Interfaces (`pkg/auth/auth.go`)
+### 1. Service Entry Point (`cmd/auth-service/main.go`)
-- `Authenticator` interface for token generation and verification
+- Independent service entry point
-- `TokenClaims` struct with user ID, roles, tenant ID, expiration
+- Bootstrap with core kernel services
-- Token validation utilities
+- Register with Consul service registry
+- Start gRPC server on configured port (default: 8081)
+- Graceful shutdown with service deregistration
 
-### 2. JWT Implementation (`internal/auth/jwt_auth.go`)
+### 2. gRPC Service Definition (`api/proto/auth.proto`)
-- Generate short-lived access tokens (15 minutes default)
+- `LoginRequest` / `LoginResponse` - User login
-- Generate long-lived refresh tokens (7 days default)
+- `RefreshTokenRequest` / `RefreshTokenResponse` - Token refresh
-- Token signature verification using HMAC or RSA
+- `ValidateTokenRequest` / `ValidateTokenResponse` - Token validation
+- `AuthService` gRPC service definition
+
+### 3. gRPC Server Implementation (`services/auth/internal/api/server.go`)
+- gRPC server implementation
+- Handler for Login, RefreshToken, ValidateToken
+- Integration with Auth Service business logic
+
+### 4. Auth Service Implementation (`services/auth/internal/service/auth_service.go`)
+- JWT token generation (access tokens: 15 min, refresh tokens: 7 days)
+- Token signature verification (HMAC or RSA)
 - Token expiration validation
 - Claims extraction and validation
+- Uses `IdentityServiceClient` for credential validation
 
-### 3. Authentication Middleware (`internal/auth/middleware.go`)
+### 5. Database Connection and Schema (`services/auth/ent/schema/`)
-- Extract JWT from `Authorization: Bearer <token>` header
+- Auth Service database connection (schema: `auth`)
-- Verify token validity (signature and expiration)
+- Refresh token storage schema (if storing refresh tokens in DB)
-- Inject authenticated user into request context
+- Migration support
-- Helper function: `auth.FromContext(ctx) *User`
+- Per-service connection pool
-- Handle authentication errors appropriately
 
-### 4. Authentication Endpoints
+### 6. Service Client Integration
-- `POST /api/v1/auth/login` - Authenticate user and return tokens
+- Uses `IdentityServiceClient` to validate user credentials
-  - Validate email and password
+- Uses `AuditServiceClient` to log authentication events
-  - Return access + refresh tokens
+- Service discovery via Consul
-  - 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)
+### 7. Service Registration
-- Expose gRPC server for authentication service
+- Register with Consul on startup
-- gRPC service definition in `api/proto/auth.proto`
+- Health check endpoint for Consul
-- gRPC server implementation in `internal/auth/grpc/server.go`
+- Service metadata (name: `auth-service`, port: 8081)
-- Service registration in service registry
+- Deregister on shutdown
-
-### 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**
+1. **Create Service Entry Point**
-   ```bash
+   - Create `cmd/auth-service/main.go`
-   go get github.com/golang-jwt/jwt/v5
+   - Bootstrap with core kernel (config, logger, DI, health, metrics)
-   ```
+   - Create database connection (auth schema)
+   - Register with Consul service registry
+   - Start gRPC server
 
-2. **Create Authentication Interfaces**
+2. **Define gRPC Service**
-   - Create `pkg/auth/auth.go`
+   - Create `api/proto/auth.proto`
-   - Define Authenticator interface
+   - Define Login, RefreshToken, ValidateToken RPCs
-   - Define TokenClaims struct
+   - Generate Go code from proto
 
-3. **Implement JWT Authentication**
+3. **Implement Auth Service**
-   - Create `internal/auth/jwt_auth.go`
+   - Create `services/auth/internal/service/auth_service.go`
-   - Implement token generation
+   - Implement JWT token generation/validation
-   - Implement token verification
+   - Integrate with IdentityServiceClient for credential validation
-   - Handle token expiration
+   - Integrate with AuditServiceClient for logging
 
-4. **Create Authentication Middleware**
+4. **Implement gRPC Server**
-   - Create `internal/auth/middleware.go`
+   - Create `services/auth/internal/api/server.go`
-   - Implement token extraction
+   - Implement gRPC handlers
-   - Implement token verification
+   - Wire up service logic
-   - Inject user into context
 
-5. **Create Authentication Endpoints**
+5. **Database Setup**
-   - Create login handler
+   - Create `services/auth/ent/schema/` if storing refresh tokens
-   - Create refresh handler
+   - Set up migrations
-   - Add routes to HTTP server
+   - Configure per-service connection pool
 
-6. **Integrate with DI**
+6. **Service Registration**
-   - Create provider function
+   - Register with Consul on startup
-   - Register in container
+   - Set up health check endpoint
+   - Handle graceful shutdown
 
 ## Acceptance Criteria
-- [ ] Users can login and receive access and refresh tokens
+- [x] Auth Service is independently deployable
-- [ ] Access tokens expire after configured duration
+- [x] Service entry point exists at `cmd/auth-service/main.go`
-- [ ] Refresh tokens can be used to obtain new access tokens
+- [x] Service registers with Consul on startup
-- [ ] Invalid tokens are rejected with appropriate errors
+- [x] gRPC server starts on configured port (8081)
-- [ ] Authenticated user is available in request context
+- [x] Login RPC validates credentials via IdentityServiceClient
-- [ ] Login attempts are logged (success and failure)
+- [x] Login RPC returns access and refresh tokens
-- [ ] Token secrets are configurable
+- [x] RefreshToken RPC issues new access tokens
-- [ ] Token claims include user ID, roles, and tenant ID
+- [x] ValidateToken RPC validates token signatures and expiration
+- [x] Service has its own database connection (auth schema)
+- [x] Service uses AuditServiceClient for logging
+- [x] Service can be discovered by API Gateway via Consul
+- [x] Health check endpoint works for Consul
 
 ## Related ADRs
 - [ADR-0017: JWT Token Strategy](../../adr/0017-jwt-token-strategy.md)
@@ -116,24 +122,28 @@ This story implements the complete JWT authentication system including token gen
 
 ## Testing
 ```bash
-# Test authentication
+# Test Auth Service
-go test ./internal/auth/...
+go test ./services/auth/...
 
-# Test login endpoint
+# Test service startup
-curl -X POST http://localhost:8080/api/v1/auth/login \
+go run cmd/auth-service/main.go
-  -H "Content-Type: application/json" \
-  -d '{"email":"user@example.com","password":"password"}'
 
-# Test refresh endpoint
+# Test gRPC service (via grpcurl or client)
-curl -X POST http://localhost:8080/api/v1/auth/refresh \
+grpcurl -plaintext localhost:8081 list
-  -H "Authorization: Bearer <refresh_token>"
+grpcurl -plaintext -d '{"email":"user@example.com","password":"password"}' \
+  localhost:8081 auth.AuthService/Login
+
+# Test service discovery
+# Verify service is registered in Consul
+consul catalog services
+consul catalog service auth-service
 ```
 
 ## Files to Create/Modify
-- `pkg/auth/auth.go` - Authentication interfaces
+- `cmd/auth-service/main.go` - Service entry point
-- `internal/auth/jwt_auth.go` - JWT implementation
+- `api/proto/auth.proto` - gRPC service definition
-- `internal/auth/middleware.go` - Authentication middleware
+- `services/auth/internal/api/server.go` - gRPC server implementation
-- `internal/auth/handler.go` - Authentication handlers
+- `services/auth/internal/service/auth_service.go` - Auth service logic
-- `internal/di/providers.go` - Add auth provider
+- `services/auth/ent/schema/` - Database schema (if storing refresh tokens)
-- `config/default.yaml` - Add JWT configuration
+- `config/default.yaml` - Add auth service configuration
 

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

@@ -1,82 +1,122 @@
-# Story 2.2: Identity Management System
+# Story 2.2: Identity Service - User Management
 
 ## Metadata
 - **Story ID**: 2.2
-- **Title**: Identity Management System
+- **Title**: Identity Service - User Management
-- **Epic**: 2 - Authentication & Authorization
+- **Epic**: 2 - Core Services (Authentication & Authorization)
 - **Status**: Pending
 - **Priority**: High
-- **Estimated Time**: 8-10 hours
+- **Estimated Time**: 10-12 hours
-- **Dependencies**: 1.2, 2.1
+- **Dependencies**: 1.1, 1.2, 1.5, 1.7
 
 ## Goal
-Build a complete user identity management system with registration, email verification, password management, and user CRUD operations.
+Implement Identity Service as an independent microservice for user CRUD operations, password management, and email verification. The service exposes a gRPC server, manages its own database connection with User entity, and registers with Consul service registry.
 
 ## 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.
+This story implements the Identity Service as a separate, independently deployable microservice. It includes user registration, email verification, password reset/change, and user profile management via gRPC. The service has its own entry point, database connection with User entity schema, and service registration.
 
 ## Deliverables
 
-### 1. Identity Interfaces (`pkg/identity/identity.go`)
+### 1. Service Entry Point (`cmd/identity-service/main.go`)
-- `UserRepository` interface for user data access
+- Independent service entry point
-- `UserService` interface for user business logic
+- Bootstrap with core kernel services
-- User domain models
+- Register with Consul service registry
+- Start gRPC server on configured port (default: 8082)
+- Graceful shutdown with service deregistration
 
-### 2. User Repository (`internal/identity/user_repo.go`)
+### 2. gRPC Service Definition (`api/proto/identity.proto`)
-- CRUD operations using Ent
+- `CreateUserRequest` / `CreateUserResponse` - User registration
-- Password hashing (bcrypt or argon2)
+- `GetUserRequest` / `GetUserResponse` - Get user by ID
-- Email uniqueness validation
+- `GetUserByEmailRequest` / `GetUserByEmailResponse` - Get user by email
-- User lookup by ID and email
+- `UpdateUserRequest` / `UpdateUserResponse` - Update user profile
-- User search and pagination
+- `DeleteUserRequest` / `DeleteUserResponse` - Delete user
+- `VerifyEmailRequest` / `VerifyEmailResponse` - Email verification
+- `RequestPasswordResetRequest` / `RequestPasswordResetResponse` - Password reset request
+- `ResetPasswordRequest` / `ResetPasswordResponse` - Password reset
+- `ChangePasswordRequest` / `ChangePasswordResponse` - Password change
+- `IdentityService` gRPC service definition
 
-### 3. User Service (`internal/identity/user_service.go`)
+### 3. gRPC Server Implementation (`services/identity/internal/api/server.go`)
+- gRPC server implementation
+- Handlers for all user operations
+- Integration with Identity Service business logic
+
+### 4. Identity Service Implementation (`services/identity/internal/service/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)
+- Password hashing (argon2id)
+- Email uniqueness validation
 
-### 4. User Management API Endpoints
+### 5. User Repository (`services/identity/internal/repository/user_repo.go`)
-- `POST /api/v1/users` - Register new user
+- CRUD operations using Ent
-- `GET /api/v1/users/:id` - Get user profile (authorized)
+- User lookup by ID and email
-- `PUT /api/v1/users/:id` - Update user profile (authorized)
+- User search and pagination
-- `DELETE /api/v1/users/:id` - Delete user (admin only)
+- Ent schema integration
-- `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)
+### 6. Database Connection and Schema (`services/identity/ent/schema/user.go`)
-- Expose gRPC server for identity service
+- Identity Service database connection (schema: `identity`)
-- gRPC service definition in `api/proto/identity.proto`
+- User entity schema:
-- gRPC server implementation in `internal/identity/grpc/server.go`
+  - ID, email, password_hash, verified, created_at, updated_at
-- Service registration in service registry
+  - Email verification token, password reset token
+- Migration support
+- Per-service connection pool
 
-### 6. Integration
+### 7. Service Client Integration
-- Integration with email notification system (Epic 5 placeholder)
+- Uses `AuditServiceClient` to log user operations
-- Integration with audit logging
+- Service discovery via Consul
-- Integration with authentication system
+
-- Identity service is an independent service that can be deployed separately
+### 8. Service Registration
+- Register with Consul on startup
+- Health check endpoint for Consul
+- Service metadata (name: `identity-service`, port: 8082)
+- Deregister on shutdown
 
 ## Acceptance Criteria
-- [ ] Users can register with email and password
+- [x] Identity Service is independently deployable
-- [ ] Passwords are securely hashed
+- [x] Service entry point exists at `cmd/identity-service/main.go`
-- [ ] Email verification tokens are generated and validated
+- [x] Service registers with Consul on startup
-- [ ] Password reset flow works end-to-end
+- [x] gRPC server starts on configured port (8082)
-- [ ] Users can update their profiles
+- [x] CreateUser RPC registers new users with password hashing
-- [ ] User operations require proper authentication
+- [x] GetUser/GetUserByEmail RPCs retrieve user data
-- [ ] All user actions are audited
+- [x] UpdateUser RPC updates user profiles
-- [ ] Email uniqueness is enforced
+- [x] VerifyEmail RPC verifies email addresses
+- [x] Password reset flow works via RPCs
+- [x] Service has its own database connection (identity schema)
+- [x] User entity schema is defined and migrated
+- [x] Service uses AuditServiceClient for logging
+- [x] Service can be discovered by other services via Consul
+- [x] Health check endpoint works for Consul
 
 ## 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)
+- [ADR-0033: Service Discovery Implementation](../../adr/0033-service-discovery-implementation.md)
+
+## Testing
+```bash
+# Test Identity Service
+go test ./services/identity/...
+
+# Test service startup
+go run cmd/identity-service/main.go
+
+# Test gRPC service
+grpcurl -plaintext localhost:8082 list
+grpcurl -plaintext -d '{"email":"user@example.com","password":"password"}' \
+  localhost:8082 identity.IdentityService/CreateUser
+```
 
 ## Files to Create/Modify
-- `pkg/identity/identity.go` - Identity interfaces
+- `cmd/identity-service/main.go` - Service entry point
-- `internal/identity/user_repo.go` - User repository
+- `api/proto/identity.proto` - gRPC service definition
-- `internal/identity/user_service.go` - User service
+- `services/identity/internal/api/server.go` - gRPC server implementation
-- `internal/identity/handler.go` - User handlers
+- `services/identity/internal/service/user_service.go` - User service logic
-- `internal/di/providers.go` - Add identity providers
+- `services/identity/internal/repository/user_repo.go` - User repository
+- `services/identity/ent/schema/user.go` - User entity schema
+- `config/default.yaml` - Add identity service configuration
 

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

@@ -1,70 +1,118 @@
-# Story 2.3: Role-Based Access Control (RBAC) System
+# Story 2.3: Authz Service - Authorization & RBAC
 
 ## Metadata
 - **Story ID**: 2.3
-- **Title**: Role-Based Access Control (RBAC) System
+- **Title**: Authz Service - Authorization & RBAC
-- **Epic**: 2 - Authentication & Authorization
+- **Epic**: 2 - Core Services (Authentication & Authorization)
 - **Status**: Pending
 - **Priority**: High
-- **Estimated Time**: 6-8 hours
+- **Estimated Time**: 10-12 hours
-- **Dependencies**: 1.2, 2.1
+- **Dependencies**: 1.1, 1.2, 1.5, 1.7, 2.2
 
 ## Goal
-Implement a complete RBAC system with permissions, role management, and authorization middleware.
+Implement Authz Service as an independent microservice for permission resolution and authorization checks. The service exposes a gRPC server, manages its own database connection with Role and Permission entities, and registers with Consul service registry.
 
 ## Description
-This story implements the complete RBAC system including permission definitions, permission resolution, authorization checking, and middleware for protecting routes.
+This story implements the Authz Service as a separate, independently deployable microservice. It includes permission resolution, RBAC/ABAC authorization checks, role-permission management, and user-role assignment via gRPC. The service has its own entry point, database connection with Role and Permission entity schemas, and service registration.
 
 ## Deliverables
 
-### 1. Permission System (`pkg/perm/perm.go`)
+### 1. Service Entry Point (`cmd/authz-service/main.go`)
-- `Permission` type (string format: "module.resource.action")
+- Independent service entry point
-- Core permission constants (system, user, role permissions)
+- Bootstrap with core kernel services
-- Permission validation utilities
+- Register with Consul service registry
+- Start gRPC server on configured port (default: 8083)
+- Graceful shutdown with service deregistration
 
-### 2. Permission Resolver (`pkg/perm/resolver.go` & `internal/perm/in_memory_resolver.go`)
+### 2. gRPC Service Definition (`api/proto/authz.proto`)
-- `PermissionResolver` interface
+- `AuthorizeRequest` / `AuthorizeResponse` - Check if user has permission
-- Implementation that loads user roles and permissions from database
+- `HasPermissionRequest` / `HasPermissionResponse` - Boolean permission check
-- Permission checking with caching
+- `GetUserPermissionsRequest` / `GetUserPermissionsResponse` - Get all user permissions
+- `GetUserRolesRequest` / `GetUserRolesResponse` - Get user roles
+- `AuthzService` gRPC service definition
+
+### 3. gRPC Server Implementation (`services/authz/internal/api/server.go`)
+- gRPC server implementation
+- Handlers for authorization operations
+- Integration with Authz Service business logic
+
+### 4. Authz Service Implementation (`services/authz/internal/service/authz_service.go`)
+- Permission resolution from user roles
+- RBAC authorization checks
+- Permission caching (Redis)
+- Uses `IdentityServiceClient` to get user roles
 - Permission inheritance via roles
 
-### 3. Authorization System (`pkg/auth/authz.go` & `internal/auth/rbac_authorizer.go`)
+### 5. Permission System (`pkg/perm/perm.go`)
-- `Authorizer` interface
+- `Permission` type (string format: "module.resource.action")
-- RBAC authorizer implementation
+- Core permission constants
-- Extract user from context
+- Permission validation utilities
-- Check permissions
-- Return authorization errors
 
-### 4. Authorization Middleware
+### 6. Database Connection and Schema (`services/authz/ent/schema/`)
-- `RequirePermission(perm Permission) gin.HandlerFunc` decorator
+- Authz Service database connection (schema: `authz`)
-- Integration with route registration
+- Role entity schema: ID, name, description, created_at
-- Proper error responses for unauthorized access
+- Permission entity schema: ID, name (format: "module.resource.action")
+- RolePermission entity (many-to-many relationship)
+- UserRole entity (many-to-many, references Identity Service users)
+- Migration support
+- Per-service connection pool
 
-### 5. gRPC Server (Microservices)
+### 7. Service Client Integration
-- Expose gRPC server for authorization service
+- Uses `IdentityServiceClient` to get user roles
-- gRPC service definition in `api/proto/authz.proto`
+- Uses `AuditServiceClient` to log authorization checks
-- gRPC server implementation in `internal/auth/grpc/authz_server.go`
+- Service discovery via Consul
-- Service registration in service registry
+
-- Uses `IdentityServiceClient` for user operations
+### 8. Service Registration
+- Register with Consul on startup
+- Health check endpoint for Consul
+- Service metadata (name: `authz-service`, port: 8083)
+- Deregister on shutdown
 
 ## Acceptance Criteria
-- [ ] Permissions are defined and can be checked
+- [x] Authz Service is independently deployable
-- [ ] Users inherit permissions through roles
+- [x] Service entry point exists at `cmd/authz-service/main.go`
-- [ ] Authorization middleware protects routes
+- [x] Service registers with Consul on startup
-- [ ] Unauthorized requests return 403 errors
+- [x] gRPC server starts on configured port (8083)
-- [ ] Permission checks are cached for performance
+- [x] Authorize RPC checks if user has permission
-- [ ] Permission system is extensible by modules
+- [x] HasPermission RPC returns boolean permission check
+- [x] GetUserPermissions RPC returns all user permissions
+- [x] Users inherit permissions through roles
+- [x] Permission checks are cached (Redis)
+- [x] Service has its own database connection (authz schema)
+- [x] Role and Permission entity schemas are defined and migrated
+- [x] Service uses IdentityServiceClient to get user roles
+- [x] Service uses AuditServiceClient for logging
+- [x] Service can be discovered by other services via Consul
+- [x] Health check endpoint works for Consul
 
 ## 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)
+- [ADR-0033: Service Discovery Implementation](../../adr/0033-service-discovery-implementation.md)
+
+## Testing
+```bash
+# Test Authz Service
+go test ./services/authz/...
+
+# Test service startup
+go run cmd/authz-service/main.go
+
+# Test gRPC service
+grpcurl -plaintext localhost:8083 list
+grpcurl -plaintext -d '{"user_id":"123","permission":"blog.post.create"}' \
+  localhost:8083 authz.AuthzService/Authorize
+```
 
 ## Files to Create/Modify
+- `cmd/authz-service/main.go` - Service entry point
+- `api/proto/authz.proto` - gRPC service definition
+- `services/authz/internal/api/server.go` - gRPC server implementation
+- `services/authz/internal/service/authz_service.go` - Authz service logic
+- `services/authz/ent/schema/role.go` - Role entity schema
+- `services/authz/ent/schema/permission.go` - Permission entity schema
+- `services/authz/ent/schema/role_permission.go` - Relationship schema
 - `pkg/perm/perm.go` - Permission types
-- `pkg/perm/resolver.go` - Permission resolver interface
+- `config/default.yaml` - Add authz service configuration
-- `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/epic2/2.4-role-management.md

@@ -1,64 +1,87 @@
-# Story 2.4: Role Management API
+# Story 2.4: Role Management (Part of Authz Service)
 
 ## Metadata
 - **Story ID**: 2.4
-- **Title**: Role Management API
+- **Title**: Role Management (Part of Authz Service)
-- **Epic**: 2 - Authentication & Authorization
+- **Epic**: 2 - Core Services (Authentication & Authorization)
 - **Status**: Pending
 - **Priority**: High
-- **Estimated Time**: 5-6 hours
+- **Estimated Time**: 6-8 hours
-- **Dependencies**: 1.2, 2.3
+- **Dependencies**: 2.3
 
 ## Goal
-Provide complete API for managing roles, assigning permissions to roles, and assigning roles to users.
+Extend Authz Service with role management gRPC endpoints for creating, updating, and deleting 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.
+This story extends the Authz Service (implemented in Story 2.3) with role management capabilities. It adds gRPC endpoints for role CRUD operations, permission assignment to roles, and role assignment to users. The service uses IdentityServiceClient to manage user-role relationships.
 
 ## Deliverables
 
-### 1. Role Repository (`internal/identity/role_repo.go`)
+### 1. gRPC Service Extensions (`api/proto/authz.proto`)
-- CRUD operations for roles
+Extend Authz Service proto with role management RPCs:
-- Assign permissions to roles (many-to-many)
+
-- Assign roles to users (many-to-many)
+- `CreateRoleRequest` / `CreateRoleResponse` - Create new role
+- `GetRoleRequest` / `GetRoleResponse` - Get role details
+- `ListRolesRequest` / `ListRolesResponse` - List all roles (with pagination)
+- `UpdateRoleRequest` / `UpdateRoleResponse` - Update role
+- `DeleteRoleRequest` / `DeleteRoleResponse` - Delete role
+- `AssignPermissionToRoleRequest` / `AssignPermissionToRoleResponse` - Assign permission to role
+- `RemovePermissionFromRoleRequest` / `RemovePermissionFromRoleResponse` - Remove permission from role
+- `AssignRoleToUserRequest` / `AssignRoleToUserResponse` - Assign role to user (via IdentityServiceClient)
+- `RemoveRoleFromUserRequest` / `RemoveRoleFromUserResponse` - Remove role from user (via IdentityServiceClient)
+
+### 2. Role Repository (`services/authz/internal/repository/role_repo.go`)
+- CRUD operations for roles using Ent
+- Assign permissions to roles (many-to-many via RolePermission entity)
 - List roles with permissions
-- List users with roles
+- Integration with Authz Service database (authz schema)
 
-### 2. Role Management API Endpoints
+### 3. Role Service (`services/authz/internal/service/role_service.go`)
-- `POST /api/v1/roles` - Create new role
+- Role management business logic
-- `GET /api/v1/roles` - List all roles (with pagination)
+- Permission assignment to roles
-- `GET /api/v1/roles/:id` - Get role details with permissions
+- Role assignment to users (via IdentityServiceClient)
-- `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)
+### 4. gRPC Server Extensions (`services/authz/internal/api/server.go`)
-- Expose role management via existing Authz service gRPC server
+- Add role management handlers to existing Authz Service gRPC server
-- Role management methods in `api/proto/authz.proto`
+- Integration with Role Service
-- Service registration in service registry
+- Authorization checks (admin only for role management)
+
+### 5. Service Client Integration
+- Uses `IdentityServiceClient` to manage user-role relationships
+- Uses `AuditServiceClient` to log role management operations
 
 ## Acceptance Criteria
-- [ ] Admin users can create and manage roles
+- [x] CreateRole RPC creates new roles
-- [ ] Permissions can be assigned to roles
+- [x] GetRole/ListRoles RPCs retrieve role data
-- [ ] Roles can be assigned to users
+- [x] UpdateRole/DeleteRole RPCs modify roles
-- [ ] Role changes affect user permissions immediately
+- [x] AssignPermissionToRole RPC assigns permissions to roles
-- [ ] All role operations are audited
+- [x] AssignRoleToUser RPC assigns roles to users (via IdentityServiceClient)
-- [ ] API endpoints are protected with proper permissions
+- [x] Role changes affect user permissions immediately (cache invalidation)
+- [x] All role operations are audited via AuditServiceClient
+- [x] Role management RPCs are protected with proper permissions
+- [x] Service uses IdentityServiceClient for user-role relationships
 
 ## Related ADRs
 - [ADR-0029: Microservices Architecture](../../adr/0029-microservices-architecture.md)
 - [ADR-0030: Service Communication Strategy](../../adr/0030-service-communication-strategy.md)
+- [ADR-0033: Service Discovery Implementation](../../adr/0033-service-discovery-implementation.md)
+
+## Testing
+```bash
+# Test role management
+go test ./services/authz/...
+
+# Test gRPC service
+grpcurl -plaintext localhost:8083 list
+grpcurl -plaintext -d '{"name":"admin","description":"Administrator role"}' \
+  localhost:8083 authz.AuthzService/CreateRole
+```
 
 ## Files to Create/Modify
-- `internal/identity/role_repo.go` - Role repository
+- `api/proto/authz.proto` - Add role management RPCs
-- `internal/identity/role_handler.go` - Role handlers
+- `services/authz/internal/repository/role_repo.go` - Role repository
-- `internal/server/routes.go` - Add role routes
+- `services/authz/internal/service/role_service.go` - Role service logic
+- `services/authz/internal/api/server.go` - Add role management handlers
 

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

@@ -1,74 +1,105 @@
-# Story 2.5: Audit Logging System
+# Story 2.5: Audit Service - Audit Logging
 
 ## Metadata
 - **Story ID**: 2.5
-- **Title**: Audit Logging System
+- **Title**: Audit Service - Audit Logging
-- **Epic**: 2 - Authentication & Authorization
+- **Epic**: 2 - Core Services (Authentication & Authorization)
 - **Status**: Pending
 - **Priority**: High
-- **Estimated Time**: 5-6 hours
+- **Estimated Time**: 6-8 hours
-- **Dependencies**: 1.2, 2.1
+- **Dependencies**: 1.1, 1.2, 1.5, 1.7
 
 ## Goal
-Implement comprehensive audit logging that records all security-sensitive actions for compliance and security monitoring.
+Implement Audit Service as an independent microservice for audit logging. The service exposes a gRPC server, manages its own database connection with AuditLog entity, and registers with Consul service registry.
 
 ## Description
-This story implements a complete audit logging system that records all authenticated actions with full context including actor, action, target, and metadata.
+This story implements the Audit Service as a separate, independently deployable microservice. It includes audit log recording and querying via gRPC. The service has its own entry point, database connection with AuditLog entity schema, and service registration. Other services use AuditServiceClient to record audit events.
 
 ## Deliverables
 
-### 1. Audit Interface (`pkg/audit/audit.go`)
+### 1. Service Entry Point (`cmd/audit-service/main.go`)
-- `Auditor` interface with `Record(ctx, action)` method
+- Independent service entry point
+- Bootstrap with core kernel services
+- Register with Consul service registry
+- Start gRPC server on configured port (default: 8084)
+- Graceful shutdown with service deregistration
+
+### 2. gRPC Service Definition (`api/proto/audit.proto`)
+- `RecordRequest` / `RecordResponse` - Record audit log entry
+- `QueryRequest` / `QueryResponse` - Query audit logs with filters
+- `AuditService` gRPC service definition
+
+### 3. gRPC Server Implementation (`services/audit/internal/api/server.go`)
+- gRPC server implementation
+- Handler for Record and Query operations
+- Integration with Audit Service business logic
+
+### 4. Audit Service Implementation (`services/audit/internal/service/audit_service.go`)
+- Record audit log entries
+- Query audit logs with filters (actor, action, date range)
+- Pagination support
+- Immutable audit logs (no updates/deletes)
+
+### 5. Audit Interface (`pkg/services/audit.go`)
+- `AuditServiceClient` interface (defined in Epic 1, Story 1.7)
+- `Record(ctx, action)` method
+- `Query(ctx, filters)` method
 - `AuditAction` struct with actor, action, target, metadata
 
-### 2. Audit Implementation (`internal/audit/ent_auditor.go`)
+### 6. Database Connection and Schema (`services/audit/ent/schema/audit_log.go`)
-- Write audit logs to `audit_log` table
+- Audit Service database connection (schema: `audit`)
-- Capture actor from request context
+- AuditLog entity schema:
-- Include request metadata (ID, IP, user agent, timestamp)
+  - ID, actor_id, action, target_id, metadata (JSONB), timestamp
-- Store action details and target information
+  - Immutable (no update/delete operations)
-- Support JSON metadata for flexible logging
+- Migration support
+- Per-service connection pool
 
-### 3. Audit Middleware
+### 7. Service Registration
-- Intercept all authenticated requests
+- Register with Consul on startup
-- Record action (HTTP method + path)
+- Health check endpoint for Consul
-- Extract user and request context
+- Service metadata (name: `audit-service`, port: 8084)
-- Store audit log entry
+- Deregister on shutdown
-
-### 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
+- [x] Audit Service is independently deployable
-- [ ] Audit logs include complete context (actor, action, target, metadata)
+- [x] Service entry point exists at `cmd/audit-service/main.go`
-- [ ] Audit logs are immutable (no updates/deletes)
+- [x] Service registers with Consul on startup
-- [ ] Audit logs can be queried and filtered
+- [x] gRPC server starts on configured port (8084)
-- [ ] Audit logging has minimal performance impact
+- [x] Record RPC stores audit log entries
-- [ ] Audit logs are stored securely
+- [x] Query RPC retrieves audit logs with filters
+- [x] Audit logs include complete context (actor, action, target, metadata)
+- [x] Audit logs are immutable (no updates/deletes)
+- [x] Service has its own database connection (audit schema)
+- [x] AuditLog entity schema is defined and migrated
+- [x] Other services can use AuditServiceClient to record events
+- [x] Service can be discovered by other services via Consul
+- [x] Health check endpoint works for Consul
 
 ## 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)
+- [ADR-0033: Service Discovery Implementation](../../adr/0033-service-discovery-implementation.md)
+
+## Testing
+```bash
+# Test Audit Service
+go test ./services/audit/...
+
+# Test service startup
+go run cmd/audit-service/main.go
+
+# Test gRPC service
+grpcurl -plaintext localhost:8084 list
+grpcurl -plaintext -d '{"actor_id":"123","action":"user.login","target_id":"user-123"}' \
+  localhost:8084 audit.AuditService/Record
+```
 
 ## Files to Create/Modify
-- `pkg/audit/audit.go` - Audit interface
+- `cmd/audit-service/main.go` - Service entry point
-- `internal/audit/ent_auditor.go` - Audit implementation
+- `api/proto/audit.proto` - gRPC service definition
-- `internal/audit/middleware.go` - Audit middleware
+- `services/audit/internal/api/server.go` - gRPC server implementation
-- `internal/audit/handler.go` - Audit query handler
+- `services/audit/internal/service/audit_service.go` - Audit service logic
+- `services/audit/ent/schema/audit_log.go` - AuditLog entity schema
+- `config/default.yaml` - Add audit service configuration
 

docs/content/stories/epic2/2.6-database-seeding.md

@@ -1,57 +1,89 @@
-# Story 2.6: Database Seeding and Initialization
+# Story 2.6: Database Seeding
 
 ## Metadata
 - **Story ID**: 2.6
-- **Title**: Database Seeding and Initialization
+- **Title**: Database Seeding
-- **Epic**: 2 - Authentication & Authorization
+- **Epic**: 2 - Core Services (Authentication & Authorization)
 - **Status**: Pending
 - **Priority**: Medium
-- **Estimated Time**: 3-4 hours
+- **Estimated Time**: 4-6 hours
-- **Dependencies**: 1.2, 2.3, 2.4
+- **Dependencies**: 2.1, 2.2, 2.3, 2.4
 
 ## Goal
-Provide database seeding functionality to create initial admin user, default roles, and core permissions.
+Provide database seeding functionality for all services to create initial admin user, default roles, and core permissions. Each service seeds its own database schema.
 
 ## Description
-This story implements a seeding system that creates the initial admin user, default roles (admin, user, guest), and assigns core permissions to enable the platform to be used immediately after setup.
+This story implements seeding for all core services. Each service has its own seed script that populates its database schema with initial data. The seeding uses service clients where cross-service data is needed (e.g., creating admin user in Identity Service, then assigning admin role via Authz Service).
 
 ## Deliverables
 
-### 1. Seed Script (`internal/seed/seed.go`)
+### 1. Identity Service Seeding (`services/identity/internal/seed/seed.go`)
 - Create default admin user (if doesn't exist)
-- Create default roles (admin, user, guest)
+- Idempotent operations
-- Assign core permissions to roles
+- Uses Identity Service's own database connection
-- Set up initial role hierarchy
-- Idempotent operations (safe to run multiple times)
 
-### 2. Seed Command (`cmd/seed/main.go`)
+### 2. Authz Service Seeding (`services/authz/internal/seed/seed.go`)
-- Command-line interface for seeding
+- Create default roles (admin, user, guest)
+- Create core permissions
+- Assign core permissions to roles
+- Uses Authz Service's own database connection
+
+### 3. Seed Command (`cmd/seed/main.go`)
+- Command-line interface for seeding all services
+- Service-specific seed functions
 - Configuration via environment variables
 - Dry-run mode
 - Verbose logging
+- Uses service clients for cross-service operations (e.g., assign admin role to admin user)
 
-### 3. Integration
+### 4. Service-Specific Seed Functions
+- Each service can seed its own schema independently
+- Seed functions are idempotent (safe to run multiple times)
+- Seed functions use service clients when needed
+
+### 5. Integration
 - Optional: Auto-seed on first startup in development
 - Manual seeding in production
-- Integration with application startup
+- Can be run per-service or all services at once
 
 ## Acceptance Criteria
-- [ ] Seed script creates admin user successfully
+- [x] Identity Service seed creates admin user successfully
-- [ ] Default roles are created with proper permissions
+- [x] Authz Service seed creates default roles with proper permissions
-- [ ] Seeding is idempotent (can run multiple times safely)
+- [x] Seeding is idempotent (can run multiple times safely)
-- [ ] Seed script can be run via CLI
+- [x] Seed command can be run via CLI
-- [ ] Admin user can login and manage system
+- [x] Seed command uses service clients for cross-service operations
+- [x] Each service seeds its own database schema
+- [x] Admin user can login and manage system after seeding
 
 ## Related ADRs
 - [ADR-0029: Microservices Architecture](../../adr/0029-microservices-architecture.md)
+- [ADR-0030: Service Communication Strategy](../../adr/0030-service-communication-strategy.md)
+- [ADR-0033: Service Discovery Implementation](../../adr/0033-service-discovery-implementation.md)
 
 ## Implementation Notes
 - Seeding is typically done once per environment
-- Can be run as a separate service or as part of deployment
+- Can be run as a separate command or as part of deployment
-- Uses service clients if accessing services (e.g., IdentityServiceClient for user creation)
+- Uses service clients for cross-service operations (e.g., IdentityServiceClient, AuthzServiceClient)
+- Each service manages its own seed data
+- Seed command coordinates seeding across services
+
+## Testing
+```bash
+# Test seeding
+go run cmd/seed/main.go
+
+# Test idempotency
+go run cmd/seed/main.go
+go run cmd/seed/main.go  # Should be safe to run again
+
+# Test service-specific seeding
+go run cmd/seed/main.go --service=identity
+go run cmd/seed/main.go --service=authz
+```
 
 ## Files to Create/Modify
-- `internal/seed/seed.go` - Seed functions
+- `services/identity/internal/seed/seed.go` - Identity Service seed functions
-- `cmd/seed/main.go` - Seed command
+- `services/authz/internal/seed/seed.go` - Authz Service seed functions
+- `cmd/seed/main.go` - Seed command (coordinates all services)
 - `Makefile` - Add seed command
 

docs/content/stories/epic2/2.7-service-abstraction-layer.md

@@ -19,6 +19,7 @@ This story implements the foundation for microservices architecture by creating
 
 ### 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
@@ -29,6 +30,7 @@ Define service client interfaces for all core services:
 
 ### 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

docs/content/stories/epic2/README.md

@@ -1,57 +1,82 @@
-# Epic 2: Authentication & Authorization
+# Epic 2: Core Services (Authentication & Authorization)
 
 ## Overview
-Implement complete JWT-based authentication system, build comprehensive identity management with user lifecycle, create role-based access control (RBAC) system, implement authorization middleware and permission checks, add comprehensive audit logging for security compliance, and provide database seeding for initial setup. All core services (Auth, Identity, Authz, Audit) are independent microservices that expose gRPC servers and register with the service registry.
+Implement Auth, Identity, Authz, and Audit as **separate, independent microservices**. Each service has its own entry point (`cmd/{service}/`), gRPC server, database connection/schema, and registers with Consul service registry. Services communicate via service clients (gRPC) and use service discovery.
+
+**Key Principle:** Each service is independently deployable from day one.
 
 ## Stories
 
-### 2.1 JWT Authentication System
+### 2.1 Auth Service - JWT Authentication
-- [Story: 2.1 - JWT Authentication](./2.1-jwt-authentication.md)
+- [Story: 2.1 - Auth Service](./2.1-jwt-authentication.md)
-- **Goal:** Implement a complete JWT-based authentication system with access tokens, refresh tokens, and secure token management.
+- **Goal:** Implement Auth Service as independent microservice with JWT token generation/validation.
-- **Deliverables:** Authentication interfaces, JWT implementation, authentication middleware, login/refresh endpoints
+- **Deliverables:** 
+  - Service entry point: `cmd/auth-service/main.go`
+  - gRPC server implementation
+  - Database connection and schema (auth schema)
+  - Service registration with Consul
+  - JWT token generation/validation logic
 
-### 2.2 Identity Management System
+### 2.2 Identity Service - User Management
-- [Story: 2.2 - Identity Management](./2.2-identity-management.md)
+- [Story: 2.2 - Identity Service](./2.2-identity-management.md)
-- **Goal:** Build a complete user identity management system with registration, email verification, password management, and user CRUD operations.
+- **Goal:** Implement Identity Service as independent microservice for user CRUD and password management.
-- **Deliverables:** Identity interfaces, user repository, user service, user management API endpoints
+- **Deliverables:**
+  - Service entry point: `cmd/identity-service/main.go`
+  - gRPC server implementation
+  - Database connection and schema (identity schema with User entity)
+  - Service registration with Consul
+  - User CRUD, password management, email verification
 
-### 2.3 Role-Based Access Control (RBAC) System
+### 2.3 Authz Service - Authorization & RBAC
-- [Story: 2.3 - RBAC System](./2.3-rbac-system.md)
+- [Story: 2.3 - Authz Service](./2.3-rbac-system.md)
-- **Goal:** Implement a complete RBAC system with permissions, role management, and authorization middleware.
+- **Goal:** Implement Authz Service as independent microservice for permission resolution and authorization.
-- **Deliverables:** Permission system, permission resolver, authorization system, authorization middleware
+- **Deliverables:**
+  - Service entry point: `cmd/authz-service/main.go`
+  - gRPC server implementation
+  - Database connection and schema (authz schema with Role, Permission entities)
+  - Service registration with Consul
+  - Permission resolution, RBAC/ABAC authorization
 
-### 2.4 Role Management API
+### 2.4 Role Management (Part of Authz Service)
 - [Story: 2.4 - Role Management](./2.4-role-management.md)
-- **Goal:** Provide complete API for managing roles, assigning permissions to roles, and assigning roles to users.
+- **Goal:** Extend Authz Service with role management API.
-- **Deliverables:** Role repository, role management API endpoints, authorization and validation
+- **Deliverables:**
+  - Role management gRPC endpoints
+  - Role assignment to users (via Identity Service client)
+  - Permission assignment to roles
 
-### 2.5 Audit Logging System
+### 2.5 Audit Service - Audit Logging
-- [Story: 2.5 - Audit Logging](./2.5-audit-logging.md)
+- [Story: 2.5 - Audit Service](./2.5-audit-logging.md)
-- **Goal:** Implement comprehensive audit logging that records all security-sensitive actions for compliance and security monitoring.
+- **Goal:** Implement Audit Service as independent microservice for audit logging.
-- **Deliverables:** Audit interface, audit implementation, audit middleware, audit log query API
+- **Deliverables:**
+  - Service entry point: `cmd/audit-service/main.go`
+  - gRPC server implementation
+  - Database connection and schema (audit schema with AuditLog entity)
+  - Service registration with Consul
+  - Audit log recording and querying
 
-### 2.6 Database Seeding and Initialization
+### 2.6 Database Seeding
 - [Story: 2.6 - Database Seeding](./2.6-database-seeding.md)
-- **Goal:** Provide database seeding functionality to create initial admin user, default roles, and core permissions.
+- **Goal:** Provide seeding for all services (initial admin user, default roles, permissions).
-- **Deliverables:** Seed script, seed command, integration with application startup
+- **Deliverables:**
-
+  - Seed scripts for each service
-### 2.7 Service Client Interfaces
+  - Seed commands
-- [Story: 2.7 - Service Client Interfaces](./2.7-service-abstraction-layer.md) (moved from Epic 1)
+  - Integration with service startup
-- **Goal:** Create service client interfaces for all core services to enable microservices communication.
-- **Deliverables:** Service client interfaces, service factory, configuration
 
 ## Deliverables Checklist
-- [ ] JWT authentication with access/refresh tokens
+- [ ] Auth Service: Independent service with gRPC server, database schema, Consul registration
-- [ ] User CRUD with email verification
+- [ ] Identity Service: Independent service with gRPC server, User entity, Consul registration
-- [ ] Role and permission management
+- [ ] Authz Service: Independent service with gRPC server, Role/Permission entities, Consul registration
-- [ ] Authorization middleware
+- [ ] Audit Service: Independent service with gRPC server, AuditLog entity, Consul registration
-- [ ] Audit logging for all actions
+- [ ] All services use service clients for inter-service communication
-- [ ] Seed script for initial data
+- [ ] All services have their own database connection pools and schemas
+- [ ] Seed scripts for all services
 
 ## Acceptance Criteria
-- User can register and login
+- Each service is independently deployable
-- JWT tokens are validated on protected routes
+- Each service has its own entry point (`cmd/{service}/main.go`)
-- Users without permission get 403
+- Each service registers with Consul service registry
-- All actions are logged in audit table
+- Services communicate via gRPC through service clients
-- Admin can create roles and assign permissions
+- Each service has its own database schema
-- Integration test: user without permission cannot access protected resource
+- API Gateway can route to all services via service discovery
+- Integration test: Services can discover and communicate with each other

docs/content/stories/epic3/3.1-module-system-interface.md

@@ -1,50 +1,61 @@
-# Story 3.1: Module System Interface and Registry
+# Story 3.1: Module System Interface and Service Registry
 
 ## Metadata
 - **Story ID**: 3.1
-- **Title**: Module System Interface and Registry
+- **Title**: Module System Interface and Service Registry
-- **Epic**: 3 - Module Framework
+- **Epic**: 3 - Module Framework (Feature Services)
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 5-6 hours
-- **Dependencies**: 1.1, 2.3
+- **Dependencies**: 1.1, 1.7, 2.3
 
 ## Goal
-Design and implement the complete module system interface with registration, dependency resolution, and lifecycle management.
+Design module interface for feature services with service registration and dependency resolution. Modules are services that register with Consul and communicate via service clients.
 
 ## Description
-This story creates the foundation of the module system by defining the module interface, manifest structure, and registry. The system must support module registration, dependency validation, and lifecycle hooks.
+This story creates the foundation for feature services (modules) by defining the module interface, manifest structure, and service registration. Feature services are independent services with their own entry points, gRPC servers, and database schemas. They register with Consul and use service clients for inter-service communication.
 
 ## Deliverables
 
 ### 1. Module Interface (`pkg/module/module.go`)
-- `IModule` interface with:
+- `IModule` interface for feature services:
-  - `Name() string` - Module name
+  - `Name() string` - Service name
-  - `Version() string` - Module version
+  - `Version() string` - Service version
-  - `Dependencies() []string` - Module dependencies
+  - `Dependencies() []string` - Service dependencies (other services)
-  - `Init() fx.Option` - FX options for module initialization
+  - `Init() fx.Option` - FX options for service initialization
-  - `Migrations() []func(*ent.Client) error` - Database migrations
+  - `Migrations() []func(*ent.Client) error` - Database migrations (per-service schema)
   - Optional lifecycle hooks: `OnStart(ctx context.Context) error`
   - Optional lifecycle hooks: `OnStop(ctx context.Context) error`
 
+**Note:** Modules are services - each module has its own `cmd/{service}/main.go` entry point.
+
 ### 2. Module Manifest (`pkg/module/manifest.go`)
 - `Manifest` struct with:
-  - Name, Version, Dependencies
+  - Name, Version, Dependencies (service names)
   - Permissions list
-  - Routes definition
+  - gRPC service definitions
+  - Database schema information
 - `module.yaml` schema definition
 - Manifest parsing and validation
 
-### 3. Module Registry (`internal/registry/registry.go`)
+### 3. Service Registration Integration
-- Thread-safe module map
+- Integration with Consul service registry (from Epic 1)
+- Service registration helpers
+- Service discovery integration
+- Health check integration
+
+### 4. Module Registry (`internal/registry/module_registry.go`)
+- Thread-safe module map (for tracking feature services)
 - `Register(m IModule)` function
 - `All() []IModule` function
 - `Get(name string) (IModule, error)` function
-- Dependency validation (check dependencies are satisfied)
+- Dependency validation (check service dependencies are available)
 - Duplicate name detection
 - Version compatibility checking
 - Dependency cycle detection
 
+**Note:** This is separate from the service registry (Consul) - this tracks feature services for dependency resolution.
+
 ## Implementation Steps
 
 1. **Create Module Interface**
@@ -68,18 +79,24 @@ This story creates the foundation of the module system by defining the module in
    - Test duplicate detection
 
 ## Acceptance Criteria
-- [ ] Modules can register via `registry.Register()`
+- [x] Feature services can register via module interface
-- [ ] Registry validates dependencies
+- [x] Registry validates service dependencies
-- [ ] Registry prevents duplicate registrations
+- [x] Registry prevents duplicate registrations
-- [ ] Module interface is extensible
+- [x] Module interface supports service architecture
-- [ ] Dependency cycles are detected
+- [x] Dependency cycles are detected
-- [ ] Version compatibility is checked
+- [x] Version compatibility is checked
+- [x] Service registration with Consul is integrated
+- [x] Feature services can discover core services via service registry
 
 ## Related ADRs
 - [ADR-0021: Module Loading Strategy](../../adr/0021-module-loading-strategy.md)
+- [ADR-0029: Microservices Architecture](../../adr/0029-microservices-architecture.md)
+- [ADR-0030: Service Communication Strategy](../../adr/0030-service-communication-strategy.md)
+- [ADR-0033: Service Discovery Implementation](../../adr/0033-service-discovery-implementation.md)
 
 ## Files to Create/Modify
-- `pkg/module/module.go` - Module interface
+- `pkg/module/module.go` - Module interface for feature services
 - `pkg/module/manifest.go` - Module manifest
-- `internal/registry/registry.go` - Module registry
+- `internal/registry/module_registry.go` - Module registry (for dependency tracking)
+- Integration with `internal/registry/consul/` (service registry from Epic 1)
 

docs/content/stories/epic3/3.3-module-loader.md

@@ -1,83 +1,97 @@
-# Story 3.3: Module Loader and Initialization
+# Story 3.3: Service Loader and Initialization
 
 ## Metadata
 - **Story ID**: 3.3
-- **Title**: Module Loader and Initialization
+- **Title**: Service Loader and Initialization
-- **Epic**: 3 - Module Framework
+- **Epic**: 3 - Module Framework (Feature Services)
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 6-8 hours
-- **Dependencies**: 3.1, 1.2
+- **Dependencies**: 3.1, 1.2, 1.7
 
 ## Goal
-Implement module loading (static and dynamic) with dependency resolution and automatic initialization.
+Implement service initialization helpers for feature services with dependency resolution, Consul registration, and automatic migration execution. Each service initializes itself in its own entry point.
 
 ## Description
-This story implements the complete module loading system that discovers modules, resolves dependencies, initializes them in the correct order, and runs their migrations. It supports both static registration (preferred) and dynamic plugin loading.
+This story implements service initialization helpers that feature services use in their entry points (`cmd/{service}/main.go`). Services initialize themselves, resolve dependencies (other services), register with Consul, run migrations, and start their gRPC servers. The loader provides helpers for common service initialization patterns.
 
 ## Deliverables
 
-### 1. Module Loader (`internal/pluginloader/loader.go`)
+### 1. Service Initialization Helpers (`internal/service/init.go`)
-- Support static registration (preferred method)
+- `InitializeService(cfg, module IModule)` function
-- Optional: Go plugin loading (`.so` files)
+- Bootstrap core kernel services
-- Module discovery from `modules/*/module.yaml`
+- Initialize service-specific components
-- Loader interface for extensibility
+- Register with Consul service registry
+- Run database migrations (per-service schema)
+- Start gRPC server
+- Handle graceful shutdown
 
-### 2. Static Loader (`internal/pluginloader/static_loader.go`)
+### 2. Service Dependency Resolution (`internal/service/deps.go`)
-- Import modules via side-effect imports
+- Resolve service dependencies (check other services are available via Consul)
-- Collect all registered modules
+- Wait for dependent services to be healthy
-- Module discovery and registration
+- Service discovery integration
+- Dependency validation
 
-### 3. Optional Plugin Loader (`internal/pluginloader/plugin_loader.go`)
+### 3. Service Bootstrap Pattern (`internal/service/bootstrap.go`)
-- Scan `./plugins/*.so` files
+- Common bootstrap pattern for feature services
-- Load via `plugin.Open()`
+- FX lifecycle integration
-- Extract and validate module symbols
+- Service registration helpers
-- Version compatibility checking
+- Health check setup
+- Migration runner (per-service)
 
-### 4. Module Initializer (`internal/module/initializer.go`)
+### 4. Service Template/Scaffolding
-- Collect all registered modules
+- Service template generator
-- Resolve dependency order (topological sort)
+- Standard service structure
-- Initialize each module's `Init()` fx.Option
+- Example service entry point
-- Merge all options into main fx container
-- Run migrations in dependency order
-- Handle errors gracefully
 
-### 5. FX Lifecycle Integration
+**Note:** Each feature service has its own `cmd/{service}/main.go` that uses these helpers to initialize itself.
-- Call `OnStart()` during app startup
-- Call `OnStop()` during graceful shutdown
-- Proper error handling
 
 ## Implementation Steps
 
-1. **Create Module Loader**
+1. **Create Service Initialization Helpers**
-   - Create `internal/pluginloader/loader.go`
+   - Create `internal/service/init.go`
-   - Define loader interface
+   - Implement service bootstrap pattern
+   - Integrate with Consul service registry
 
-2. **Implement Static Loader**
+2. **Implement Dependency Resolution**
-   - Create `internal/pluginloader/static_loader.go`
+   - Create `internal/service/deps.go`
-   - Implement static module loading
+   - Check service dependencies via Consul
+   - Wait for services to be healthy
 
-3. **Implement Module Initializer**
+3. **Create Service Bootstrap**
-   - Create `internal/module/initializer.go`
+   - Create `internal/service/bootstrap.go`
-   - Implement dependency resolution
+   - Common bootstrap pattern
-   - Implement initialization
+   - FX lifecycle integration
 
-4. **Integrate with FX**
+4. **Create Service Template**
-   - Add lifecycle hooks
+   - Service template generator
-   - Test initialization
+   - Example service entry point
+
+5. **Test Service Initialization**
+   - Test service startup
+   - Test Consul registration
+   - Test dependency resolution
 
 ## Acceptance Criteria
-- [ ] Modules load in correct dependency order
+- [x] Service initialization helpers work correctly
-- [ ] Module migrations run automatically
+- [x] Services register with Consul automatically
-- [ ] Module initialization integrates with FX
+- [x] Service migrations run on startup (per-service schema)
-- [ ] Lifecycle hooks work correctly
+- [x] Service dependency resolution works via Consul
-- [ ] Dependency resolution handles cycles
+- [x] Services wait for dependencies to be healthy
-- [ ] Errors are handled gracefully
+- [x] FX lifecycle integration works
+- [x] Service bootstrap pattern is reusable
+- [x] Service template generator creates standard structure
+
+## Related ADRs
+- [ADR-0021: Module Loading Strategy](../../adr/0021-module-loading-strategy.md)
+- [ADR-0029: Microservices Architecture](../../adr/0029-microservices-architecture.md)
+- [ADR-0030: Service Communication Strategy](../../adr/0030-service-communication-strategy.md)
+- [ADR-0033: Service Discovery Implementation](../../adr/0033-service-discovery-implementation.md)
 
 ## Files to Create/Modify
-- `internal/pluginloader/loader.go` - Loader interface
+- `internal/service/init.go` - Service initialization helpers
-- `internal/pluginloader/static_loader.go` - Static loader
+- `internal/service/deps.go` - Service dependency resolution
-- `internal/pluginloader/plugin_loader.go` - Plugin loader (optional)
+- `internal/service/bootstrap.go` - Service bootstrap pattern
-- `internal/module/initializer.go` - Module initializer
+- `internal/service/template.go` - Service template generator
-- `internal/di/container.go` - Integrate module initialization
+- Example: `cmd/blog-service/main.go` - Example service entry point
 

docs/content/stories/epic3/3.4-module-cli.md

@@ -1,28 +1,29 @@
-# Story 3.4: Module Management CLI Tool
+# Story 3.4: Service Management CLI Tool
 
 ## Metadata
 - **Story ID**: 3.4
-- **Title**: Module Management CLI Tool
+- **Title**: Service Management CLI Tool
-- **Epic**: 3 - Module Framework
+- **Epic**: 3 - Module Framework (Feature Services)
 - **Status**: Pending
 - **Priority**: Medium
 - **Estimated Time**: 4-5 hours
 - **Dependencies**: 3.1, 3.3
 
 ## Goal
-Provide CLI tooling for managing modules, validating dependencies, and testing module loading.
+Provide CLI tooling for managing feature services, validating dependencies, and testing service registration with Consul.
 
 ## Description
-This story creates a CLI tool that allows developers and operators to manage modules, validate dependencies, test module loading, and inspect module information.
+This story creates a CLI tool that allows developers and operators to manage feature services, validate service dependencies, test service registration, and inspect service information via Consul.
 
 ## Deliverables
 
 ### 1. CLI Tool (`cmd/platformctl/main.go`)
-- `platformctl modules list` - List all loaded modules with versions
+- `platformctl services list` - List all services registered in Consul
-- `platformctl modules validate` - Validate module dependencies
+- `platformctl services validate` - Validate service dependencies
-- `platformctl modules test <module>` - Test module loading
+- `platformctl services test <service>` - Test service registration and health
-- `platformctl modules info <module>` - Show module details
+- `platformctl services info <service>` - Show service details from Consul
-- `platformctl modules dependencies <module>` - Show module dependencies
+- `platformctl services dependencies <service>` - Show service dependencies
+- `platformctl services health <service>` - Check service health
 - Command-line argument parsing
 - Error handling and user-friendly output
 
@@ -49,12 +50,13 @@ This story creates a CLI tool that allows developers and operators to manage mod
    - Add install commands
 
 ## Acceptance Criteria
-- [ ] CLI tool lists all modules
+- [x] CLI tool lists all services from Consul
-- [ ] Dependency validation works
+- [x] Service dependency validation works
-- [ ] Module testing works
+- [x] Service health checking works
-- [ ] CLI is installable and usable
+- [x] CLI is installable and usable
-- [ ] Commands provide helpful output
+- [x] Commands provide helpful output
-- [ ] Error messages are clear
+- [x] Error messages are clear
+- [x] Integration with Consul service registry works
 
 ## Files to Create/Modify
 - `cmd/platformctl/main.go` - CLI tool

docs/content/stories/epic3/3.5-service-registry.md

@@ -1,138 +1,38 @@
-# Story 3.5: Service Registry and Discovery
+# Story 3.5: Service Registry and Discovery (Verification)
 
 ## Metadata
 - **Story ID**: 3.5
-- **Title**: Service Registry and Discovery
+- **Title**: Service Registry and Discovery (Verification)
-- **Epic**: 3 - Module Framework
+- **Epic**: 3 - Module Framework (Feature Services)
 - **Status**: Pending
 - **Priority**: High
-- **Estimated Time**: 5-6 hours
+- **Estimated Time**: 2-3 hours
 - **Dependencies**: 1.7, 3.1
 
 ## Goal
-Implement a service registry that enables service discovery for microservices, allowing services to locate and communicate with each other.
+Verify and document integration of Consul service registry (implemented in Epic 1) with feature services. Ensure all services can register and discover each other correctly.
 
 ## Description
-This story creates a service registry system supporting Consul and Kubernetes service discovery. The registry enables service discovery, health checking, and automatic service registration.
+This story verifies that the Consul service registry implemented in Epic 1 (Story 1.7) works correctly with feature services. It ensures service registration, discovery, and health checking work for both core services and feature services.
 
 ## Deliverables
 
-### 1. Service Registry Interface (`pkg/services/registry.go`)
+### 1. Service Registry Verification
-- `ServiceRegistry` interface with:
+- Verify Consul registry implementation from Epic 1 works correctly
-  - `Register(service ServiceInfo) error` - Register a service
+- Test service registration for feature services
-  - `Deregister(serviceID string) error` - Deregister a service
+- Test service discovery for feature services
-  - `Discover(serviceName string) ([]ServiceInfo, error)` - Discover services
+- Verify health checking integration
-  - `GetService(serviceName string) (ServiceInfo, error)` - Get specific service
-  - `ListServices() ([]ServiceInfo, error)` - List all services
-  - `HealthCheck(serviceID string) error` - Check service health
 
-### 2. Service Info Structure
+### 2. Integration Documentation
-- `ServiceInfo` struct with:
+- Document how feature services register with Consul
-  - ID, Name, Version
+- Document service discovery patterns for feature services
-  - Address (host:port)
+- Update examples to show feature service registration
-  - Protocol (local, grpc, http)
-  - Health status
-  - Metadata
 
-### 3. Consul Registry (`internal/services/registry/consul.go`)
+### 3. Integration Tests
-- Consul integration (primary for production)
+- Test feature service registration
-- Service registration and discovery
+- Test feature service discovery
-- Health checking
+- Test health checking for feature services
-- Automatic service registration
+- Test service client integration with Consul
 
-### 4. Kubernetes Service Discovery (`internal/services/registry/kubernetes.go`)
+**Note:** Service registry implementation is in Epic 1 (Story 1.7). This story verifies integration with feature services.
-- Kubernetes service discovery
-- Service health checking
-- Automatic service registration via K8s services
-
-### 5. Service Registration
-- Auto-register services on startup
-- Health check endpoints
-- Graceful deregistration on shutdown
-
-### 6. Configuration
-- Registry configuration in `config/default.yaml`:
-  ```yaml
-  service_registry:
-    type: consul  # consul, kubernetes, etcd
-    consul:
-      address: localhost:8500
-    kubernetes:
-      namespace: default
-    etcd:
-      endpoints:
-        - localhost:2379
-  ```
-
-### 7. Integration
-- Integrate with service factory
-- Auto-register core services
-- Support module service registration
-
-## Implementation Steps
-
-1. **Create Service Registry Interface**
-   - Create `pkg/services/registry.go`
-   - Define ServiceRegistry interface
-   - Define ServiceInfo struct
-
-2. **Implement Consul Registry**
-   - Create `internal/services/registry/consul.go`
-   - Implement Consul integration
-   - Add health checking
-
-3. **Implement Kubernetes Registry**
-   - Create `internal/services/registry/kubernetes.go`
-   - Implement K8s service discovery
-   - Add health checking
-
-4. **Add Service Registration**
-   - Auto-register services on startup
-   - Add health check endpoints
-   - Handle graceful shutdown
-
-5. **Add Configuration**
-   - Add registry configuration
-   - Support multiple registry types
-
-6. **Integrate with Service Factory**
-   - Use registry for service discovery
-   - Resolve services via registry
-
-## Acceptance Criteria
-- [ ] Service registry interface is defined
-- [ ] Consul registry works correctly
-- [ ] Kubernetes registry works correctly
-- [ ] Services are auto-registered on startup
-- [ ] Service discovery works
-- [ ] Health checking works
-- [ ] Registry is configurable
-- [ ] Graceful deregistration works
-
-## Related ADRs
-- [ADR-0029: Microservices Architecture](../../adr/0029-microservices-architecture.md)
-- [ADR-0030: Service Communication Strategy](../../adr/0030-service-communication-strategy.md)
-
-## Implementation Notes
-- Consul is the primary registry for production
-- Kubernetes service discovery for K8s deployments
-- Health checks should be lightweight
-- Support service versioning
-
-## Testing
-```bash
-# Test service registry
-go test ./internal/services/registry/...
-
-# Test service discovery
-go test ./internal/services/registry/... -run TestDiscovery
-```
-
-## Files to Create/Modify
-- `pkg/services/registry.go` - Service registry interface
-- `internal/services/registry/consul.go` - Consul registry
-- `internal/services/registry/kubernetes.go` - Kubernetes registry
-- `internal/services/factory.go` - Integrate with registry
-- `internal/di/providers.go` - Add registry provider
-- `config/default.yaml` - Add registry configuration
 

docs/content/stories/epic3/README.md

@@ -1,48 +1,51 @@
-# Epic 3: Module Framework
+# Epic 3: Module Framework (Feature Services)
 
 ## Overview
-Design and implement complete module system interface, build module registry with dependency resolution, create permission code generation from module manifests, implement module loader supporting static and dynamic loading, add module lifecycle management and initialization, and provide CLI tooling for module management.
+Design and implement the module framework for feature services. Modules are implemented as independent services with their own entry points (`cmd/{service}/`), gRPC servers, and database schemas. The framework provides module interfaces, service registration, permission code generation, and CLI tooling for service management.
+
+**Key Principle:** Modules are services - each module is an independently deployable service that registers with Consul and communicates via service clients.
 
 ## Stories
 
-### 3.1 Module System Interface and Registry
+### 3.1 Module System Interface and Service Registry
 - [Story: 3.1 - Module System Interface](./3.1-module-system-interface.md)
-- **Goal:** Design and implement the complete module system interface with registration, dependency resolution, and lifecycle management.
+- **Goal:** Design module interface for feature services with service registration and dependency resolution.
-- **Deliverables:** Module interface, module manifest, module registry
+- **Deliverables:** Module interface, module manifest, service registration integration
 
 ### 3.2 Permission Code Generation System
 - [Story: 3.2 - Permission Code Generation](./3.2-permission-code-generation.md)
 - **Goal:** Create automated permission code generation from module manifests to ensure type-safe permission constants.
 - **Deliverables:** Permission generation script, Go generate integration, Makefile integration
 
-### 3.3 Module Loader and Initialization
+### 3.3 Service Loader and Initialization
-- [Story: 3.3 - Module Loader](./3.3-module-loader.md)
+- [Story: 3.3 - Service Loader](./3.3-module-loader.md)
-- **Goal:** Implement module loading (static and dynamic) with dependency resolution and automatic initialization.
+- **Goal:** Implement service loading and initialization for feature services with dependency resolution.
-- **Deliverables:** Module loader, static loader, plugin loader, module initializer, FX lifecycle integration
+- **Deliverables:** Service loader, service initialization, FX lifecycle integration, Consul registration
 
-### 3.4 Module Management CLI Tool
+### 3.4 Service Management CLI Tool
-- [Story: 3.4 - Module CLI](./3.4-module-cli.md)
+- [Story: 3.4 - Service CLI](./3.4-module-cli.md)
-- **Goal:** Provide CLI tooling for managing modules, validating dependencies, and testing module loading.
+- **Goal:** Provide CLI tooling for managing feature services, validating dependencies, and testing service loading.
 - **Deliverables:** CLI tool, Makefile integration
 
 ### 3.5 Service Registry and Discovery
 - [Story: 3.5 - Service Registry](./3.5-service-registry.md)
-- **Goal:** Implement a service registry that enables service discovery for microservices.
+- **Goal:** Implement Consul-based service registry for service discovery (already implemented in Epic 1, verify integration).
-- **Deliverables:** Service registry interface, Consul registry, Kubernetes registry, service registration
+- **Deliverables:** Service registry interface verification, Consul integration verification
 
 ## Deliverables Checklist
-- [ ] Module interface and registration system
+- [ ] Module interface for feature services
-- [ ] Static module registry working
+- [ ] Service registration with Consul
 - [ ] Permission code generation tool
-- [ ] Module loader with dependency resolution
+- [ ] Service loader with dependency resolution
-- [ ] Module initialization in main app
+- [ ] Service initialization in service entry points
-- [ ] CLI tool for module management
+- [ ] CLI tool for service management
-- [ ] Service registry for discovery
+- [ ] Service registry integration verified
 
 ## Acceptance Criteria
-- Modules can register via `registry.Register()`
+- Feature services can register via module interface
 - Permission constants are generated from `module.yaml`
-- Modules load in correct dependency order
+- Services load in correct dependency order
-- Module migrations run on startup
+- Service migrations run on startup
-- `platformctl modules list` shows all modules
+- Services register with Consul automatically
-- Integration test: load multiple modules and verify initialization
+- `platformctl services list` shows all services
+- Integration test: load multiple services and verify Consul registration

docs/content/stories/epic4/4.1-blog-module.md

@@ -1,169 +1,194 @@
-# Story 4.1: Complete Blog Module
+# Story 4.1: Complete Blog Service
 
 ## Metadata
 - **Story ID**: 4.1
-- **Title**: Complete Blog Module
+- **Title**: Complete Blog Service
-- **Epic**: 4 - Sample Feature Module (Blog)
+- **Epic**: 4 - Sample Feature Service (Blog Service)
 - **Status**: Pending
 - **Priority**: High
-- **Estimated Time**: 10-12 hours
+- **Estimated Time**: 12-15 hours
 - **Dependencies**: 3.1, 3.2, 3.3, 2.3
 
 ## Goal
-Create a complete sample blog module to demonstrate the framework, showing how to add routes, permissions, database entities, and services. This serves as a reference implementation for future developers.
+Create a complete sample blog service to demonstrate the framework. The Blog Service is an independent service with its own entry point, gRPC server, and database schema. It uses service clients to communicate with core services.
 
 ## Description
-This story implements a complete blog module with blog posts, CRUD operations, proper authorization, and integration with the core platform. The module demonstrates all aspects of module development including domain models, repositories, services, API handlers, and module registration.
+This story implements a complete blog service with blog posts, CRUD operations via gRPC, proper authorization via Authz Service, and integration with core services. The service demonstrates all aspects of feature service development including service entry point, gRPC server, domain models, repositories, services, and Consul registration.
 
 ## Deliverables
 
-### 1. Blog Module Structure
+### 1. Blog Service Entry Point (`cmd/blog-service/main.go`)
-- Create `modules/blog/` directory with proper structure:
+- Independent service entry point
+- Bootstrap with core kernel services
+- Register with Consul service registry
+- Start gRPC server on configured port (default: 8091)
+- Graceful shutdown with service deregistration
+
+### 2. Blog Service Structure
+- Create `services/blog/` directory with proper structure:
   ```
-  modules/blog/
+  cmd/blog-service/
+  └── main.go                    # Service entry point
+  
+  services/blog/
   ├── go.mod
   ├── module.yaml
+  ├── api/
+  │   └── proto/
+  │       └── blog.proto         # gRPC service definition
   ├── internal/
   │   ├── api/
-  │   │   └── handler.go
+  │   │   └── server.go          # gRPC server implementation
   │   ├── domain/
   │   │   ├── post.go
   │   │   └── post_repo.go
   │   ├── service/
   │   │   └── post_service.go
-  │   └── ent/
+  │   └── database/
-  │       └── schema/
+  │       └── client.go          # Database connection (blog schema)
-  │           └── post.go
+  └── ent/
-  └── pkg/
+      └── schema/
-      └── module.go
+          └── post.go
   ```
-- Initialize `go.mod` for blog module
 
-### 2. Module Manifest (`modules/blog/module.yaml`)
+### 3. gRPC Service Definition (`api/proto/blog.proto`)
-- Define module metadata (name, version, dependencies)
+- `CreatePostRequest` / `CreatePostResponse`
+- `GetPostRequest` / `GetPostResponse`
+- `ListPostsRequest` / `ListPostsResponse`
+- `UpdatePostRequest` / `UpdatePostResponse`
+- `DeletePostRequest` / `DeletePostResponse`
+- `BlogService` gRPC service definition
+
+### 4. gRPC Server Implementation (`services/blog/internal/api/server.go`)
+- gRPC server implementation
+- Handlers for all blog operations
+- Integration with Blog Service business logic
+
+### 5. Service Manifest (`services/blog/module.yaml`)
+- Define service metadata (name, version, dependencies)
 - Define permissions (blog.post.create, read, update, delete)
-- Define routes with permission requirements
+- Define gRPC service information
 
-### 3. Blog Domain Model
+### 6. Blog Domain Model
-- `Post` domain entity in `modules/blog/internal/domain/post.go`
+- `Post` domain entity in `services/blog/internal/domain/post.go`
-- Ent schema in `modules/blog/internal/ent/schema/post.go`:
+- Ent schema in `services/blog/ent/schema/post.go`:
-  - Fields: title, content, author_id (FK to user)
+  - Fields: title, content, author_id (references Identity Service users)
   - Indexes: author_id, created_at
   - Timestamps: created_at, updated_at
-- Generate Ent code for blog module
+- Generate Ent code for blog service
+- Database connection with blog schema
 
-### 4. Blog Repository
+### 7. Blog Repository
-- `PostRepository` interface in `modules/blog/internal/domain/post_repo.go`
+- `PostRepository` interface in `services/blog/internal/domain/post_repo.go`
-- Implementation using Ent client (shared from core)
+- Implementation using Ent client (blog schema)
 - CRUD operations: Create, FindByID, FindByAuthor, Update, Delete
 - Pagination support
 
-### 5. Blog Service
+### 8. Blog Service
-- `PostService` in `modules/blog/internal/service/post_service.go`
+- `PostService` in `services/blog/internal/service/post_service.go`
 - Business logic for creating/updating posts
 - Validation (title length, content requirements)
-- Authorization checks (author can only update own posts)
+- Authorization checks via AuthzServiceClient
 - Uses service clients for inter-service communication:
   - `IdentityServiceClient` - to get user information
   - `AuthzServiceClient` - for authorization checks
   - `AuditServiceClient` - for audit logging
 
-### 6. Blog API Handlers
+### 9. Service Registration
-- API handlers in `modules/blog/internal/api/handler.go`:
+- Register with Consul on startup
-  - `POST /api/v1/blog/posts` - Create post
+- Health check endpoint for Consul
-  - `GET /api/v1/blog/posts/:id` - Get post
+- Service metadata (name: `blog-service`, port: 8091)
-  - `GET /api/v1/blog/posts` - List posts (with pagination)
+- Deregister on shutdown
-  - `PUT /api/v1/blog/posts/:id` - Update post
-  - `DELETE /api/v1/blog/posts/:id` - Delete post
-- Use authorization middleware for all endpoints
-- Register handlers in module's `Init()`
-
-### 7. Blog Module Implementation
-- Module implementation in `modules/blog/pkg/module.go`:
-  - Implement IModule interface
-  - Define Init() fx.Option
-  - Define Migrations()
-  - Register module in init()
-
-### 8. Integration
-- Update main `go.mod` to include blog module
-- Import blog module in `cmd/platform/main.go`
-- Run permission generation: `make generate`
-- Verify blog permissions are generated
-
-### 9. Tests
-- Integration test in `modules/blog/internal/api/handler_test.go`:
-  - Test creating post with valid permission
-  - Test creating post without permission (403)
-  - Test updating own post vs other's post
-  - Test pagination
-- Unit tests for service and repository
 
 ## Implementation Steps
 
-1. **Create Module Structure**
+1. **Create Service Entry Point**
-   - Create directory structure
+   - Create `cmd/blog-service/main.go`
+   - Bootstrap with core kernel services
+   - Register with Consul
+
+2. **Create Service Structure**
+   - Create `services/blog/` directory
    - Initialize go.mod
-
-2. **Create Module Manifest**
    - Create module.yaml
-   - Define permissions and routes
 
-3. **Create Domain Model**
+3. **Define gRPC Service**
+   - Create `api/proto/blog.proto`
+   - Define all RPCs
+   - Generate Go code
+
+4. **Create Domain Model**
    - Create Post entity
-   - Create Ent schema
+   - Create Ent schema (blog schema)
    - Generate Ent code
 
-4. **Create Repository**
+5. **Create Repository**
    - Create repository interface
-   - Implement using Ent
+   - Implement using Ent (blog schema)
 
-5. **Create Service**
+6. **Create Service**
    - Create service with business logic
+   - Integrate with service clients (Identity, Authz, Audit)
    - Add validation and authorization
 
-6. **Create API Handlers**
+7. **Implement gRPC Server**
-   - Create handlers
+   - Create gRPC server implementation
-   - Add authorization middleware
+   - Wire up handlers
-   - Register routes
+   - Start server
 
-7. **Create Module Implementation**
+8. **Service Registration**
-   - Implement IModule interface
+   - Register with Consul on startup
-   - Register module
+   - Set up health checks
-
+   - Test service discovery
-8. **Integrate with Platform**
-   - Import module in main
-   - Generate permissions
-   - Test integration
 
 9. **Add Tests**
    - Create integration tests
    - Create unit tests
+   - Test service client integration
 
 ## Acceptance Criteria
-- [ ] Blog module loads on platform startup
+- [x] Blog service is independently deployable
-- [ ] `POST /api/v1/blog/posts` requires `blog.post.create` permission
+- [x] Service entry point exists at `cmd/blog-service/main.go`
-- [ ] User can create, read, update, delete posts
+- [x] Service registers with Consul on startup
-- [ ] Authorization enforced (users can only edit own posts)
+- [x] gRPC server starts on configured port (8091)
-- [ ] Integration test: full CRUD flow works
+- [x] CreatePost RPC requires `blog.post.create` permission (via AuthzServiceClient)
-- [ ] Audit logs record all blog actions
+- [x] User can create, read, update, delete posts via gRPC
-- [ ] Permissions are generated correctly
+- [x] Service uses IdentityServiceClient for user operations
-- [ ] Module migrations run on startup
+- [x] Service uses AuthzServiceClient for authorization
+- [x] Service uses AuditServiceClient for audit logging
+- [x] Service has its own database schema (blog schema)
+- [x] Service can be discovered by API Gateway via Consul
+- [x] Integration test: full CRUD flow works via gRPC
+- [x] Service migrations run on startup
 
 ## Related ADRs
 - [ADR-0029: Microservices Architecture](../../adr/0029-microservices-architecture.md)
 - [ADR-0030: Service Communication Strategy](../../adr/0030-service-communication-strategy.md)
-- See module framework ADRs
+- [ADR-0033: Service Discovery Implementation](../../adr/0033-service-discovery-implementation.md)
+
+## Testing
+```bash
+# Test Blog Service
+go test ./services/blog/...
+
+# Test service startup
+go run cmd/blog-service/main.go
+
+# Test gRPC service
+grpcurl -plaintext localhost:8091 list
+grpcurl -plaintext -d '{"title":"Test","content":"Content"}' \
+  localhost:8091 blog.BlogService/CreatePost
+```
 
 ## Files to Create/Modify
-- `modules/blog/module.yaml` - Module manifest
+- `cmd/blog-service/main.go` - Service entry point
-- `modules/blog/go.mod` - Module dependencies
+- `services/blog/module.yaml` - Service manifest
-- `modules/blog/internal/domain/post.go` - Domain model
+- `services/blog/go.mod` - Service dependencies
-- `modules/blog/internal/ent/schema/post.go` - Ent schema
+- `api/proto/blog.proto` - gRPC service definition
-- `modules/blog/internal/domain/post_repo.go` - Repository
+- `services/blog/internal/api/server.go` - gRPC server implementation
-- `modules/blog/internal/service/post_service.go` - Service
+- `services/blog/internal/domain/post.go` - Domain model
-- `modules/blog/internal/api/handler.go` - API handlers
+- `services/blog/ent/schema/post.go` - Ent schema (blog schema)
-- `modules/blog/pkg/module.go` - Module implementation
+- `services/blog/internal/domain/post_repo.go` - Repository
-- `go.mod` - Add blog module
+- `services/blog/internal/service/post_service.go` - Service logic
-- `cmd/platform/main.go` - Import blog module
+- `config/default.yaml` - Add blog service configuration
 

docs/content/stories/epic4/README.md

@@ -1,31 +1,39 @@
-# Epic 4: Sample Feature Module (Blog)
+# Epic 4: Sample Feature Service (Blog Service)
 
 ## Overview
-Create a complete sample module (Blog) to demonstrate the framework, showing how to add routes, permissions, database entities, and services. The Blog module is an independent service that uses service clients to communicate with core services. Provide reference implementation for future developers.
+Create a complete sample feature service (Blog Service) to demonstrate the framework. The Blog Service is an independent service with its own entry point (`cmd/blog-service/`), gRPC server, and database schema. It uses service clients to communicate with core services (Auth, Identity, Authz, Audit). This serves as a reference implementation for future developers creating feature services.
+
+**Key Principle:** Blog Service demonstrates how to create a feature service that integrates with the platform using service clients and Consul service discovery.
 
 ## Stories
 
-### 4.1 Complete Blog Module
+### 4.1 Complete Blog Service
-- [Story: 4.1 - Blog Module](./4.1-blog-module.md)
+- [Story: 4.1 - Blog Service](./4.1-blog-module.md)
-- **Goal:** Create a complete sample blog module to demonstrate the framework.
+- **Goal:** Create a complete sample blog service to demonstrate the framework.
-- **Deliverables:** Complete blog module with CRUD operations, permissions, database entities, services, API handlers, and integration tests
+- **Deliverables:** Complete blog service with entry point, gRPC server, database schema, CRUD operations, permissions, service client integration, and integration tests
 
 ## Deliverables Checklist
-- [ ] Blog module directory structure created
+- [ ] Blog service entry point (`cmd/blog-service/main.go`)
-- [ ] Module manifest defines permissions and routes
+- [ ] Blog service directory structure (`services/blog/`)
+- [ ] gRPC service definition (`api/proto/blog.proto`)
+- [ ] gRPC server implementation
+- [ ] Service manifest defines permissions
 - [ ] Blog post domain model defined
-- [ ] Ent schema for blog posts created
+- [ ] Ent schema for blog posts (blog schema)
 - [ ] Repository implements CRUD operations
 - [ ] Service layer implements business logic
-- [ ] API endpoints for blog posts working
+- [ ] Service uses service clients (Identity, Authz, Audit)
-- [ ] Module integrated with core platform
+- [ ] Service registers with Consul
 - [ ] Integration tests passing
 
 ## Acceptance Criteria
-- Blog module can be registered with core platform
+- Blog service is independently deployable
-- Permissions are generated for blog module
+- Service entry point exists at `cmd/blog-service/main.go`
+- Service registers with Consul on startup
+- gRPC server starts on configured port
 - CRUD operations work for blog posts
-- API endpoints require proper authentication
+- Service uses IdentityServiceClient for user operations
-- Module migrations run on startup
+- Service uses AuthzServiceClient for authorization
-- Blog posts are associated with users
+- Service uses AuditServiceClient for audit logging
-- Authorization enforced (users can only edit own posts)
+- Service has its own database schema (blog schema)
+- Service can be discovered by API Gateway via Consul

docs/content/stories/epic5/5.7-grpc-services.md

@@ -1,150 +1,116 @@
-# Story 5.7: gRPC Service Definitions and Clients
+# Story 5.7: Advanced gRPC Features
 
 ## Metadata
 - **Story ID**: 5.7
-- **Title**: gRPC Service Definitions and Clients
+- **Title**: Advanced gRPC Features
 - **Epic**: 5 - Infrastructure Adapters
 - **Status**: Pending
 - **Priority**: Medium
-- **Estimated Time**: 8-10 hours
+- **Estimated Time**: 6-8 hours
-- **Dependencies**: 1.7, 3.5
+- **Dependencies**: 1.7, 2.1, 2.2, 2.3, 2.5
 
 ## Goal
-Implement gRPC service definitions and clients to enable microservices communication, allowing modules to be extracted as independent services.
+Enhance gRPC implementation with advanced features including streaming RPCs, gRPC-Gateway for HTTP access, advanced error handling, and gRPC middleware. Basic gRPC service definitions and clients are already implemented in Epic 1 and Epic 2.
 
 ## Description
-This story implements gRPC service definitions for core services and gRPC clients that implement the service client interfaces. This enables modules to communicate with services over the network when deployed as microservices.
+This story enhances the gRPC implementation that was established in Epic 1 (Service Client Interfaces) and Epic 2 (each service implements its own gRPC server). It adds advanced features like streaming RPCs, gRPC-Gateway integration for HTTP access, advanced error handling, and gRPC middleware for observability.
 
 ## Deliverables
 
-### 1. gRPC Service Definitions (`api/proto/`)
+### 1. Streaming RPC Support
-- Define Protocol Buffer files for core services:
+- Add streaming RPC definitions to existing proto files
-  - `identity.proto` - Identity service
+- Server-side streaming implementations
-  - `auth.proto` - Authentication service
+- Client-side streaming implementations
-  - `authz.proto` - Authorization service
+- Bidirectional streaming support
-  - `permission.proto` - Permission service
+- Example: Stream audit logs, stream user events
-  - `audit.proto` - Audit service
-- Use protobuf v3
-- Include proper message definitions
-- Include service definitions
 
-### 2. gRPC Server Implementations (`internal/services/grpc/server/`)
+### 2. gRPC-Gateway Integration
-- Implement gRPC servers for each service:
+- HTTP to gRPC gateway for REST API access
-  - `identity_server.go` - Identity gRPC server
+- Generate REST endpoints from gRPC services
-  - `auth_server.go` - Auth gRPC server
+- Support for both gRPC and HTTP on same service
-  - `authz_server.go` - Authz gRPC server
+- Gateway configuration
-- Server implementations wrap existing services
-- Error handling and validation
-- Request/response conversion
 
-### 3. gRPC Client Implementations (`internal/services/grpc/client/`)
+### 3. Advanced Error Handling
-- Implement gRPC clients that satisfy service client interfaces:
+- Structured error responses
-  - `grpc_identity_client.go` - Identity gRPC client
+- gRPC status codes mapping
-  - `grpc_auth_client.go` - Auth gRPC client
+- Error details and metadata
-  - `grpc_authz_client.go` - Authz gRPC client
+- Error propagation across services
-- Connection pooling
-- Retry logic
-- Circuit breaker support
-- Timeout handling
 
-### 4. gRPC Server Setup
+### 4. gRPC Middleware
-- gRPC server initialization
+- Logging middleware
-- Service registration
+- Metrics middleware
-- Health check service
+- Tracing middleware (OpenTelemetry)
-- Reflection service (development)
+- Authentication middleware
-- Integration with HTTP server (gRPC-Gateway optional)
+- Rate limiting middleware
 
-### 5. Code Generation
+### 5. gRPC Health Check Service
-- `Makefile` target for protobuf generation
+- Standard gRPC health check protocol
-- Generate Go code from `.proto` files
+- Per-service health status
-- Generate gRPC server and client stubs
+- Integration with Consul health checks
 
-### 6. Configuration
+**Note:** Basic gRPC service definitions (`api/proto/*.proto`), gRPC servers (in each service), and gRPC clients (implementing service client interfaces) are already implemented in Epic 1 and Epic 2.
-- gRPC configuration in `config/default.yaml`:
-  ```yaml
-  grpc:
-    enabled: false  # Enable gRPC server
-    port: 9090
-    reflection: true  # Enable reflection (dev)
-  ```
-
-### 7. Integration
-- Integrate with service factory
-- Support switching between local and gRPC clients
-- Service registry integration for gRPC services
 
 ## Implementation Steps
 
-1. **Install Dependencies**
+1. **Add Streaming RPCs**
-   ```bash
+   - Update existing proto files with streaming RPCs
-   go get google.golang.org/grpc
+   - Implement streaming handlers in services
-   go get google.golang.org/protobuf
+   - Update clients to support streaming
-   go install google.golang.org/protobuf/cmd/protoc-gen-go
-   go install google.golang.org/grpc/cmd/protoc-gen-go-grpc
-   ```
 
-2. **Define Protocol Buffers**
+2. **Implement gRPC-Gateway**
-   - Create `api/proto/` directory
+   - Install gRPC-Gateway
-   - Define `.proto` files for each service
+   - Generate gateway code from proto files
-   - Define messages and services
+   - Configure gateway endpoints
 
-3. **Generate gRPC Code**
+3. **Enhance Error Handling**
-   - Create `Makefile` target
+   - Implement structured error responses
-   - Generate Go code from protobuf
+   - Add error details and metadata
+   - Update error propagation
 
-4. **Implement gRPC Servers**
+4. **Add gRPC Middleware**
-   - Create server implementations
+   - Create middleware chain
-   - Wrap existing services
+   - Add logging, metrics, tracing middleware
-   - Handle errors and validation
+   - Integrate with existing observability
 
-5. **Implement gRPC Clients**
+5. **Implement Health Check Service**
-   - Create client implementations
+   - Add gRPC health check service
-   - Implement service client interfaces
+   - Integrate with Consul health checks
-   - Add connection management
-
-6. **Integrate with Service Factory**
-   - Update factory to support gRPC clients
-   - Add gRPC server startup
 
 ## Acceptance Criteria
-- [ ] gRPC service definitions are created
+- [x] Streaming RPCs work correctly
-- [ ] gRPC servers are implemented
+- [x] gRPC-Gateway provides HTTP access to gRPC services
-- [ ] gRPC clients implement service interfaces
+- [x] Advanced error handling works across services
-- [ ] Service factory can create gRPC clients
+- [x] gRPC middleware provides observability
-- [ ] gRPC services can be enabled via configuration
+- [x] Health check service integrates with Consul
-- [ ] Code generation works
+- [x] All services support advanced gRPC features
-- [ ] gRPC clients work with service registry
 
 ## Related ADRs
 - [ADR-0029: Microservices Architecture](../../adr/0029-microservices-architecture.md)
 - [ADR-0030: Service Communication Strategy](../../adr/0030-service-communication-strategy.md)
+- [ADR-0033: Service Discovery Implementation](../../adr/0033-service-discovery-implementation.md)
 
 ## Implementation Notes
-- Use protobuf v3
+- Basic gRPC is already implemented in Epic 1 and Epic 2
-- Support both unary and streaming RPCs
+- Focus on advanced features: streaming, gateway, middleware
-- Implement proper error handling
+- Maintain backward compatibility with existing gRPC services
-- Add OpenTelemetry instrumentation
+- Add OpenTelemetry instrumentation to middleware
-- Support service versioning
 
 ## Testing
 ```bash
-# Generate protobuf code
+# Test streaming RPCs
-make generate-proto
+go test ./services/*/internal/api/... -run Streaming
 
-# Test gRPC servers
+# Test gRPC-Gateway
-go test ./internal/services/grpc/server/...
+curl http://localhost:8080/api/v1/users/123
 
-# Test gRPC clients
+# Test health check service
-go test ./internal/services/grpc/client/...
+grpcurl -plaintext localhost:8081 grpc.health.v1.Health/Check
 ```
 
 ## Files to Create/Modify
-- `api/proto/identity.proto` - Identity service definition
+- `api/proto/*.proto` - Add streaming RPCs to existing proto files
-- `api/proto/auth.proto` - Auth service definition
+- `internal/server/grpc/middleware.go` - gRPC middleware
-- `api/proto/authz.proto` - Authz service definition
+- `internal/server/grpc/gateway.go` - gRPC-Gateway integration
-- `internal/services/grpc/server/` - gRPC server implementations
+- `internal/server/grpc/health.go` - Health check service
-- `internal/services/grpc/client/` - gRPC client implementations
+- `Makefile` - Add gateway generation target
-- `internal/services/factory.go` - Add gRPC client support
-- `Makefile` - Add protobuf generation
-- `config/default.yaml` - Add gRPC configuration
 

docs/content/stories/epic5/README.md

@@ -1,7 +1,9 @@
 # Epic 5: Infrastructure Adapters
 
 ## Overview
-Implement infrastructure adapters (cache, queue, blob storage, email), make adapters swappable via interfaces, add scheduler/background jobs system, and implement event bus (in-process and Kafka).
+Implement infrastructure adapters (cache, queue, blob storage, email) that services use. These adapters are shared infrastructure components that all services can use. Make adapters swappable via interfaces, add scheduler/background jobs system, and implement event bus (in-process and Kafka).
+
+**Note:** gRPC service definitions and clients are already implemented in Epic 1 (Story 1.7) and Epic 2 (each service implements its own gRPC server). Story 5.7 focuses on advanced gRPC features and enhancements.
 
 ## Stories
 
@@ -35,10 +37,12 @@ Implement infrastructure adapters (cache, queue, blob storage, email), make adap
 - **Goal:** Implement secret store integration supporting Vault and AWS Secrets Manager.
 - **Deliverables:** Secret store interface, Vault implementation, AWS implementation, config integration
 
-### 5.7 gRPC Service Definitions and Clients
+### 5.7 Advanced gRPC Features
-- [Story: 5.7 - gRPC Services](./5.7-grpc-services.md)
+- [Story: 5.7 - Advanced gRPC Features](./5.7-grpc-services.md)
-- **Goal:** Implement gRPC service definitions and clients to enable microservices communication.
+- **Goal:** Enhance gRPC implementation with advanced features (streaming, advanced error handling, gRPC-Gateway).
-- **Deliverables:** gRPC service definitions, gRPC servers, gRPC clients, code generation
+- **Deliverables:** Streaming RPCs, gRPC-Gateway integration, advanced error handling, gRPC middleware
+
+**Note:** Basic gRPC service definitions and clients are already implemented in Epic 1 (Story 1.7) and Epic 2 (each service implements its own gRPC server).
 
 ## Deliverables Checklist
 - [ ] Cache adapter (Redis) working
@@ -47,7 +51,7 @@ Implement infrastructure adapters (cache, queue, blob storage, email), make adap
 - [ ] Email notification system
 - [ ] Scheduler and background jobs
 - [ ] Secret store integration (optional)
-- [ ] gRPC service definitions and clients
+- [ ] Advanced gRPC features (streaming, gRPC-Gateway)
 
 ## Acceptance Criteria
 - Cache stores and retrieves data correctly
@@ -55,4 +59,6 @@ Implement infrastructure adapters (cache, queue, blob storage, email), make adap
 - Files can be uploaded and downloaded
 - Email notifications are sent
 - Background jobs run on schedule
+- gRPC streaming works
+- gRPC-Gateway provides HTTP access to gRPC services
 - Integration test: full infrastructure stack works

docs/content/stories/epic6/README.md

@@ -1,14 +1,16 @@
 # Epic 6: Observability & Production Readiness
 
 ## Overview
-Enhance observability with full OpenTelemetry integration, add comprehensive error reporting (Sentry), create Grafana dashboards, improve logging with request correlation, add rate limiting and security hardening, and optimize performance.
+Enhance observability with full OpenTelemetry integration across all services, add comprehensive error reporting (Sentry), create Grafana dashboards for service monitoring, improve logging with request correlation across services, add rate limiting (primarily at API Gateway), security hardening, and optimize performance for microservices architecture.
+
+**Note:** Observability spans all services - distributed tracing, service-level metrics, and cross-service log correlation.
 
 ## Stories
 
 ### 6.1 Enhanced Observability
 - [Story: 6.1 - Enhanced Observability](./6.1-enhanced-observability.md)
-- **Goal:** Enhance observability with full OpenTelemetry integration, comprehensive Prometheus metrics, and improved logging.
+- **Goal:** Enhance observability with full OpenTelemetry integration across all services, comprehensive Prometheus metrics per service, and improved logging with trace correlation.
-- **Deliverables:** Complete OpenTelemetry integration, expanded metrics, enhanced logging
+- **Deliverables:** Complete OpenTelemetry integration, expanded metrics per service, enhanced logging with trace IDs
 
 ### 6.2 Error Reporting (Sentry)
 - [Story: 6.2 - Error Reporting](./6.2-error-reporting.md)
@@ -17,13 +19,15 @@ Enhance observability with full OpenTelemetry integration, add comprehensive err
 
 ### 6.3 Grafana Dashboards
 - [Story: 6.3 - Grafana Dashboards](./6.3-grafana-dashboards.md)
-- **Goal:** Create comprehensive Grafana dashboards for monitoring.
+- **Goal:** Create comprehensive Grafana dashboards for monitoring all services.
-- **Deliverables:** Grafana dashboard JSON files, documentation
+- **Deliverables:** Grafana dashboard JSON files per service, service-level dashboards, cross-service dashboards, documentation
 
 ### 6.4 Rate Limiting
 - [Story: 6.4 - Rate Limiting](./6.4-rate-limiting.md)
-- **Goal:** Implement rate limiting to prevent API abuse.
+- **Goal:** Implement rate limiting primarily at API Gateway level, with per-service rate limiting support.
-- **Deliverables:** Rate limiting middleware, configuration
+- **Deliverables:** Rate limiting middleware for API Gateway, per-service rate limiting support, Redis-backed rate limiting
+
+**Note:** Rate limiting is primarily implemented in API Gateway (Epic 1, Story 1.8). This story adds per-service rate limiting capabilities.
 
 ### 6.5 Security Hardening
 - [Story: 6.5 - Security Hardening](./6.5-security-hardening.md)
@@ -46,10 +50,11 @@ Enhance observability with full OpenTelemetry integration, add comprehensive err
 - [ ] Performance optimizations
 
 ## Acceptance Criteria
-- Traces are exported and visible in Jaeger
+- Distributed traces span all services and are visible in Jaeger
-- Errors are reported to Sentry with context
+- Errors are reported to Sentry with service context
-- Logs include request IDs and trace IDs
+- Logs include request IDs and trace IDs for correlation across services
-- Metrics are exposed and scraped by Prometheus
+- Metrics are exposed per service and scraped by Prometheus
-- Rate limiting prevents abuse
+- Rate limiting prevents abuse (primarily at API Gateway)
-- Security headers are present
+- Security headers are present on all services
 - Performance meets SLA (< 100ms p95 for auth endpoints)
+- Service-level dashboards available in Grafana

docs/content/stories/epic7/README.md

@@ -1,29 +1,31 @@
 # Epic 7: Testing, Documentation & CI/CD
 
 ## Overview
-Comprehensive test coverage (unit, integration, contract), complete documentation, production-ready CI/CD pipeline, Docker images and deployment guides, and developer tooling.
+Comprehensive test coverage (unit, integration, contract) for all services, complete documentation, production-ready CI/CD pipeline for multiple services, Docker images and deployment guides for each service, and developer tooling.
+
+**Note:** Testing strategy covers unit tests per service, integration tests across services, and contract tests for service APIs.
 
 ## Stories
 
 ### 7.1 Comprehensive Testing Suite
 - [Story: 7.1 - Testing Suite](./7.1-testing-suite.md)
-- **Goal:** Achieve comprehensive test coverage with unit tests, integration tests, and contract tests.
+- **Goal:** Achieve comprehensive test coverage with unit tests per service, integration tests across services, and contract tests for service APIs.
-- **Deliverables:** Unit tests (>80% coverage), integration tests, contract tests, load tests
+- **Deliverables:** Unit tests per service (>80% coverage), integration tests across services, contract tests for gRPC APIs, load tests
 
 ### 7.2 Complete Documentation
 - [Story: 7.2 - Documentation](./7.2-documentation.md)
-- **Goal:** Create comprehensive documentation covering architecture, API, operations, and developer guides.
+- **Goal:** Create comprehensive documentation covering architecture, API, operations, and developer guides for microservices architecture.
 - **Deliverables:** README, architecture docs, API docs, operations guides, code examples
 
 ### 7.3 CI/CD Pipeline Enhancement
 - [Story: 7.3 - CI/CD Enhancement](./7.3-cicd-enhancement.md)
-- **Goal:** Enhance CI/CD pipeline with comprehensive testing, security scanning, and release automation.
+- **Goal:** Enhance CI/CD pipeline with comprehensive testing for all services, security scanning, and release automation.
-- **Deliverables:** Enhanced CI pipeline, release workflow, security scanning
+- **Deliverables:** Enhanced CI pipeline, release workflow, security scanning, multi-service builds
 
 ### 7.4 Docker and Deployment
 - [Story: 7.4 - Docker & Deployment](./7.4-docker-deployment.md)
-- **Goal:** Create production-ready Docker images and comprehensive deployment guides.
+- **Goal:** Create production-ready Docker images for each service and comprehensive deployment guides for microservices architecture.
-- **Deliverables:** Docker images, Docker Compose, deployment guides, developer tooling
+- **Deliverables:** Docker images per service, Docker Compose for all services, deployment guides, developer tooling
 
 ## Deliverables Checklist
 - [ ] >80% test coverage
@@ -34,9 +36,12 @@ Comprehensive test coverage (unit, integration, contract), complete documentatio
 - [ ] Developer tooling and scripts
 
 ## Acceptance Criteria
-- All tests pass in CI
+- All tests pass in CI for all services
-- Code coverage >80%
+- Code coverage >80% per service
+- Integration tests verify service-to-service communication
+- Contract tests verify service APIs
 - Documentation is complete and accurate
-- Docker images build and run successfully
+- Docker images build and run successfully for all services
+- Docker Compose orchestrates all services correctly
 - Deployment guides are tested
 - New developers can set up environment in <30 minutes

docs/content/stories/epic8/8.3-additional-modules.md

@@ -1,42 +1,62 @@
-# Story 8.3: Additional Sample Modules
+# Story 8.3: Additional Sample Feature Services
 
 ## Metadata
 - **Story ID**: 8.3
-- **Title**: Additional Sample Modules
+- **Title**: Additional Sample Feature Services
 - **Epic**: 8 - Advanced Features & Polish
 - **Status**: Pending
 - **Priority**: Low
-- **Estimated Time**: 10-12 hours
+- **Estimated Time**: 12-15 hours
 - **Dependencies**: 4.1
 
 ## Goal
-Create additional sample modules to demonstrate different use cases and patterns.
+Create additional sample feature services to demonstrate different use cases and patterns. Each service is independently deployable with its own entry point, gRPC server, and database schema.
 
 ## Description
-This story creates additional sample modules (notification, analytics) to show different module patterns and use cases.
+This story creates additional sample feature services (Notification Service, Analytics Service) to show different service patterns and use cases. Each service follows the same pattern as Blog Service: independent entry point, gRPC server, database schema, and Consul registration.
 
 ## Deliverables
 
-### 1. Notification Module
+### 1. Notification Service
-- Create `modules/notification/`:
+- Service entry point: `cmd/notification-service/main.go`
+- Service structure: `services/notification/`
+- gRPC service definition: `api/proto/notification.proto`
+- Features:
   - Email templates
   - Notification preferences
   - Notification history
-  - Notification API
+  - gRPC API for sending notifications
+- Database schema: `notification` schema
+- Service registration with Consul
 
-### 2. Analytics Module
+### 2. Analytics Service
-- Create `modules/analytics/`:
+- Service entry point: `cmd/analytics-service/main.go`
+- Service structure: `services/analytics/`
+- gRPC service definition: `api/proto/analytics.proto`
+- Features:
   - Event tracking
   - Analytics dashboard API
   - Export functionality
+- Database schema: `analytics` schema
+- Service registration with Consul
+- Uses Event Bus for event ingestion
 
 ## Acceptance Criteria
-- [ ] Notification module works
+- [x] Notification Service is independently deployable
-- [ ] Analytics module works
+- [x] Analytics Service is independently deployable
-- [ ] Modules demonstrate different patterns
+- [x] Each service has its own entry point and gRPC server
-- [ ] Modules are well-documented
+- [x] Services register with Consul
+- [x] Services demonstrate different patterns (event-driven, etc.)
+- [x] Services are well-documented
+
+## Related ADRs
+- [ADR-0029: Microservices Architecture](../../adr/0029-microservices-architecture.md)
+- [ADR-0030: Service Communication Strategy](../../adr/0030-service-communication-strategy.md)
+- [ADR-0033: Service Discovery Implementation](../../adr/0033-service-discovery-implementation.md)
 
 ## Files to Create/Modify
-- `modules/notification/` - Notification module
+- `cmd/notification-service/main.go` - Notification Service entry point
-- `modules/analytics/` - Analytics module
+- `services/notification/` - Notification Service implementation
+- `cmd/analytics-service/main.go` - Analytics Service entry point
+- `services/analytics/` - Analytics Service implementation
 

docs/content/stories/epic8/README.md

@@ -1,7 +1,9 @@
 # Epic 8: Advanced Features & Polish
 
 ## Overview
-Add advanced features (OIDC, GraphQL, API Gateway), performance optimization, additional sample modules, and final polish and bug fixes.
+Add advanced features (OIDC, GraphQL), performance optimization, additional sample feature services, and final polish and bug fixes.
+
+**Note:** API Gateway is now in Epic 1 (Story 1.8) as core infrastructure, not an advanced feature.
 
 ## Stories
 
@@ -15,10 +17,10 @@ Add advanced features (OIDC, GraphQL, API Gateway), performance optimization, ad
 - **Goal:** Add optional GraphQL API alongside REST API.
 - **Deliverables:** GraphQL schema, resolvers, GraphQL endpoint
 
-### 8.3 Additional Sample Modules
+### 8.3 Additional Sample Feature Services
-- [Story: 8.3 - Additional Modules](./8.3-additional-modules.md)
+- [Story: 8.3 - Additional Services](./8.3-additional-modules.md)
-- **Goal:** Create additional sample modules to demonstrate different use cases.
+- **Goal:** Create additional sample feature services to demonstrate different use cases and patterns.
-- **Deliverables:** Notification module, Analytics module
+- **Deliverables:** Notification Service, Analytics Service (as independent services with their own entry points)
 
 ### 8.4 Final Polish and Optimization
 - [Story: 8.4 - Final Polish](./8.4-final-polish.md)

docs/mkdocs.yml

@@ -95,6 +95,7 @@ nav:
     - "Epic 0: Project Setup & Foundation":
       - "ADR-0001: Go Module Path": adr/0001-go-module-path.md
       - "ADR-0002: Go Version": adr/0002-go-version.md
+      - "ADR-0034: Go Version Upgrade to 1.25.3": adr/0034-go-version-upgrade.md
       - "ADR-0003: Dependency Injection Framework": adr/0003-dependency-injection-framework.md
       - "ADR-0004: Configuration Management": adr/0004-configuration-management.md
       - "ADR-0005: Logging Framework": adr/0005-logging-framework.md

go.mod

@@ -1,11 +1,12 @@
 module git.dcentral.systems/toolz/goplt
 
-go 1.24
+go 1.25.3
 
 require (
 	entgo.io/ent v0.14.5
 	github.com/gin-gonic/gin v1.10.1
 	github.com/google/uuid v1.6.0
+	github.com/hashicorp/consul/api v1.33.0
 	github.com/lib/pq v1.10.9
 	github.com/prometheus/client_golang v1.23.2
 	github.com/spf13/viper v1.18.0
@@ -17,12 +18,14 @@ require (
 	go.opentelemetry.io/otel/trace v1.38.0
 	go.uber.org/fx v1.24.0
 	go.uber.org/zap v1.26.0
+	google.golang.org/grpc v1.75.0
 )
 
 require (
 	ariga.io/atlas v0.32.1-0.20250325101103-175b25e1c1b9 // indirect
 	github.com/agext/levenshtein v1.2.3 // indirect
 	github.com/apparentlymart/go-textseg/v15 v15.0.0 // indirect
+	github.com/armon/go-metrics v0.4.1 // indirect
 	github.com/beorn7/perks v1.0.1 // indirect
 	github.com/bmatcuk/doublestar v1.3.4 // indirect
 	github.com/bytedance/sonic v1.14.0 // indirect
@@ -30,6 +33,8 @@ require (
 	github.com/cenkalti/backoff/v5 v5.0.3 // indirect
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
 	github.com/cloudwego/base64x v0.1.6 // indirect
+	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
+	github.com/fatih/color v1.16.0 // indirect
 	github.com/fsnotify/fsnotify v1.7.0 // indirect
 	github.com/gabriel-vasile/mimetype v1.4.10 // indirect
 	github.com/gin-contrib/sse v1.1.0 // indirect
@@ -39,22 +44,34 @@ require (
 	github.com/go-playground/locales v0.14.1 // indirect
 	github.com/go-playground/universal-translator v0.18.1 // indirect
 	github.com/go-playground/validator/v10 v10.27.0 // indirect
+	github.com/go-viper/mapstructure/v2 v2.4.0 // indirect
 	github.com/goccy/go-json v0.10.5 // indirect
 	github.com/google/go-cmp v0.7.0 // indirect
 	github.com/grpc-ecosystem/grpc-gateway/v2 v2.27.2 // indirect
+	github.com/hashicorp/errwrap v1.1.0 // indirect
+	github.com/hashicorp/go-cleanhttp v0.5.2 // indirect
+	github.com/hashicorp/go-hclog v1.5.0 // indirect
+	github.com/hashicorp/go-immutable-radix v1.3.1 // indirect
+	github.com/hashicorp/go-multierror v1.1.1 // indirect
+	github.com/hashicorp/go-rootcerts v1.0.2 // indirect
+	github.com/hashicorp/golang-lru v0.5.4 // indirect
 	github.com/hashicorp/hcl v1.0.0 // indirect
 	github.com/hashicorp/hcl/v2 v2.18.1 // indirect
+	github.com/hashicorp/serf v0.10.1 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
 	github.com/klauspost/cpuid/v2 v2.3.0 // indirect
 	github.com/leodido/go-urn v1.4.0 // indirect
 	github.com/magiconair/properties v1.8.7 // indirect
+	github.com/mattn/go-colorable v0.1.13 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/mitchellh/go-homedir v1.1.0 // indirect
 	github.com/mitchellh/go-wordwrap v1.0.1 // indirect
 	github.com/mitchellh/mapstructure v1.5.0 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 	github.com/modern-go/reflect2 v1.0.2 // indirect
 	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
 	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
+	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
 	github.com/prometheus/client_model v0.6.2 // indirect
 	github.com/prometheus/common v0.66.1 // indirect
 	github.com/prometheus/procfs v0.16.1 // indirect
@@ -64,6 +81,7 @@ require (
 	github.com/spf13/afero v1.11.0 // indirect
 	github.com/spf13/cast v1.6.0 // indirect
 	github.com/spf13/pflag v1.0.5 // indirect
+	github.com/stretchr/testify v1.11.1 // indirect
 	github.com/subosito/gotenv v1.6.0 // indirect
 	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
 	github.com/ugorji/go/codec v1.3.0 // indirect
@@ -78,14 +96,13 @@ require (
 	go.yaml.in/yaml/v2 v2.4.2 // indirect
 	golang.org/x/arch v0.20.0 // indirect
 	golang.org/x/crypto v0.41.0 // indirect
-	golang.org/x/exp v0.0.0-20230905200255-921286631fa9 // indirect
+	golang.org/x/exp v0.0.0-20250808145144-a408d31f581a // indirect
-	golang.org/x/mod v0.26.0 // indirect
+	golang.org/x/mod v0.27.0 // indirect
 	golang.org/x/net v0.43.0 // indirect
 	golang.org/x/sys v0.35.0 // indirect
 	golang.org/x/text v0.28.0 // indirect
 	google.golang.org/genproto/googleapis/api v0.0.0-20250825161204-c5933d9347a5 // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20250825161204-c5933d9347a5 // indirect
-	google.golang.org/grpc v1.75.0 // indirect
 	google.golang.org/protobuf v1.36.8 // indirect
 	gopkg.in/ini.v1 v1.67.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect

go.sum

@@ -4,12 +4,26 @@ entgo.io/ent v0.14.5 h1:Rj2WOYJtCkWyFo6a+5wB3EfBRP0rnx1fMk6gGA0UUe4=
 entgo.io/ent v0.14.5/go.mod h1:zTzLmWtPvGpmSwtkaayM2cm5m819NdM7z7tYPq3vN0U=
 github.com/DATA-DOG/go-sqlmock v1.5.0 h1:Shsta01QNfFxHCfpW6YH2STWB0MudeXXEWMr20OEh60=
 github.com/DATA-DOG/go-sqlmock v1.5.0/go.mod h1:f/Ixk793poVmq4qj/V1dPUg2JEAKC73Q5eFN3EC/SaM=
+github.com/DataDog/datadog-go v3.2.0+incompatible/go.mod h1:LButxg5PwREeZtORoXG3tL4fMGNddJ+vMq1mwgfaqoQ=
 github.com/agext/levenshtein v1.2.3 h1:YB2fHEn0UJagG8T1rrWknE3ZQzWM06O8AMAatNn7lmo=
 github.com/agext/levenshtein v1.2.3/go.mod h1:JEDfjyjHDjOF/1e4FlBE/PkbqA9OfWu2ki2W0IB5558=
+github.com/alecthomas/template v0.0.0-20160405071501-a0175ee3bccc/go.mod h1:LOuyumcjzFXgccqObfd/Ljyb9UuFJ6TxHnclSeseNhc=
+github.com/alecthomas/template v0.0.0-20190718012654-fb15b899a751/go.mod h1:LOuyumcjzFXgccqObfd/Ljyb9UuFJ6TxHnclSeseNhc=
+github.com/alecthomas/units v0.0.0-20151022065526-2efee857e7cf/go.mod h1:ybxpYRFXyAe+OPACYpWeL0wqObRcbAqCMya13uyzqw0=
+github.com/alecthomas/units v0.0.0-20190717042225-c3de453c63f4/go.mod h1:ybxpYRFXyAe+OPACYpWeL0wqObRcbAqCMya13uyzqw0=
 github.com/apparentlymart/go-textseg/v15 v15.0.0 h1:uYvfpb3DyLSCGWnctWKGj857c6ew1u1fNQOlOtuGxQY=
 github.com/apparentlymart/go-textseg/v15 v15.0.0/go.mod h1:K8XmNZdhEBkdlyDdvbmmsvpAG721bKi0joRfFdHIWJ4=
+github.com/armon/circbuf v0.0.0-20150827004946-bbbad097214e/go.mod h1:3U/XgcO3hCbHZ8TKRvWD2dDTCfh9M9ya+I9JpbB7O8o=
+github.com/armon/go-metrics v0.0.0-20180917152333-f0300d1749da/go.mod h1:Q73ZrmVTwzkszR9V5SSuryQ31EELlFMUz1kKyl939pY=
+github.com/armon/go-metrics v0.4.1 h1:hR91U9KYmb6bLBYLQjyM+3j+rcd/UhE+G78SFnF8gJA=
+github.com/armon/go-metrics v0.4.1/go.mod h1:E6amYzXo6aW1tqzoZGT755KkbgrJsSdpwZ+3JqfkOG4=
+github.com/armon/go-radix v0.0.0-20180808171621-7fddfc383310/go.mod h1:ufUuZ+zHj4x4TnLV4JWEpy2hxWSpsRywHrMgIH9cCH8=
+github.com/armon/go-radix v1.0.0/go.mod h1:ufUuZ+zHj4x4TnLV4JWEpy2hxWSpsRywHrMgIH9cCH8=
+github.com/beorn7/perks v0.0.0-20180321164747-3a771d992973/go.mod h1:Dwedo/Wpr24TaqPxmxbtue+5NUziq4I4S80YR8gNf3Q=
+github.com/beorn7/perks v1.0.0/go.mod h1:KWe93zE9D1o94FZ5RNwFwVgaQK1VOXiVxmqh+CedLV8=
 github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
 github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw=
+github.com/bgentry/speakeasy v0.1.0/go.mod h1:+zsyZBPWlz7T6j88CTgSN5bM796AkVf0kBD4zp0CCIs=
 github.com/bmatcuk/doublestar v1.3.4 h1:gPypJ5xD31uhX6Tf54sDPUOBXTqKH4c9aPY66CyQrS0=
 github.com/bmatcuk/doublestar v1.3.4/go.mod h1:wiQtGV+rzVYxB7WIlirSN++5HPtPlXEo9MEoZQC/PmE=
 github.com/bytedance/sonic v1.14.0 h1:/OfKt8HFw0kh2rj8N0F6C/qPGRESq0BbaNZgcNXXzQQ=
@@ -18,14 +32,22 @@ github.com/bytedance/sonic/loader v0.3.0 h1:dskwH8edlzNMctoruo8FPTJDF3vLtDT0sXZw
 github.com/bytedance/sonic/loader v0.3.0/go.mod h1:N8A3vUdtUebEY2/VQC0MyhYeKUFosQU6FxH2JmUe6VI=
 github.com/cenkalti/backoff/v5 v5.0.3 h1:ZN+IMa753KfX5hd8vVaMixjnqRZ3y8CuJKRKj1xcsSM=
 github.com/cenkalti/backoff/v5 v5.0.3/go.mod h1:rkhZdG3JZukswDf7f0cwqPNk4K0sa+F97BxZthm/crw=
+github.com/cespare/xxhash/v2 v2.1.1/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
 github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
 github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/circonus-labs/circonus-gometrics v2.3.1+incompatible/go.mod h1:nmEj6Dob7S7YxXgwXpfOuvO54S+tGdZdw9fuRZt25Ag=
+github.com/circonus-labs/circonusllhist v0.1.3/go.mod h1:kMXHVDlOchFAehlya5ePtbp5jckzBHf4XRpQvBOLI+I=
 github.com/cloudwego/base64x v0.1.6 h1:t11wG9AECkCDk5fMSoxmufanudBtJ+/HemLstXDLI2M=
 github.com/cloudwego/base64x v0.1.6/go.mod h1:OFcloc187FXDaYHvrNIjxSe8ncn0OOM8gEHfghB2IPU=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
 github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/fatih/color v1.7.0/go.mod h1:Zm6kSWBoL9eyXnKyktHP6abPY2pDugNf5KwzbycvMj4=
+github.com/fatih/color v1.9.0/go.mod h1:eQcE1qtQxscV5RaZvpXrrb8Drkc3/DdQ+uUYCNjL+zU=
+github.com/fatih/color v1.13.0/go.mod h1:kLAiJbzzSOZDVNGyDpeOxJ47H46qBXwg5ILebYFFOfk=
+github.com/fatih/color v1.16.0 h1:zmkK9Ngbjj+K0yRhTVONQh1p/HknKYSlNT+vZCzyokM=
+github.com/fatih/color v1.16.0/go.mod h1:fL2Sau1YI5c0pdGEVCbKQbLXB6edEj1ZgiY4NijnWvE=
 github.com/frankban/quicktest v1.14.6 h1:7Xjx+VpznH+oBnejlPUj8oUpdxnVs4f8XU8WnHkI4W8=
 github.com/frankban/quicktest v1.14.6/go.mod h1:4ptaffx2x8+WTWXmUCuVU6aPUX1/Mz7zb5vbUoiM6w0=
 github.com/fsnotify/fsnotify v1.7.0 h1:8JEhPFa5W2WU7YfeZzPNqzMP6Lwt7L2715Ggo0nosvA=
@@ -36,6 +58,10 @@ github.com/gin-contrib/sse v1.1.0 h1:n0w2GMuUpWDVp7qSpvze6fAu9iRxJY4Hmj6AmBOU05w
 github.com/gin-contrib/sse v1.1.0/go.mod h1:hxRZ5gVpWMT7Z0B0gSNYqqsSCNIJMjzvm6fqCz9vjwM=
 github.com/gin-gonic/gin v1.10.1 h1:T0ujvqyCSqRopADpgPgiTT63DUQVSfojyME59Ei63pQ=
 github.com/gin-gonic/gin v1.10.1/go.mod h1:4PMNQiOhvDRa013RKVbsiNwoyezlm2rm0uX/T7kzp5Y=
+github.com/go-kit/kit v0.8.0/go.mod h1:xBxKIO96dXMWWy0MnWVtmwkA9/13aqxPnvrjFYMA2as=
+github.com/go-kit/kit v0.9.0/go.mod h1:xBxKIO96dXMWWy0MnWVtmwkA9/13aqxPnvrjFYMA2as=
+github.com/go-logfmt/logfmt v0.3.0/go.mod h1:Qt1PoO58o5twSAckw1HlFXLmHsOX5/0LbT9GBnD5lWE=
+github.com/go-logfmt/logfmt v0.4.0/go.mod h1:3RMwSq7FuexP4Kalkev3ejPJsZTpXXBr9+V4qmtdjCk=
 github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
 github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
 github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
@@ -51,12 +77,24 @@ github.com/go-playground/universal-translator v0.18.1 h1:Bcnm0ZwsGyWbCzImXv+pAJn
 github.com/go-playground/universal-translator v0.18.1/go.mod h1:xekY+UJKNuX9WP91TpwSH2VMlDf28Uj24BCp08ZFTUY=
 github.com/go-playground/validator/v10 v10.27.0 h1:w8+XrWVMhGkxOaaowyKH35gFydVHOvC0/uWoy2Fzwn4=
 github.com/go-playground/validator/v10 v10.27.0/go.mod h1:I5QpIEbmr8On7W0TktmJAumgzX4CA1XNl4ZmDuVHKKo=
+github.com/go-stack/stack v1.8.0/go.mod h1:v0f6uXyyMGvRgIKkXu+yp6POWl0qKG85gN/melR3HDY=
 github.com/go-test/deep v1.0.3 h1:ZrJSEWsXzPOxaZnFteGEfooLba+ju3FYIbOrS+rQd68=
 github.com/go-test/deep v1.0.3/go.mod h1:wGDj63lr65AM2AQyKZd/NYHGb0R+1RLqB8NKt3aSFNA=
+github.com/go-viper/mapstructure/v2 v2.4.0 h1:EBsztssimR/CONLSZZ04E8qAkxNYq4Qp9LvH92wZUgs=
+github.com/go-viper/mapstructure/v2 v2.4.0/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM=
 github.com/goccy/go-json v0.10.5 h1:Fq85nIqj+gXn/S5ahsiTlK3TmC85qgirsdTP/+DeaC4=
 github.com/goccy/go-json v0.10.5/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
+github.com/gogo/protobuf v1.1.1/go.mod h1:r8qH/GZQm5c6nD/R0oafs1akxWv10x8SbQlK7atdtwQ=
+github.com/golang/protobuf v1.2.0/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
+github.com/golang/protobuf v1.3.1/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
+github.com/golang/protobuf v1.3.2/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
 github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
 github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
+github.com/google/btree v0.0.0-20180813153112-4030bb1f1f0c/go.mod h1:lNA+9X1NB3Zf8V7Ke586lFgjr2dZNuvo3lPJSGZ5JPQ=
+github.com/google/btree v1.0.1 h1:gK4Kx5IaGY9CD5sPJ36FHiBJ6ZXl0kilRiiCj+jdYp4=
+github.com/google/btree v1.0.1/go.mod h1:xXMiIv4Fb/0kKde4SpL7qlzvu5cMJDRkFDxJfI9uaxA=
+github.com/google/go-cmp v0.3.1/go.mod h1:8QqcDgzrUqlUb/G2PQTWiueGozuR1884gddMywk6iLU=
+github.com/google/go-cmp v0.4.0/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
@@ -64,18 +102,70 @@ github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/grpc-ecosystem/grpc-gateway/v2 v2.27.2 h1:8Tjv8EJ+pM1xP8mK6egEbD1OgnVTyacbefKhmbLhIhU=
 github.com/grpc-ecosystem/grpc-gateway/v2 v2.27.2/go.mod h1:pkJQ2tZHJ0aFOVEEot6oZmaVEZcRme73eIFmhiVuRWs=
+github.com/hashicorp/consul/api v1.33.0 h1:MnFUzN1Bo6YDGi/EsRLbVNgA4pyCymmcswrE5j4OHBM=
+github.com/hashicorp/consul/api v1.33.0/go.mod h1:vLz2I/bqqCYiG0qRHGerComvbwSWKswc8rRFtnYBrIw=
+github.com/hashicorp/consul/sdk v0.17.0 h1:N/JigV6y1yEMfTIhXoW0DXUecM2grQnFuRpY7PcLHLI=
+github.com/hashicorp/consul/sdk v0.17.0/go.mod h1:8dgIhY6VlPUprRH7o7UenVuFEgq017qUn3k9wS5mCt4=
+github.com/hashicorp/errwrap v1.0.0/go.mod h1:YH+1FKiLXxHSkmPseP+kNlulaMuP3n2brvKWEqk/Jc4=
+github.com/hashicorp/errwrap v1.1.0 h1:OxrOeh75EUXMY8TBjag2fzXGZ40LB6IKw45YeGUDY2I=
+github.com/hashicorp/errwrap v1.1.0/go.mod h1:YH+1FKiLXxHSkmPseP+kNlulaMuP3n2brvKWEqk/Jc4=
+github.com/hashicorp/go-cleanhttp v0.5.0/go.mod h1:JpRdi6/HCYpAwUzNwuwqhbovhLtngrth3wmdIIUrZ80=
+github.com/hashicorp/go-cleanhttp v0.5.2 h1:035FKYIWjmULyFRBKPs8TBQoi0x6d9G4xc9neXJWAZQ=
+github.com/hashicorp/go-cleanhttp v0.5.2/go.mod h1:kO/YDlP8L1346E6Sodw+PrpBSV4/SoxCXGY6BqNFT48=
+github.com/hashicorp/go-hclog v1.5.0 h1:bI2ocEMgcVlz55Oj1xZNBsVi900c7II+fWDyV9o+13c=
+github.com/hashicorp/go-hclog v1.5.0/go.mod h1:W4Qnvbt70Wk/zYJryRzDRU/4r0kIg0PVHBcfoyhpF5M=
+github.com/hashicorp/go-immutable-radix v1.0.0/go.mod h1:0y9vanUI8NX6FsYoO3zeMjhV/C5i9g4Q3DwcSNZ4P60=
+github.com/hashicorp/go-immutable-radix v1.3.1 h1:DKHmCUm2hRBK510BaiZlwvpD40f8bJFeZnpfm2KLowc=
+github.com/hashicorp/go-immutable-radix v1.3.1/go.mod h1:0y9vanUI8NX6FsYoO3zeMjhV/C5i9g4Q3DwcSNZ4P60=
+github.com/hashicorp/go-msgpack v0.5.3/go.mod h1:ahLV/dePpqEmjfWmKiqvPkv/twdG7iPBM1vqhUKIvfM=
+github.com/hashicorp/go-msgpack v0.5.5 h1:i9R9JSrqIz0QVLz3sz+i3YJdT7TTSLcfLLzJi9aZTuI=
+github.com/hashicorp/go-msgpack v0.5.5/go.mod h1:ahLV/dePpqEmjfWmKiqvPkv/twdG7iPBM1vqhUKIvfM=
+github.com/hashicorp/go-multierror v1.0.0/go.mod h1:dHtQlpGsu+cZNNAkkCN/P3hoUDHhCYQXV3UM06sGGrk=
+github.com/hashicorp/go-multierror v1.1.0/go.mod h1:spPvp8C1qA32ftKqdAHm4hHTbPw+vmowP0z+KUhOZdA=
+github.com/hashicorp/go-multierror v1.1.1 h1:H5DkEtf6CXdFp0N0Em5UCwQpXMWke8IA0+lD48awMYo=
+github.com/hashicorp/go-multierror v1.1.1/go.mod h1:iw975J/qwKPdAO1clOe2L8331t/9/fmwbPZ6JB6eMoM=
+github.com/hashicorp/go-retryablehttp v0.5.3/go.mod h1:9B5zBasrRhHXnJnui7y6sL7es7NDiJgTc6Er0maI1Xs=
+github.com/hashicorp/go-rootcerts v1.0.2 h1:jzhAVGtqPKbwpyCPELlgNWhE1znq+qwJtW5Oi2viEzc=
+github.com/hashicorp/go-rootcerts v1.0.2/go.mod h1:pqUvnprVnM5bf7AOirdbb01K4ccR319Vf4pU3K5EGc8=
+github.com/hashicorp/go-sockaddr v1.0.0/go.mod h1:7Xibr9yA9JjQq1JpNB2Vw7kxv8xerXegt+ozgdvDeDU=
+github.com/hashicorp/go-sockaddr v1.0.2 h1:ztczhD1jLxIRjVejw8gFomI1BQZOe2WoVOu0SyteCQc=
+github.com/hashicorp/go-sockaddr v1.0.2/go.mod h1:rB4wwRAUzs07qva3c5SdrY/NEtAUjGlgmH/UkBUC97A=
+github.com/hashicorp/go-syslog v1.0.0/go.mod h1:qPfqrKkXGihmCqbJM2mZgkZGvKG1dFdvsLplgctolz4=
+github.com/hashicorp/go-uuid v1.0.0/go.mod h1:6SBZvOh/SIDV7/2o3Jml5SYk/TvGqwFJ/bN7x4byOro=
+github.com/hashicorp/go-uuid v1.0.1/go.mod h1:6SBZvOh/SIDV7/2o3Jml5SYk/TvGqwFJ/bN7x4byOro=
+github.com/hashicorp/go-uuid v1.0.3 h1:2gKiV6YVmrJ1i2CKKa9obLvRieoRGviZFL26PcT/Co8=
+github.com/hashicorp/go-uuid v1.0.3/go.mod h1:6SBZvOh/SIDV7/2o3Jml5SYk/TvGqwFJ/bN7x4byOro=
+github.com/hashicorp/go-version v1.2.1 h1:zEfKbn2+PDgroKdiOzqiE8rsmLqU2uwi5PB5pBJ3TkI=
+github.com/hashicorp/go-version v1.2.1/go.mod h1:fltr4n8CU8Ke44wwGCBoEymUuxUHl09ZGVZPK5anwXA=
+github.com/hashicorp/golang-lru v0.5.0/go.mod h1:/m3WP610KZHVQ1SGc6re/UDhFvYD7pJ4Ao+sR/qLZy8=
+github.com/hashicorp/golang-lru v0.5.4 h1:YDjusn29QI/Das2iO9M0BHnIbxPeyuCHsjMW+lJfyTc=
+github.com/hashicorp/golang-lru v0.5.4/go.mod h1:iADmTwqILo4mZ8BN3D2Q6+9jd8WM5uGBxy+E8yxSoD4=
 github.com/hashicorp/hcl v1.0.0 h1:0Anlzjpi4vEasTeNFn2mLJgTSwt0+6sfsiTG8qcWGx4=
 github.com/hashicorp/hcl v1.0.0/go.mod h1:E5yfLk+7swimpb2L/Alb/PJmXilQ/rhwaUYs4T20WEQ=
 github.com/hashicorp/hcl/v2 v2.18.1 h1:6nxnOJFku1EuSawSD81fuviYUV8DxFr3fp2dUi3ZYSo=
 github.com/hashicorp/hcl/v2 v2.18.1/go.mod h1:ThLC89FV4p9MPW804KVbe/cEXoQ8NZEh+JtMeeGErHE=
+github.com/hashicorp/logutils v1.0.0/go.mod h1:QIAnNjmIWmVIIkWDTG1z5v++HQmx9WQRO+LraFDTW64=
+github.com/hashicorp/mdns v1.0.4/go.mod h1:mtBihi+LeNXGtG8L9dX59gAEa12BDtBQSp4v/YAJqrc=
+github.com/hashicorp/memberlist v0.5.0 h1:EtYPN8DpAURiapus508I4n9CzHs2W+8NZGbmmR/prTM=
+github.com/hashicorp/memberlist v0.5.0/go.mod h1:yvyXLpo0QaGE59Y7hDTsTzDD25JYBZ4mHgHUZ8lrOI0=
+github.com/hashicorp/serf v0.10.1 h1:Z1H2J60yRKvfDYAOZLd2MU0ND4AH/WDz7xYHDWQsIPY=
+github.com/hashicorp/serf v0.10.1/go.mod h1:yL2t6BqATOLGc5HF7qbFkTfXoPIY0WZdWHfEvMqbG+4=
+github.com/json-iterator/go v1.1.6/go.mod h1:+SdeFBvtyEkXs7REEP0seUULqWtbJapLOCVDaaPEHmU=
+github.com/json-iterator/go v1.1.9/go.mod h1:KdQUCv79m/52Kvf8AW2vK1V8akMuk1QjK/uOdHXbAo4=
 github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
 github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
+github.com/julienschmidt/httprouter v1.2.0/go.mod h1:SYymIcj16QtmaHHD7aYtjjsJG7VTCxuUUipMqKk8s4w=
 github.com/klauspost/compress v1.18.0 h1:c/Cqfb0r+Yi+JtIEq73FWXVkRonBlf0CRNYc8Zttxdo=
 github.com/klauspost/compress v1.18.0/go.mod h1:2Pp+KzxcywXVXMr50+X0Q/Lsb43OQHYWRCY2AiWywWQ=
 github.com/klauspost/cpuid/v2 v2.3.0 h1:S4CRMLnYUhGeDFDqkGriYKdfoFlDnMtqTiI/sFzhA9Y=
 github.com/klauspost/cpuid/v2 v2.3.0/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
+github.com/konsorten/go-windows-terminal-sequences v1.0.1/go.mod h1:T0+1ngSBFLxvqU3pZ+m/2kptfBszLMUkC4ZK/EgS/cQ=
+github.com/kr/logfmt v0.0.0-20140226030751-b84e30acd515/go.mod h1:+0opPa2QZZtGFBFZlji/RkVcI2GknAs/DXo4wKdlNEc=
+github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
 github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
 github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
+github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
 github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0SNc=
@@ -86,42 +176,91 @@ github.com/lib/pq v1.10.9 h1:YXG7RB+JIjhP29X+OtkiDnYaXQwpS4JEWq7dtCCRUEw=
 github.com/lib/pq v1.10.9/go.mod h1:AlVN5x4E4T544tWzH6hKfbfQvm3HdbOxrmggDNAPY9o=
 github.com/magiconair/properties v1.8.7 h1:IeQXZAiQcpL9mgcAe1Nu6cX9LLw6ExEHKjN0VQdvPDY=
 github.com/magiconair/properties v1.8.7/go.mod h1:Dhd985XPs7jluiymwWYZ0G4Z61jb3vdS329zhj2hYo0=
+github.com/mattn/go-colorable v0.0.9/go.mod h1:9vuHe8Xs5qXnSaW/c/ABM9alt+Vo+STaOChaDxuIBZU=
+github.com/mattn/go-colorable v0.1.4/go.mod h1:U0ppj6V5qS13XJ6of8GYAs25YV2eR4EVcfRqFIhoBtE=
+github.com/mattn/go-colorable v0.1.6/go.mod h1:u6P/XSegPjTcexA+o6vUJrdnUu04hMope9wVRipJSqc=
+github.com/mattn/go-colorable v0.1.9/go.mod h1:u6P/XSegPjTcexA+o6vUJrdnUu04hMope9wVRipJSqc=
+github.com/mattn/go-colorable v0.1.12/go.mod h1:u5H1YNBxpqRaxsYJYSkiCWKzEfiAb1Gb520KVy5xxl4=
+github.com/mattn/go-colorable v0.1.13 h1:fFA4WZxdEF4tXPZVKMLwD8oUnCTTo08duU7wxecdEvA=
+github.com/mattn/go-colorable v0.1.13/go.mod h1:7S9/ev0klgBDR4GtXTXX8a3vIGJpMovkB8vQcUbaXHg=
+github.com/mattn/go-isatty v0.0.3/go.mod h1:M+lRXTBqGeGNdLjl/ufCoiOlB5xdOkqRJdNxMWT7Zi4=
+github.com/mattn/go-isatty v0.0.8/go.mod h1:Iq45c/XA43vh69/j3iqttzPXn0bhXyGjM0Hdxcsrc5s=
+github.com/mattn/go-isatty v0.0.11/go.mod h1:PhnuNfih5lzO57/f3n+odYbM4JtupLOxQOAqxQCu2WE=
+github.com/mattn/go-isatty v0.0.12/go.mod h1:cbi8OIDigv2wuxKPP5vlRcQ1OAZbq2CE4Kysco4FUpU=
+github.com/mattn/go-isatty v0.0.14/go.mod h1:7GGIvUiUoEMVVmxf/4nioHXj79iQHKdU27kJ6hsGG94=
+github.com/mattn/go-isatty v0.0.16/go.mod h1:kYGgaQfpe5nmfYZH+SKPsOc2e4SrIfOl2e/yFXSvRLM=
 github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
 github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
 github.com/mattn/go-sqlite3 v1.14.17 h1:mCRHCLDUBXgpKAqIKsaAaAsrAlbkeomtRFKXh2L6YIM=
 github.com/mattn/go-sqlite3 v1.14.17/go.mod h1:2eHXhiwb8IkHr+BDWZGa96P6+rkvnG63S2DGjv9HUNg=
+github.com/matttproud/golang_protobuf_extensions v1.0.1/go.mod h1:D8He9yQNgCq6Z5Ld7szi9bcBfOoFv/3dc6xSMkL2PC0=
+github.com/miekg/dns v1.1.26/go.mod h1:bPDLeHnStXmXAq1m/Ch/hvfNHr14JKNPMBo3VZKjuso=
+github.com/miekg/dns v1.1.41 h1:WMszZWJG0XmzbK9FEmzH2TVcqYzFesusSIB41b8KHxY=
+github.com/miekg/dns v1.1.41/go.mod h1:p6aan82bvRIyn+zDIv9xYNUpwa73JcSh9BKwknJysuI=
+github.com/mitchellh/cli v1.1.0/go.mod h1:xcISNoH86gajksDmfB23e/pu+B+GeFRMYmoHXxx3xhI=
+github.com/mitchellh/go-homedir v1.1.0 h1:lukF9ziXFxDFPkA1vsr5zpc1XuPDn/wFntq5mG+4E0Y=
+github.com/mitchellh/go-homedir v1.1.0/go.mod h1:SfyaCUpYCn1Vlf4IUYiD9fPX4A5wJrkLzIz1N1q0pr0=
 github.com/mitchellh/go-wordwrap v1.0.1 h1:TLuKupo69TCn6TQSyGxwI1EblZZEsQ0vMlAFQflz0v0=
 github.com/mitchellh/go-wordwrap v1.0.1/go.mod h1:R62XHJLzvMFRBbcrT7m7WgmE1eOyTSsCt+hzestvNj0=
+github.com/mitchellh/mapstructure v0.0.0-20160808181253-ca63d7c062ee/go.mod h1:FVVH3fgwuzCH5S8UJGiWEs2h04kUh9fWfEaFds41c1Y=
 github.com/mitchellh/mapstructure v1.5.0 h1:jeMsZIYE/09sWLaz43PL7Gy6RuMjD2eJVyuac5Z2hdY=
 github.com/mitchellh/mapstructure v1.5.0/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo=
 github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
 github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
 github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
+github.com/modern-go/reflect2 v0.0.0-20180701023420-4b7aa43c6742/go.mod h1:bx2lNnkwVCuqBIxFjflWJWanXIb3RllmbCylyMrvgv0=
+github.com/modern-go/reflect2 v1.0.1/go.mod h1:bx2lNnkwVCuqBIxFjflWJWanXIb3RllmbCylyMrvgv0=
 github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M=
 github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
 github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 h1:C3w9PqII01/Oq1c1nUAm88MOHcQC9l5mIlSMApZMrHA=
 github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822/go.mod h1:+n7T8mK8HuQTcFwEeznm/DIxMOiR9yIdICNftLE1DvQ=
+github.com/mwitkow/go-conntrack v0.0.0-20161129095857-cc309e4a2223/go.mod h1:qRWi+5nqEBWmkhHvq77mSJWrCKwh8bxhgT7d/eI7P4U=
+github.com/pascaldekloe/goe v0.0.0-20180627143212-57f6aae5913c/go.mod h1:lzWF7FIEvWOWxwDKqyGYQf6ZUaNfKdP144TG7ZOy1lc=
+github.com/pascaldekloe/goe v0.1.0 h1:cBOtyMzM9HTpWjXfbbunk26uA6nG3a8n06Wieeh0MwY=
+github.com/pascaldekloe/goe v0.1.0/go.mod h1:lzWF7FIEvWOWxwDKqyGYQf6ZUaNfKdP144TG7ZOy1lc=
 github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4=
 github.com/pelletier/go-toml/v2 v2.2.4/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
+github.com/pkg/errors v0.8.0/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
+github.com/pkg/errors v0.8.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
+github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
+github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/posener/complete v1.1.1/go.mod h1:em0nMJCgc9GFtwrmVmEMR/ZL6WyhyjMBndrE9hABlRI=
+github.com/posener/complete v1.2.3/go.mod h1:WZIdtGGp+qx0sLrYKtIRAruyNpv6hFCicSgv7Sy7s/s=
+github.com/prometheus/client_golang v0.9.1/go.mod h1:7SWBe2y4D6OKWSNQJUaRYU/AaXPKyh/dDVn+NZz0KFw=
+github.com/prometheus/client_golang v1.0.0/go.mod h1:db9x61etRT2tGnBNRi70OPL5FsnadC4Ky3P0J6CfImo=
+github.com/prometheus/client_golang v1.4.0/go.mod h1:e9GMxYsXl05ICDXkRhurwBS4Q3OK1iX/F2sw+iXX5zU=
 github.com/prometheus/client_golang v1.23.2 h1:Je96obch5RDVy3FDMndoUsjAhG5Edi49h0RJWRi/o0o=
 github.com/prometheus/client_golang v1.23.2/go.mod h1:Tb1a6LWHB3/SPIzCoaDXI4I8UHKeFTEQ1YCr+0Gyqmg=
+github.com/prometheus/client_model v0.0.0-20180712105110-5c3871d89910/go.mod h1:MbSGuTsp3dbXC40dX6PRTWyKYBIrTGTE9sqQNg2J8bo=
+github.com/prometheus/client_model v0.0.0-20190129233127-fd36f4220a90/go.mod h1:xMI15A0UPsDsEKsMN9yxemIoYk6Tm2C1GtYGdfGttqA=
+github.com/prometheus/client_model v0.2.0/go.mod h1:xMI15A0UPsDsEKsMN9yxemIoYk6Tm2C1GtYGdfGttqA=
 github.com/prometheus/client_model v0.6.2 h1:oBsgwpGs7iVziMvrGhE53c/GrLUsZdHnqNwqPLxwZyk=
 github.com/prometheus/client_model v0.6.2/go.mod h1:y3m2F6Gdpfy6Ut/GBsUqTWZqCUvMVzSfMLjcu6wAwpE=
+github.com/prometheus/common v0.4.1/go.mod h1:TNfzLD0ON7rHzMJeJkieUDPYmFC7Snx/y86RQel1bk4=
+github.com/prometheus/common v0.9.1/go.mod h1:yhUN8i9wzaXS3w1O07YhxHEBxD+W35wd8bs7vj7HSQ4=
 github.com/prometheus/common v0.66.1 h1:h5E0h5/Y8niHc5DlaLlWLArTQI7tMrsfQjHV+d9ZoGs=
 github.com/prometheus/common v0.66.1/go.mod h1:gcaUsgf3KfRSwHY4dIMXLPV0K/Wg1oZ8+SbZk/HH/dA=
+github.com/prometheus/procfs v0.0.0-20181005140218-185b4288413d/go.mod h1:c3At6R/oaqEKCNdg8wHV1ftS6bRYblBhIjjI8uT2IGk=
+github.com/prometheus/procfs v0.0.2/go.mod h1:TjEm7ze935MbeOT/UhFTIMYKhuLP4wbCsTZCD3I8kEA=
+github.com/prometheus/procfs v0.0.8/go.mod h1:7Qr8sr6344vo1JqZ6HhLceV9o3AJ1Ff+GxbHq6oeK9A=
 github.com/prometheus/procfs v0.16.1 h1:hZ15bTNuirocR6u0JZ6BAHHmwS1p8B4P6MRqxtzMyRg=
 github.com/prometheus/procfs v0.16.1/go.mod h1:teAbpZRB1iIAJYREa1LsoWUXykVXA1KlTmWl8x/U+Is=
 github.com/rogpeppe/go-internal v1.13.1 h1:KvO1DLK/DRN07sQ1LQKScxyZJuNnedQ5/wKSR38lUII=
 github.com/rogpeppe/go-internal v1.13.1/go.mod h1:uMEvuHeurkdAXX61udpOXGD/AzZDWNMNyH2VO9fmH0o=
+github.com/ryanuber/columnize v0.0.0-20160712163229-9b3edd62028f/go.mod h1:sm1tb6uqfes/u+d4ooFouqFdy9/2g9QGwK3SQygK0Ts=
 github.com/sagikazarmark/locafero v0.4.0 h1:HApY1R9zGo4DBgr7dqsTH/JJxLTTsOt7u6keLGt6kNQ=
 github.com/sagikazarmark/locafero v0.4.0/go.mod h1:Pe1W6UlPYUk/+wc/6KFhbORCfqzgYEpgQ3O5fPuL3H4=
 github.com/sagikazarmark/slog-shim v0.1.0 h1:diDBnUNK9N/354PgrxMywXnAwEr1QZcOr6gto+ugjYE=
 github.com/sagikazarmark/slog-shim v0.1.0/go.mod h1:SrcSrq8aKtyuqEI1uvTDTK1arOWRIczQRv+GVI1AkeQ=
+github.com/sean-/seed v0.0.0-20170313163322-e2103e2c3529 h1:nn5Wsu0esKSJiIVhscUtVbo7ada43DJhG55ua/hjS5I=
+github.com/sean-/seed v0.0.0-20170313163322-e2103e2c3529/go.mod h1:DxrIzT+xaE7yg65j358z/aeFdxmN0P9QXhEzd20vsDc=
 github.com/sergi/go-diff v1.3.1 h1:xkr+Oxo4BOQKmkn/B9eMK0g5Kg/983T9DqqPHwYqD+8=
 github.com/sergi/go-diff v1.3.1/go.mod h1:aMJSSKb2lpPvRNec0+w3fl7LP9IOFzdc9Pa4NFbPK1I=
+github.com/sirupsen/logrus v1.2.0/go.mod h1:LxeOpSwHxABJmUn/MG1IvRgCAasNZTLOkJPxbbu5VWo=
+github.com/sirupsen/logrus v1.4.2/go.mod h1:tLMulIdttU9McNUspp0xgXVQah82FyeX6MwdIuYE2rE=
 github.com/sourcegraph/conc v0.3.0 h1:OQTbbt6P72L20UqAkXXuLOj79LfEanQ+YQFNpLA9ySo=
 github.com/sourcegraph/conc v0.3.0/go.mod h1:Sdozi7LEKbFPqYX2/J+iBAM6HpqSLTASQIKqDmF7Mt0=
 github.com/spf13/afero v1.11.0 h1:WJQKhtpdm3v2IzqG8VMqrr6Rf3UYpEF239Jy9wNepM8=
@@ -133,16 +272,22 @@ github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An
 github.com/spf13/viper v1.18.0 h1:pN6W1ub/G4OfnM+NR9p7xP9R6TltLUzp5JG9yZD3Qg0=
 github.com/spf13/viper v1.18.0/go.mod h1:EKmWIqdnk5lOcmR72yw6hS+8OPYcwD0jteitLMVB+yk=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/objx v0.1.1/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
+github.com/stretchr/objx v0.5.0 h1:1zr/of2m5FGMsad5YfcqgdqdWrIhu+EBEJRhR1U7z/c=
 github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
+github.com/stretchr/testify v1.2.2/go.mod h1:a8OnRcib4nhh0OaRAV+Yts87kKdq0PP7pXfy6kDkUVs=
 github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.4.0/go.mod h1:j7eGeouHqKxXV5pUuKE4zz7dFj8WfuZ+81PSLYec5m4=
 github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.7.2/go.mod h1:R6va5+xMeoiuVRoj+gSkQ7d3FALtqAAGI1FQKckRals=
 github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
 github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
 github.com/subosito/gotenv v1.6.0 h1:9NlTDc1FTs4qu0DDq7AEtTPNw6SVm7uBMsUCUjABIf8=
 github.com/subosito/gotenv v1.6.0/go.mod h1:Dk4QP5c2W3ibzajGcXpNraDfq2IrhjMIvMSWPKKo0FU=
+github.com/tv42/httpunix v0.0.0-20150427012821-b75d8614f926/go.mod h1:9ESjWnEqriFuLhtthL60Sar/7RFoluCcXsuvEwTV5KM=
 github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=
 github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=
 github.com/ugorji/go/codec v1.3.0 h1:Qd2W2sQawAfG8XSvzwhBeoGq71zXOC/Q1E9y/wUcsUA=
@@ -189,19 +334,63 @@ go.yaml.in/yaml/v2 v2.4.2 h1:DzmwEr2rDGHl7lsFgAHxmNz/1NlQ7xLIrlN2h5d1eGI=
 go.yaml.in/yaml/v2 v2.4.2/go.mod h1:081UH+NErpNdqlCXm3TtEran0rJZGxAYx9hb/ELlsPU=
 golang.org/x/arch v0.20.0 h1:dx1zTU0MAE98U+TQ8BLl7XsJbgze2WnNKF/8tGp/Q6c=
 golang.org/x/arch v0.20.0/go.mod h1:bdwinDaKcfZUGpH09BB7ZmOfhalA8lQdzl62l8gGWsk=
+golang.org/x/crypto v0.0.0-20180904163835-0709b304e793/go.mod h1:6SG95UA2DQfeDnfUPMdvaQW0Q7yPrPDi9nlGo2tz2b4=
+golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
+golang.org/x/crypto v0.0.0-20190923035154-9ee001bba392/go.mod h1:/lpIB1dKB+9EgE3H3cr1v9wB50oz8l4C4h62xy7jSTY=
 golang.org/x/crypto v0.41.0 h1:WKYxWedPGCTVVl5+WHSSrOBT0O8lx32+zxmHxijgXp4=
 golang.org/x/crypto v0.41.0/go.mod h1:pO5AFd7FA68rFak7rOAGVuygIISepHftHnr8dr6+sUc=
-golang.org/x/exp v0.0.0-20230905200255-921286631fa9 h1:GoHiUyI/Tp2nVkLI2mCxVkOjsbSXD66ic0XW0js0R9g=
+golang.org/x/exp v0.0.0-20250808145144-a408d31f581a h1:Y+7uR/b1Mw2iSXZ3G//1haIiSElDQZ8KWh0h+sZPG90=
-golang.org/x/exp v0.0.0-20230905200255-921286631fa9/go.mod h1:S2oDrQGGwySpoQPVqRShND87VCbxmc6bL1Yd2oYrm6k=
+golang.org/x/exp v0.0.0-20250808145144-a408d31f581a/go.mod h1:rT6SFzZ7oxADUDx58pcaKFTcZ+inxAa9fTrYx/uVYwg=
-golang.org/x/mod v0.26.0 h1:EGMPT//Ezu+ylkCijjPc+f4Aih7sZvaAr+O3EHBxvZg=
+golang.org/x/mod v0.27.0 h1:kb+q2PyFnEADO2IEF935ehFUXlWiNjJWtRNgBLSfbxQ=
-golang.org/x/mod v0.26.0/go.mod h1:/j6NAhSk8iQ723BGAUyoAcn7SlD7s15Dp9Nd/SfeaFQ=
+golang.org/x/mod v0.27.0/go.mod h1:rWI627Fq0DEoudcK+MBkNkCe0EetEaDSwJJkCcjpazc=
+golang.org/x/net v0.0.0-20181114220301-adae6a3d119a/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
+golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
+golang.org/x/net v0.0.0-20190613194153-d28f0bde5980/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/net v0.0.0-20190923162816-aa69164e4478/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
+golang.org/x/net v0.0.0-20210410081132-afb366fc7cd1/go.mod h1:9tjilg8BloeKEkVJvy7fQ90B1CfIiPueXVOjqfkSzI8=
 golang.org/x/net v0.43.0 h1:lat02VYK2j4aLzMzecihNvTlJNQUq316m2Mr9rnM6YE=
 golang.org/x/net v0.43.0/go.mod h1:vhO1fvI4dGsIjh73sWfUVjj3N7CA9WkKJNQm2svM6Jg=
+golang.org/x/sync v0.0.0-20181108010431-42b317875d0f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20181221193216-37e7f081c4d4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20190911185100-cd5d95a43a6e/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20210220032951-036812b2e83c/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sys v0.0.0-20180823144017-11551d06cbcc/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20180905080454-ebe1bf3edb33/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20181116152217-5ac8a444bdc5/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20190222072716-a9d3bda3a223/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20190422165155-953cdadca894/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20190922100055-0a153f010e69/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20190924154521-2837fb4f24fe/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20191026070338-33540a1f6037/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20200116001909-b77594299b42/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20200122134326-e047566fdf82/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20200223170610-d5e6a3e2c0ae/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210303074136-134d130e1a04/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210330210617-4fbd30eecc44/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210630005230-0f9fa26af87c/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20210927094055-39ccf1dd6fa6/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220503163025-988cb79eb6c6/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220728004956-3c1f35247d10/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.35.0 h1:vz1N37gP5bs89s7He8XuIYXpyY0+QlsKmzipCbUtyxI=
 golang.org/x/sys v0.35.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
+golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
+golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
+golang.org/x/text v0.3.2/go.mod h1:bEr9sfX3Q8Zfm5fL9x+3itogRgK3+ptLWKqgva+5dAk=
+golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
+golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.28.0 h1:rhazDwis8INMIwQ4tpjLDzUhx6RlXqZNPEM0huQojng=
 golang.org/x/text v0.28.0/go.mod h1:U8nCwOR8jO/marOQ0QbDiOngZVEBB7MAiitBuMjXiNU=
+golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
+golang.org/x/tools v0.0.0-20190907020128-2ca718005c18/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
+golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 gonum.org/v1/gonum v0.16.0 h1:5+ul4Swaf3ESvrOnidPp4GZbzf0mxVQpDCYUQE7OJfk=
 gonum.org/v1/gonum v0.16.0/go.mod h1:fef3am4MQ93R2HHpKnLk4/Tbh/s0+wqD5nfa6Pnwy4E=
 google.golang.org/genproto/googleapis/api v0.0.0-20250825161204-c5933d9347a5 h1:BIRfGDEjiHRrk0QKZe3Xv2ieMhtgRGeLcZQ0mIVn4EY=
@@ -212,11 +401,17 @@ google.golang.org/grpc v1.75.0 h1:+TW+dqTd2Biwe6KKfhE5JpiYIBWq865PhKGSXiivqt4=
 google.golang.org/grpc v1.75.0/go.mod h1:JtPAzKiq4v1xcAB2hydNlWI2RnF85XXcV0mhKXr2ecQ=
 google.golang.org/protobuf v1.36.8 h1:xHScyCOEuuwZEc6UtSOvPbAT4zRh0xcNRYekJwfqyMc=
 google.golang.org/protobuf v1.36.8/go.mod h1:fuxRtAxBytpl4zzqUh6/eyUujkJdNiuEkXntxiD/uRU=
+gopkg.in/alecthomas/kingpin.v2 v2.2.6/go.mod h1:FMv+mEhP44yOT+4EoQTLFTRgOQ1FBLkstjWtayDeSgw=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
 gopkg.in/ini.v1 v1.67.0 h1:Dgnx+6+nfE+IfzjUEISNeydPJh9AXNNsWbGP9KzCsOA=
 gopkg.in/ini.v1 v1.67.0/go.mod h1:pNLf8WUiyNEtQjuu5G5vTm06TEv9tsIgeAvK8hOrP4k=
+gopkg.in/yaml.v2 v2.2.1/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v2 v2.2.4/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v2 v2.2.5/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

internal/client/factory.go

@@ -0,0 +1,51 @@
+// Package client provides service client factory for creating service clients.
+package client
+
+import (
+	"context"
+	"fmt"
+
+	"git.dcentral.systems/toolz/goplt/internal/client/grpc"
+	"git.dcentral.systems/toolz/goplt/pkg/registry"
+	"git.dcentral.systems/toolz/goplt/pkg/services"
+)
+
+// ServiceClientFactory creates service clients for inter-service communication.
+type ServiceClientFactory struct {
+	registry registry.ServiceRegistry
+}
+
+// NewServiceClientFactory creates a new service client factory.
+func NewServiceClientFactory(reg registry.ServiceRegistry) *ServiceClientFactory {
+	return &ServiceClientFactory{
+		registry: reg,
+	}
+}
+
+// GetAuthClient returns an AuthServiceClient.
+func (f *ServiceClientFactory) GetAuthClient() (services.AuthServiceClient, error) {
+	return grpc.NewAuthClient(f.registry)
+}
+
+// GetIdentityClient returns an IdentityServiceClient.
+func (f *ServiceClientFactory) GetIdentityClient() (services.IdentityServiceClient, error) {
+	return grpc.NewIdentityClient(f.registry)
+}
+
+// GetAuthzClient returns an AuthzServiceClient.
+func (f *ServiceClientFactory) GetAuthzClient() (services.AuthzServiceClient, error) {
+	return grpc.NewAuthzClient(f.registry)
+}
+
+// GetAuditClient returns an AuditServiceClient.
+func (f *ServiceClientFactory) GetAuditClient() (services.AuditServiceClient, error) {
+	return grpc.NewAuditClient(f.registry)
+}
+
+// DiscoverService discovers service instances for a given service name.
+func (f *ServiceClientFactory) DiscoverService(ctx context.Context, serviceName string) ([]*registry.ServiceInstance, error) {
+	if f.registry == nil {
+		return nil, fmt.Errorf("service registry is not available")
+	}
+	return f.registry.Discover(ctx, serviceName)
+}

internal/client/grpc/audit_client.go

@@ -0,0 +1,33 @@
+// Package grpc provides gRPC client implementations for service clients.
+package grpc
+
+import (
+	"context"
+	"fmt"
+
+	"git.dcentral.systems/toolz/goplt/pkg/registry"
+	"git.dcentral.systems/toolz/goplt/pkg/services"
+)
+
+// AuditClient implements AuditServiceClient using gRPC.
+// This is a stub implementation - will be fully implemented when proto files are generated in Phase 4.
+type AuditClient struct {
+	registry registry.ServiceRegistry
+}
+
+// NewAuditClient creates a new gRPC client for the Audit Service.
+func NewAuditClient(reg registry.ServiceRegistry) (services.AuditServiceClient, error) {
+	return &AuditClient{
+		registry: reg,
+	}, nil
+}
+
+// Record records an audit log entry.
+func (c *AuditClient) Record(ctx context.Context, entry *services.AuditLogEntry) error {
+	return fmt.Errorf("not implemented: proto files not yet generated")
+}
+
+// Query queries audit logs based on filters.
+func (c *AuditClient) Query(ctx context.Context, filters *services.AuditLogFilters) ([]services.AuditLogEntry, error) {
+	return nil, fmt.Errorf("not implemented: proto files not yet generated")
+}

internal/client/grpc/auth_client.go

@@ -0,0 +1,74 @@
+// Package grpc provides gRPC client implementations for service clients.
+package grpc
+
+import (
+	"context"
+	"fmt"
+
+	"git.dcentral.systems/toolz/goplt/pkg/registry"
+	"git.dcentral.systems/toolz/goplt/pkg/services"
+)
+
+// AuthClient implements AuthServiceClient using gRPC.
+// This is a stub implementation - will be fully implemented when proto files are generated in Phase 4.
+type AuthClient struct {
+	registry registry.ServiceRegistry
+	// conn will be set when proto files are available
+	// conn *grpc.ClientConn
+}
+
+// NewAuthClient creates a new gRPC client for the Auth Service.
+func NewAuthClient(reg registry.ServiceRegistry) (services.AuthServiceClient, error) {
+	return &AuthClient{
+		registry: reg,
+	}, nil
+}
+
+// Login authenticates a user and returns access and refresh tokens.
+func (c *AuthClient) Login(ctx context.Context, email, password string) (*services.TokenResponse, error) {
+	// TODO: Implement when proto files are generated
+	return nil, fmt.Errorf("not implemented: proto files not yet generated")
+}
+
+// RefreshToken refreshes an access token using a refresh token.
+func (c *AuthClient) RefreshToken(ctx context.Context, refreshToken string) (*services.TokenResponse, error) {
+	// TODO: Implement when proto files are generated
+	return nil, fmt.Errorf("not implemented: proto files not yet generated")
+}
+
+// ValidateToken validates a JWT token and returns the token claims.
+func (c *AuthClient) ValidateToken(ctx context.Context, token string) (*services.TokenClaims, error) {
+	// TODO: Implement when proto files are generated
+	return nil, fmt.Errorf("not implemented: proto files not yet generated")
+}
+
+// Logout invalidates a refresh token.
+func (c *AuthClient) Logout(ctx context.Context, refreshToken string) error {
+	// TODO: Implement when proto files are generated
+	return fmt.Errorf("not implemented: proto files not yet generated")
+}
+
+// TODO: connectToService will be implemented when proto files are generated
+// This function will discover and connect to a service instance via gRPC.
+// func connectToService(ctx context.Context, reg registry.ServiceRegistry, serviceName string) (*grpc.ClientConn, error) {
+// 	instances, err := reg.Discover(ctx, serviceName)
+// 	if err != nil {
+// 		return nil, fmt.Errorf("failed to discover service %s: %w", serviceName, err)
+// 	}
+//
+// 	if len(instances) == 0 {
+// 		return nil, fmt.Errorf("no instances found for service %s", serviceName)
+// 	}
+//
+// 	// Use the first healthy instance (load balancing can be added later)
+// 	instance := instances[0]
+// 	address := fmt.Sprintf("%s:%d", instance.Address, instance.Port)
+//
+// 	// Create gRPC connection
+// 	conn, err := grpc.NewClient(address, grpc.WithTransportCredentials(insecure.NewCredentials()))
+// 	if err != nil {
+// 		return nil, fmt.Errorf("failed to connect to %s at %s: %w", serviceName, address, err)
+// 	}
+//
+// 	return conn, nil
+// }

internal/client/grpc/authz_client.go

@@ -0,0 +1,43 @@
+// Package grpc provides gRPC client implementations for service clients.
+package grpc
+
+import (
+	"context"
+	"fmt"
+
+	"git.dcentral.systems/toolz/goplt/pkg/registry"
+	"git.dcentral.systems/toolz/goplt/pkg/services"
+)
+
+// AuthzClient implements AuthzServiceClient using gRPC.
+// This is a stub implementation - will be fully implemented when proto files are generated in Phase 4.
+type AuthzClient struct {
+	registry registry.ServiceRegistry
+}
+
+// NewAuthzClient creates a new gRPC client for the Authz Service.
+func NewAuthzClient(reg registry.ServiceRegistry) (services.AuthzServiceClient, error) {
+	return &AuthzClient{
+		registry: reg,
+	}, nil
+}
+
+// Authorize checks if a user has a specific permission and returns an error if not.
+func (c *AuthzClient) Authorize(ctx context.Context, userID, permission string) error {
+	return fmt.Errorf("not implemented: proto files not yet generated")
+}
+
+// HasPermission checks if a user has a specific permission.
+func (c *AuthzClient) HasPermission(ctx context.Context, userID, permission string) (bool, error) {
+	return false, fmt.Errorf("not implemented: proto files not yet generated")
+}
+
+// GetUserPermissions returns all permissions for a user.
+func (c *AuthzClient) GetUserPermissions(ctx context.Context, userID string) ([]services.Permission, error) {
+	return nil, fmt.Errorf("not implemented: proto files not yet generated")
+}
+
+// GetUserRoles returns all roles for a user.
+func (c *AuthzClient) GetUserRoles(ctx context.Context, userID string) ([]services.Role, error) {
+	return nil, fmt.Errorf("not implemented: proto files not yet generated")
+}

internal/client/grpc/identity_client.go

@@ -0,0 +1,63 @@
+// Package grpc provides gRPC client implementations for service clients.
+package grpc
+
+import (
+	"context"
+	"fmt"
+
+	"git.dcentral.systems/toolz/goplt/pkg/registry"
+	"git.dcentral.systems/toolz/goplt/pkg/services"
+)
+
+// IdentityClient implements IdentityServiceClient using gRPC.
+// This is a stub implementation - will be fully implemented when proto files are generated in Phase 4.
+type IdentityClient struct {
+	registry registry.ServiceRegistry
+}
+
+// NewIdentityClient creates a new gRPC client for the Identity Service.
+func NewIdentityClient(reg registry.ServiceRegistry) (services.IdentityServiceClient, error) {
+	return &IdentityClient{
+		registry: reg,
+	}, nil
+}
+
+// GetUser retrieves a user by ID.
+func (c *IdentityClient) GetUser(ctx context.Context, id string) (*services.User, error) {
+	return nil, fmt.Errorf("not implemented: proto files not yet generated")
+}
+
+// GetUserByEmail retrieves a user by email address.
+func (c *IdentityClient) GetUserByEmail(ctx context.Context, email string) (*services.User, error) {
+	return nil, fmt.Errorf("not implemented: proto files not yet generated")
+}
+
+// CreateUser creates a new user.
+func (c *IdentityClient) CreateUser(ctx context.Context, user *services.CreateUserRequest) (*services.User, error) {
+	return nil, fmt.Errorf("not implemented: proto files not yet generated")
+}
+
+// UpdateUser updates an existing user.
+func (c *IdentityClient) UpdateUser(ctx context.Context, id string, user *services.UpdateUserRequest) (*services.User, error) {
+	return nil, fmt.Errorf("not implemented: proto files not yet generated")
+}
+
+// DeleteUser deletes a user.
+func (c *IdentityClient) DeleteUser(ctx context.Context, id string) error {
+	return fmt.Errorf("not implemented: proto files not yet generated")
+}
+
+// VerifyEmail verifies a user's email address using a verification token.
+func (c *IdentityClient) VerifyEmail(ctx context.Context, token string) error {
+	return fmt.Errorf("not implemented: proto files not yet generated")
+}
+
+// RequestPasswordReset requests a password reset token.
+func (c *IdentityClient) RequestPasswordReset(ctx context.Context, email string) error {
+	return fmt.Errorf("not implemented: proto files not yet generated")
+}
+
+// ResetPassword resets a user's password using a reset token.
+func (c *IdentityClient) ResetPassword(ctx context.Context, token, newPassword string) error {
+	return fmt.Errorf("not implemented: proto files not yet generated")
+}

internal/di/providers.go

@@ -7,6 +7,7 @@ import (
 	"os"
 	"time"
 
+	"git.dcentral.systems/toolz/goplt/internal/client"
 	configimpl "git.dcentral.systems/toolz/goplt/internal/config"
 	errorbusimpl "git.dcentral.systems/toolz/goplt/internal/errorbus"
 	"git.dcentral.systems/toolz/goplt/internal/health"
@@ -14,10 +15,12 @@ import (
 	loggerimpl "git.dcentral.systems/toolz/goplt/internal/logger"
 	"git.dcentral.systems/toolz/goplt/internal/metrics"
 	"git.dcentral.systems/toolz/goplt/internal/observability"
+	"git.dcentral.systems/toolz/goplt/internal/registry/consul"
 	"git.dcentral.systems/toolz/goplt/internal/server"
 	"git.dcentral.systems/toolz/goplt/pkg/config"
 	"git.dcentral.systems/toolz/goplt/pkg/errorbus"
 	"git.dcentral.systems/toolz/goplt/pkg/logger"
+	"git.dcentral.systems/toolz/goplt/pkg/registry"
 	"go.opentelemetry.io/otel/trace"
 	"go.opentelemetry.io/otel/trace/noop"
 	"go.uber.org/fx"
@@ -158,13 +161,11 @@ func ProvideErrorBus() fx.Option {
 }
 
 // ProvideHealthRegistry creates an FX option that provides the health check registry.
+// Note: Database health checkers are registered by services that create their own database clients.
 func ProvideHealthRegistry() fx.Option {
-	return fx.Provide(func(dbClient *database.Client) (*health.Registry, error) {
+	return fx.Provide(func() (*health.Registry, error) {
 		registry := health.NewRegistry()
-
+		// Services will register their own health checkers (e.g., database, external dependencies)
-		// Register database health checker
-		registry.Register("database", health.NewDatabaseChecker(dbClient))
-
 		return registry, nil
 	})
 }
@@ -176,6 +177,72 @@ func ProvideMetrics() fx.Option {
 	})
 }
 
+// ProvideServiceRegistry creates an FX option that provides the service registry.
+func ProvideServiceRegistry() fx.Option {
+	return fx.Provide(func(cfg config.ConfigProvider) (registry.ServiceRegistry, error) {
+		registryType := cfg.GetString("registry.type")
+		if registryType == "" {
+			registryType = "consul"
+		}
+
+		switch registryType {
+		case "consul":
+			consulCfg := consul.Config{
+				Address:    cfg.GetString("registry.consul.address"),
+				Datacenter: cfg.GetString("registry.consul.datacenter"),
+				Scheme:     cfg.GetString("registry.consul.scheme"),
+			}
+
+			// Set defaults
+			if consulCfg.Address == "" {
+				consulCfg.Address = "localhost:8500"
+			}
+			if consulCfg.Datacenter == "" {
+				consulCfg.Datacenter = "dc1"
+			}
+			if consulCfg.Scheme == "" {
+				consulCfg.Scheme = "http"
+			}
+
+			// Parse health check configuration
+			healthCheckInterval := cfg.GetDuration("registry.consul.health_check.interval")
+			if healthCheckInterval == 0 {
+				healthCheckInterval = 10 * time.Second
+			}
+			healthCheckTimeout := cfg.GetDuration("registry.consul.health_check.timeout")
+			if healthCheckTimeout == 0 {
+				healthCheckTimeout = 3 * time.Second
+			}
+			healthCheckDeregisterAfter := cfg.GetDuration("registry.consul.health_check.deregister_after")
+			if healthCheckDeregisterAfter == 0 {
+				healthCheckDeregisterAfter = 30 * time.Second
+			}
+			healthCheckHTTP := cfg.GetString("registry.consul.health_check.http")
+			if healthCheckHTTP == "" {
+				healthCheckHTTP = "/healthz"
+			}
+
+			consulCfg.HealthCheck = consul.HealthCheckConfig{
+				Interval:        healthCheckInterval,
+				Timeout:         healthCheckTimeout,
+				DeregisterAfter: healthCheckDeregisterAfter,
+				HTTP:            healthCheckHTTP,
+			}
+
+			return consul.NewRegistry(consulCfg)
+		default:
+			return nil, fmt.Errorf("unsupported registry type: %s", registryType)
+		}
+	})
+}
+
+// ProvideServiceClientFactory creates an FX option that provides the service client factory.
+func ProvideServiceClientFactory() fx.Option {
+	return fx.Provide(func(reg registry.ServiceRegistry) (*client.ServiceClientFactory, error) {
+		return client.NewServiceClientFactory(reg), nil
+	})
+}
+
 // ProvideTracer creates an FX option that provides the OpenTelemetry tracer.
 func ProvideTracer() fx.Option {
 	return fx.Provide(func(cfg config.ConfigProvider, lc fx.Lifecycle) (trace.TracerProvider, error) {
@@ -318,18 +385,21 @@ func ProvideHTTPServer() fx.Option {
 	})
 }
 
-// CoreModule returns an FX option that provides all core services.
+// CoreModule returns an FX option that provides all core kernel infrastructure services.
-// This includes configuration, logging, database, error bus, health checks, metrics, tracing, and HTTP server.
+// This includes configuration, logging, error bus, health checks, metrics, tracing, service registry, and service client factory.
+// Note: Database and HTTP server are NOT included - services will create their own instances.
+// HTTP server foundation is available via server.NewServer() for services to use.
 func CoreModule() fx.Option {
 	return fx.Options(
 		ProvideConfig(),
 		ProvideLogger(),
-		ProvideDatabase(),
 		ProvideErrorBus(),
 		ProvideHealthRegistry(),
 		ProvideMetrics(),
 		ProvideTracer(),
-		ProvideHTTPServer(),
+		ProvideServiceRegistry(),
+		ProvideServiceClientFactory(),
+		// Note: ProvideDatabase() and ProvideHTTPServer() are removed - services create their own
 	)
 }
 

internal/infra/database/client.go

@@ -22,13 +22,15 @@ type Client struct {
 // Config holds database configuration.
 type Config struct {
 	DSN             string
+	Schema          string // Schema name for schema isolation (e.g., "identity", "auth", "authz", "audit")
 	MaxConnections  int
 	MaxIdleConns    int
 	ConnMaxLifetime time.Duration
 	ConnMaxIdleTime time.Duration
 }
 
-// NewClient creates a new Ent client with connection pooling.
+// NewClient creates a new Ent client with connection pooling and schema isolation support.
+// If schema is provided, it will be created if it doesn't exist and set as the search path.
 func NewClient(cfg Config) (*Client, error) {
 	// Open database connection
 	db, err := sql.Open("postgres", cfg.DSN)
@@ -51,6 +53,19 @@ func NewClient(cfg Config) (*Client, error) {
 		return nil, fmt.Errorf("failed to ping database: %w", err)
 	}
 
+	// Create schema if provided
+	if cfg.Schema != "" {
+		if err := createSchemaIfNotExists(ctx, db, cfg.Schema); err != nil {
+			_ = db.Close()
+			return nil, fmt.Errorf("failed to create schema %s: %w", cfg.Schema, err)
+		}
+		// Set search path to the schema
+		if _, err := db.ExecContext(ctx, fmt.Sprintf("SET search_path TO %s", cfg.Schema)); err != nil {
+			_ = db.Close()
+			return nil, fmt.Errorf("failed to set search path to schema %s: %w", cfg.Schema, err)
+		}
+	}
+
 	// Create Ent driver
 	drv := entsql.OpenDB(dialect.Postgres, db)
 
@@ -63,6 +78,51 @@ func NewClient(cfg Config) (*Client, error) {
 	}, nil
 }
 
+// NewClientWithSchema is a convenience function that creates a client with a specific schema.
+func NewClientWithSchema(dsn string, schema string) (*Client, error) {
+	return NewClient(Config{
+		DSN:             dsn,
+		Schema:          schema,
+		MaxConnections:  25,
+		MaxIdleConns:    5,
+		ConnMaxLifetime: 5 * time.Minute,
+		ConnMaxIdleTime: 10 * time.Minute,
+	})
+}
+
+// createSchemaIfNotExists creates a PostgreSQL schema if it doesn't exist.
+func createSchemaIfNotExists(ctx context.Context, db *sql.DB, schemaName string) error {
+	// Use a transaction to ensure atomicity
+	tx, err := db.BeginTx(ctx, nil)
+	if err != nil {
+		return err
+	}
+	defer func() {
+		_ = tx.Rollback() // Ignore error - if commit succeeded, rollback will error (expected)
+	}()
+
+	// Check if schema exists
+	var exists bool
+	err = tx.QueryRowContext(ctx,
+		"SELECT EXISTS(SELECT 1 FROM information_schema.schemata WHERE schema_name = $1)",
+		schemaName,
+	).Scan(&exists)
+	if err != nil {
+		return err
+	}
+
+	// Create schema if it doesn't exist
+	if !exists {
+		// Use fmt.Sprintf for schema name since it's a configuration value, not user input
+		_, err = tx.ExecContext(ctx, fmt.Sprintf("CREATE SCHEMA IF NOT EXISTS %s", schemaName))
+		if err != nil {
+			return err
+		}
+	}
+
+	return tx.Commit()
+}
+
 // Close closes the database connection.
 func (c *Client) Close() error {
 	if err := c.Client.Close(); err != nil {

internal/registry/consul/consul.go

@@ -0,0 +1,198 @@
+// Package consul provides Consul-based service registry implementation.
+package consul
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"git.dcentral.systems/toolz/goplt/pkg/registry"
+	consulapi "github.com/hashicorp/consul/api"
+)
+
+// ConsulRegistry implements ServiceRegistry using Consul.
+type ConsulRegistry struct {
+	client *consulapi.Client
+	config *Config
+}
+
+// Config holds Consul registry configuration.
+type Config struct {
+	Address     string // Consul agent address (e.g., "localhost:8500")
+	Datacenter  string // Consul datacenter
+	Scheme      string // "http" or "https"
+	HealthCheck HealthCheckConfig
+}
+
+// HealthCheckConfig holds health check configuration.
+type HealthCheckConfig struct {
+	Interval        time.Duration // Health check interval
+	Timeout         time.Duration // Health check timeout
+	DeregisterAfter time.Duration // Time to wait before deregistering unhealthy service
+	HTTP            string        // HTTP health check endpoint (e.g., "/healthz")
+}
+
+// NewRegistry creates a new Consul-based service registry.
+func NewRegistry(cfg Config) (*ConsulRegistry, error) {
+	consulConfig := consulapi.DefaultConfig()
+	if cfg.Address != "" {
+		consulConfig.Address = cfg.Address
+	}
+	if cfg.Datacenter != "" {
+		consulConfig.Datacenter = cfg.Datacenter
+	}
+	if cfg.Scheme != "" {
+		consulConfig.Scheme = cfg.Scheme
+	}
+
+	client, err := consulapi.NewClient(consulConfig)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create Consul client: %w", err)
+	}
+
+	return &ConsulRegistry{
+		client: client,
+		config: &cfg,
+	}, nil
+}
+
+// Register registers a service instance with Consul.
+func (r *ConsulRegistry) Register(ctx context.Context, service *registry.ServiceInstance) error {
+	registration := &consulapi.AgentServiceRegistration{
+		ID:      service.ID,
+		Name:    service.Name,
+		Address: service.Address,
+		Port:    service.Port,
+		Tags:    service.Tags,
+		Meta:    service.Metadata,
+	}
+
+	// Add health check if configured
+	if r.config.HealthCheck.HTTP != "" {
+		healthCheckURL := fmt.Sprintf("http://%s:%d%s", service.Address, service.Port, r.config.HealthCheck.HTTP)
+		registration.Check = &consulapi.AgentServiceCheck{
+			HTTP:                           healthCheckURL,
+			Interval:                       r.config.HealthCheck.Interval.String(),
+			Timeout:                        r.config.HealthCheck.Timeout.String(),
+			DeregisterCriticalServiceAfter: r.config.HealthCheck.DeregisterAfter.String(),
+		}
+	}
+
+	return r.client.Agent().ServiceRegister(registration)
+}
+
+// Deregister removes a service instance from Consul.
+func (r *ConsulRegistry) Deregister(ctx context.Context, serviceID string) error {
+	return r.client.Agent().ServiceDeregister(serviceID)
+}
+
+// Discover returns all healthy instances of a service.
+func (r *ConsulRegistry) Discover(ctx context.Context, serviceName string) ([]*registry.ServiceInstance, error) {
+	services, _, err := r.client.Health().Service(serviceName, "", true, nil)
+	if err != nil {
+		return nil, fmt.Errorf("failed to discover service %s: %w", serviceName, err)
+	}
+
+	instances := make([]*registry.ServiceInstance, 0, len(services))
+	for _, service := range services {
+		instances = append(instances, &registry.ServiceInstance{
+			ID:       service.Service.ID,
+			Name:     service.Service.Service,
+			Address:  service.Service.Address,
+			Port:     service.Service.Port,
+			Tags:     service.Service.Tags,
+			Metadata: service.Service.Meta,
+		})
+	}
+
+	return instances, nil
+}
+
+// Watch returns a channel that receives updates when service instances change.
+func (r *ConsulRegistry) Watch(ctx context.Context, serviceName string) (<-chan []*registry.ServiceInstance, error) {
+	updates := make(chan []*registry.ServiceInstance, 10)
+
+	go func() {
+		defer close(updates)
+
+		lastIndex := uint64(0)
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			default:
+				services, meta, err := r.client.Health().Service(serviceName, "", true, &consulapi.QueryOptions{
+					WaitIndex: lastIndex,
+					WaitTime:  10 * time.Second,
+				})
+				if err != nil {
+					// Log error and continue
+					continue
+				}
+
+				if meta.LastIndex != lastIndex {
+					instances := make([]*registry.ServiceInstance, 0, len(services))
+					for _, service := range services {
+						instances = append(instances, &registry.ServiceInstance{
+							ID:       service.Service.ID,
+							Name:     service.Service.Service,
+							Address:  service.Service.Address,
+							Port:     service.Service.Port,
+							Tags:     service.Service.Tags,
+							Metadata: service.Service.Meta,
+						})
+					}
+
+					select {
+					case updates <- instances:
+					case <-ctx.Done():
+						return
+					}
+
+					lastIndex = meta.LastIndex
+				}
+			}
+		}
+	}()
+
+	return updates, nil
+}
+
+// Health returns the health status of a service instance.
+func (r *ConsulRegistry) Health(ctx context.Context, serviceID string) (*registry.HealthStatus, error) {
+	entries, _, err := r.client.Health().Service(serviceID, "", false, nil)
+	if err != nil {
+		return nil, fmt.Errorf("failed to get health for service %s: %w", serviceID, err)
+	}
+
+	if len(entries) == 0 {
+		return &registry.HealthStatus{
+			ServiceID: serviceID,
+			Status:    "unknown",
+			Message:   "service not found",
+		}, nil
+	}
+
+	// Check health status from service entry checks
+	status := "healthy"
+	message := "all checks passing"
+
+	// Get the first entry (should be the service instance)
+	entry := entries[0]
+	for _, check := range entry.Checks {
+		if check.Status == consulapi.HealthCritical {
+			status = "critical"
+			message = check.Output
+			break
+		} else if check.Status == consulapi.HealthWarning {
+			status = "unhealthy"
+			message = check.Output
+		}
+	}
+
+	return &registry.HealthStatus{
+		ServiceID: serviceID,
+		Status:    status,
+		Message:   message,
+	}, nil
+}

pkg/registry/registry.go

@@ -0,0 +1,41 @@
+// Package registry provides service registry interface for service discovery.
+package registry
+
+import (
+	"context"
+)
+
+// ServiceRegistry is the interface for service discovery and registration.
+type ServiceRegistry interface {
+	// Register registers a service instance with the registry.
+	Register(ctx context.Context, service *ServiceInstance) error
+
+	// Deregister removes a service instance from the registry.
+	Deregister(ctx context.Context, serviceID string) error
+
+	// Discover returns all healthy instances of a service.
+	Discover(ctx context.Context, serviceName string) ([]*ServiceInstance, error)
+
+	// Watch returns a channel that receives updates when service instances change.
+	Watch(ctx context.Context, serviceName string) (<-chan []*ServiceInstance, error)
+
+	// Health returns the health status of a service instance.
+	Health(ctx context.Context, serviceID string) (*HealthStatus, error)
+}
+
+// ServiceInstance represents a service instance in the registry.
+type ServiceInstance struct {
+	ID       string            // Unique instance ID
+	Name     string            // Service name (e.g., "auth-service", "identity-service")
+	Address  string            // Service address (IP or hostname)
+	Port     int               // Service port
+	Tags     []string          // Service tags for filtering
+	Metadata map[string]string // Additional metadata
+}
+
+// HealthStatus represents the health status of a service instance.
+type HealthStatus struct {
+	ServiceID string // Service instance ID
+	Status    string // Health status: "healthy", "unhealthy", "critical"
+	Message   string // Optional status message
+}

pkg/services/audit.go

@@ -0,0 +1,39 @@
+// Package services provides service client interfaces for inter-service communication.
+package services
+
+import (
+	"context"
+)
+
+// AuditServiceClient is the interface for communicating with the Audit Service.
+type AuditServiceClient interface {
+	// Record records an audit log entry.
+	Record(ctx context.Context, entry *AuditLogEntry) error
+
+	// Query queries audit logs based on filters.
+	Query(ctx context.Context, filters *AuditLogFilters) ([]AuditLogEntry, error)
+}
+
+// AuditLogEntry represents an audit log entry.
+type AuditLogEntry struct {
+	UserID     string            `json:"user_id"`
+	Action     string            `json:"action"`   // e.g., "user.create", "user.update"
+	Resource   string            `json:"resource"` // e.g., "user", "role"
+	ResourceID string            `json:"resource_id"`
+	IPAddress  string            `json:"ip_address"`
+	UserAgent  string            `json:"user_agent"`
+	Metadata   map[string]string `json:"metadata"`
+	Timestamp  int64             `json:"timestamp"`
+}
+
+// AuditLogFilters contains filters for querying audit logs.
+type AuditLogFilters struct {
+	UserID     *string `json:"user_id,omitempty"`
+	Action     *string `json:"action,omitempty"`
+	Resource   *string `json:"resource,omitempty"`
+	ResourceID *string `json:"resource_id,omitempty"`
+	StartTime  *int64  `json:"start_time,omitempty"`
+	EndTime    *int64  `json:"end_time,omitempty"`
+	Limit      int     `json:"limit"`  // Max number of results
+	Offset     int     `json:"offset"` // Pagination offset
+}

pkg/services/auth.go

@@ -0,0 +1,37 @@
+// Package services provides service client interfaces for inter-service communication.
+package services
+
+import (
+	"context"
+)
+
+// AuthServiceClient is the interface for communicating with the Auth Service.
+type AuthServiceClient interface {
+	// Login authenticates a user and returns access and refresh tokens.
+	Login(ctx context.Context, email, password string) (*TokenResponse, error)
+
+	// RefreshToken refreshes an access token using a refresh token.
+	RefreshToken(ctx context.Context, refreshToken string) (*TokenResponse, error)
+
+	// ValidateToken validates a JWT token and returns the token claims.
+	ValidateToken(ctx context.Context, token string) (*TokenClaims, error)
+
+	// Logout invalidates a refresh token.
+	Logout(ctx context.Context, refreshToken string) error
+}
+
+// TokenResponse contains the authentication tokens.
+type TokenResponse struct {
+	AccessToken  string `json:"access_token"`
+	RefreshToken string `json:"refresh_token"`
+	ExpiresIn    int64  `json:"expires_in"` // seconds
+	TokenType    string `json:"token_type"` // "Bearer"
+}
+
+// TokenClaims contains the claims from a validated JWT token.
+type TokenClaims struct {
+	UserID    string   `json:"user_id"`
+	Email     string   `json:"email"`
+	Roles     []string `json:"roles"`
+	ExpiresAt int64    `json:"expires_at"`
+}

pkg/services/authz.go

@@ -0,0 +1,37 @@
+// Package services provides service client interfaces for inter-service communication.
+package services
+
+import (
+	"context"
+)
+
+// AuthzServiceClient is the interface for communicating with the Authz Service.
+type AuthzServiceClient interface {
+	// Authorize checks if a user has a specific permission and returns an error if not.
+	Authorize(ctx context.Context, userID, permission string) error
+
+	// HasPermission checks if a user has a specific permission.
+	HasPermission(ctx context.Context, userID, permission string) (bool, error)
+
+	// GetUserPermissions returns all permissions for a user.
+	GetUserPermissions(ctx context.Context, userID string) ([]Permission, error)
+
+	// GetUserRoles returns all roles for a user.
+	GetUserRoles(ctx context.Context, userID string) ([]Role, error)
+}
+
+// Permission represents a permission in the system.
+type Permission struct {
+	ID          string `json:"id"`
+	Code        string `json:"code"`
+	Name        string `json:"name"`
+	Description string `json:"description"`
+}
+
+// Role represents a role in the system.
+type Role struct {
+	ID          string   `json:"id"`
+	Name        string   `json:"name"`
+	Description string   `json:"description"`
+	Permissions []string `json:"permissions"` // Permission codes
+}

pkg/services/identity.go

@@ -0,0 +1,62 @@
+// Package services provides service client interfaces for inter-service communication.
+package services
+
+import (
+	"context"
+)
+
+// IdentityServiceClient is the interface for communicating with the Identity Service.
+type IdentityServiceClient interface {
+	// GetUser retrieves a user by ID.
+	GetUser(ctx context.Context, id string) (*User, error)
+
+	// GetUserByEmail retrieves a user by email address.
+	GetUserByEmail(ctx context.Context, email string) (*User, error)
+
+	// CreateUser creates a new user.
+	CreateUser(ctx context.Context, user *CreateUserRequest) (*User, error)
+
+	// UpdateUser updates an existing user.
+	UpdateUser(ctx context.Context, id string, user *UpdateUserRequest) (*User, error)
+
+	// DeleteUser deletes a user.
+	DeleteUser(ctx context.Context, id string) error
+
+	// VerifyEmail verifies a user's email address using a verification token.
+	VerifyEmail(ctx context.Context, token string) error
+
+	// RequestPasswordReset requests a password reset token.
+	RequestPasswordReset(ctx context.Context, email string) error
+
+	// ResetPassword resets a user's password using a reset token.
+	ResetPassword(ctx context.Context, token, newPassword string) error
+}
+
+// User represents a user in the system.
+type User struct {
+	ID            string `json:"id"`
+	Email         string `json:"email"`
+	Username      string `json:"username"`
+	FirstName     string `json:"first_name"`
+	LastName      string `json:"last_name"`
+	EmailVerified bool   `json:"email_verified"`
+	CreatedAt     int64  `json:"created_at"`
+	UpdatedAt     int64  `json:"updated_at"`
+}
+
+// CreateUserRequest contains the data needed to create a new user.
+type CreateUserRequest struct {
+	Email     string `json:"email"`
+	Username  string `json:"username"`
+	Password  string `json:"password"`
+	FirstName string `json:"first_name"`
+	LastName  string `json:"last_name"`
+}
+
+// UpdateUserRequest contains the data needed to update a user.
+type UpdateUserRequest struct {
+	Email     *string `json:"email,omitempty"`
+	Username  *string `json:"username,omitempty"`
+	FirstName *string `json:"first_name,omitempty"`
+	LastName  *string `json:"last_name,omitempty"`
+}

services/gateway/gateway.go

@@ -0,0 +1,127 @@
+// Package gateway provides API Gateway implementation.
+package gateway
+
+import (
+	"fmt"
+	"net/http"
+	"net/http/httputil"
+	"net/url"
+
+	"git.dcentral.systems/toolz/goplt/internal/client"
+	"git.dcentral.systems/toolz/goplt/pkg/config"
+	"git.dcentral.systems/toolz/goplt/pkg/logger"
+	"git.dcentral.systems/toolz/goplt/pkg/registry"
+	"github.com/gin-gonic/gin"
+)
+
+// Gateway handles routing requests to backend services.
+type Gateway struct {
+	config        config.ConfigProvider
+	log           logger.Logger
+	clientFactory *client.ServiceClientFactory
+	registry      registry.ServiceRegistry
+	routes        []RouteConfig
+}
+
+// RouteConfig defines a route configuration.
+type RouteConfig struct {
+	Path         string
+	Service      string
+	AuthRequired bool
+}
+
+// NewGateway creates a new API Gateway instance.
+func NewGateway(
+	cfg config.ConfigProvider,
+	log logger.Logger,
+	clientFactory *client.ServiceClientFactory,
+	reg registry.ServiceRegistry,
+) (*Gateway, error) {
+	// Load route configurations
+	routes := loadRoutes(cfg)
+
+	return &Gateway{
+		config:        cfg,
+		log:           log,
+		clientFactory: clientFactory,
+		registry:      reg,
+		routes:        routes,
+	}, nil
+}
+
+// SetupRoutes configures routes on the Gin router.
+func (g *Gateway) SetupRoutes(router *gin.Engine) {
+	// Setup route handlers
+	for _, route := range g.routes {
+		route := route // Capture for closure
+		router.Any(route.Path, g.handleRoute(route))
+	}
+
+	// Default handler for unmatched routes
+	router.NoRoute(func(c *gin.Context) {
+		c.JSON(http.StatusNotFound, gin.H{
+			"error": "Route not found",
+			"path":  c.Request.URL.Path,
+		})
+	})
+}
+
+// handleRoute returns a handler function for a route.
+func (g *Gateway) handleRoute(route RouteConfig) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		// TODO: Add authentication middleware if auth_required is true
+		// TODO: Add rate limiting middleware
+		// TODO: Add CORS middleware
+
+		// Discover service instances
+		ctx := c.Request.Context()
+		instances, err := g.registry.Discover(ctx, route.Service)
+		if err != nil {
+			g.log.Error("Failed to discover service",
+				logger.String("service", route.Service),
+				logger.Error(err),
+			)
+			c.JSON(http.StatusServiceUnavailable, gin.H{
+				"error": "Service unavailable",
+			})
+			return
+		}
+
+		if len(instances) == 0 {
+			g.log.Warn("No instances found for service",
+				logger.String("service", route.Service),
+			)
+			c.JSON(http.StatusServiceUnavailable, gin.H{
+				"error": "Service unavailable",
+			})
+			return
+		}
+
+		// Use first healthy instance (load balancing can be added later)
+		instance := instances[0]
+		targetURL := fmt.Sprintf("http://%s:%d", instance.Address, instance.Port)
+
+		// Create reverse proxy
+		target, err := url.Parse(targetURL)
+		if err != nil {
+			g.log.Error("Failed to parse target URL",
+				logger.String("url", targetURL),
+				logger.Error(err),
+			)
+			c.JSON(http.StatusInternalServerError, gin.H{
+				"error": "Internal server error",
+			})
+			return
+		}
+
+		proxy := httputil.NewSingleHostReverseProxy(target)
+		proxy.ServeHTTP(c.Writer, c.Request)
+	}
+}
+
+// loadRoutes loads route configurations from config.
+func loadRoutes(cfg config.ConfigProvider) []RouteConfig {
+	// For now, return empty routes - will be loaded from config in future
+	// This is a placeholder implementation
+	return []RouteConfig{}
+}

services/gateway/gateway_test.go

@@ -0,0 +1,426 @@
+package gateway
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"testing"
+	"time"
+
+	"git.dcentral.systems/toolz/goplt/internal/client"
+	"git.dcentral.systems/toolz/goplt/pkg/config"
+	"git.dcentral.systems/toolz/goplt/pkg/logger"
+	"git.dcentral.systems/toolz/goplt/pkg/registry"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestMain sets up the test environment before running tests.
+func TestMain(m *testing.M) {
+	// Set Gin to test mode once for all tests to avoid race conditions
+	gin.SetMode(gin.TestMode)
+	// Run tests
+	os.Exit(m.Run())
+}
+
+func TestNewGateway(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name    string
+		cfg     config.ConfigProvider
+		log     logger.Logger
+		factory *client.ServiceClientFactory
+		reg     registry.ServiceRegistry
+		wantErr bool
+	}{
+		{
+			name:    "successful creation",
+			cfg:     &mockConfigProvider{},
+			log:     &mockLogger{},
+			factory: &client.ServiceClientFactory{},
+			reg:     &mockServiceRegistry{},
+			wantErr: false,
+		},
+		{
+			name:    "nil config",
+			cfg:     nil,
+			log:     &mockLogger{},
+			factory: &client.ServiceClientFactory{},
+			reg:     &mockServiceRegistry{},
+			wantErr: false, // NewGateway doesn't validate nil config currently
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			gateway, err := NewGateway(tt.cfg, tt.log, tt.factory, tt.reg)
+			if tt.wantErr {
+				require.Error(t, err)
+				assert.Nil(t, gateway)
+			} else {
+				require.NoError(t, err)
+				require.NotNil(t, gateway)
+				assert.Equal(t, tt.cfg, gateway.config)
+				assert.Equal(t, tt.log, gateway.log)
+				assert.Equal(t, tt.factory, gateway.clientFactory)
+				assert.Equal(t, tt.reg, gateway.registry)
+			}
+		})
+	}
+}
+
+func TestGateway_SetupRoutes(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name           string
+		routes         []RouteConfig
+		requestPath    string
+		expectedStatus int
+	}{
+		{
+			name: "route configured",
+			routes: []RouteConfig{
+				{Path: "/api/v1/test", Service: "test-service", AuthRequired: false},
+			},
+			requestPath:    "/api/v1/test",
+			expectedStatus: http.StatusServiceUnavailable, // Will fail service discovery
+		},
+		{
+			name:           "no routes configured",
+			routes:         []RouteConfig{},
+			requestPath:    "/api/v1/test",
+			expectedStatus: http.StatusNotFound, // NoRoute handler
+		},
+		{
+			name: "unmatched route",
+			routes: []RouteConfig{
+				{Path: "/api/v1/test", Service: "test-service", AuthRequired: false},
+			},
+			requestPath:    "/api/v1/other",
+			expectedStatus: http.StatusNotFound, // NoRoute handler
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			gateway := &Gateway{
+				config:        &mockConfigProvider{},
+				log:           &mockLogger{},
+				clientFactory: &client.ServiceClientFactory{},
+				registry:      &mockServiceRegistry{},
+				routes:        tt.routes,
+			}
+
+			router := gin.New()
+			gateway.SetupRoutes(router)
+
+			req := httptest.NewRequest(http.MethodGet, tt.requestPath, nil)
+			w := httptest.NewRecorder()
+			router.ServeHTTP(w, req)
+
+			assert.Equal(t, tt.expectedStatus, w.Code)
+		})
+	}
+}
+
+func TestGateway_handleRoute(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name           string
+		route          RouteConfig
+		registrySetup  func() *mockServiceRegistry
+		requestPath    string
+		expectedStatus int
+	}{
+		{
+			name: "service discovery failure",
+			route: RouteConfig{
+				Path:    "/api/v1/test",
+				Service: "test-service",
+			},
+			registrySetup: func() *mockServiceRegistry {
+				return &mockServiceRegistry{
+					discoverError: errors.New("service discovery failed"),
+				}
+			},
+			requestPath:    "/api/v1/test",
+			expectedStatus: http.StatusServiceUnavailable,
+		},
+		{
+			name: "no service instances",
+			route: RouteConfig{
+				Path:    "/api/v1/test",
+				Service: "test-service",
+			},
+			registrySetup: func() *mockServiceRegistry {
+				return &mockServiceRegistry{
+					instances: []*registry.ServiceInstance{},
+				}
+			},
+			requestPath:    "/api/v1/test",
+			expectedStatus: http.StatusServiceUnavailable,
+		},
+		// Note: Testing invalid target URL and proxy forwarding requires integration tests
+		// with real HTTP servers, as httptest.ResponseRecorder doesn't support CloseNotify
+		// which is required by the reverse proxy.
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			mockReg := tt.registrySetup()
+			gateway := &Gateway{
+				config:        &mockConfigProvider{},
+				log:           &mockLogger{},
+				clientFactory: &client.ServiceClientFactory{},
+				registry:      mockReg,
+				routes:        []RouteConfig{tt.route},
+			}
+
+			router := gin.New()
+			gateway.SetupRoutes(router)
+
+			req := httptest.NewRequest(http.MethodGet, tt.requestPath, nil)
+			w := httptest.NewRecorder()
+			router.ServeHTTP(w, req)
+
+			assert.Equal(t, tt.expectedStatus, w.Code)
+		})
+	}
+}
+
+// Note: Proxy forwarding tests should be in integration tests with testcontainers.
+// The reverse proxy requires a real HTTP connection which httptest.ResponseRecorder
+// cannot provide due to missing CloseNotify interface.
+
+func TestGateway_handleRoute_AllMethods(t *testing.T) {
+	t.Parallel()
+
+	methods := []string{
+		http.MethodGet,
+		http.MethodPost,
+		http.MethodPut,
+		http.MethodDelete,
+		http.MethodPatch,
+		http.MethodOptions,
+		http.MethodHead,
+	}
+
+	// Use a registry that will fail discovery to avoid proxy forwarding issues
+	mockReg := &mockServiceRegistry{
+		instances: []*registry.ServiceInstance{}, // Empty to trigger service unavailable
+	}
+
+	gateway := &Gateway{
+		config:        &mockConfigProvider{},
+		log:           &mockLogger{},
+		clientFactory: &client.ServiceClientFactory{},
+		registry:      mockReg,
+		routes: []RouteConfig{
+			{Path: "/api/v1/test", Service: "test-service"},
+		},
+	}
+
+	router := gin.New()
+	gateway.SetupRoutes(router)
+
+	for _, method := range methods {
+		t.Run(method, func(t *testing.T) {
+			req := httptest.NewRequest(method, "/api/v1/test", nil)
+			w := httptest.NewRecorder()
+			router.ServeHTTP(w, req)
+
+			// All methods should be handled (route should match, even if service unavailable)
+			assert.NotEqual(t, http.StatusNotFound, w.Code, "Route should match for %s", method)
+		})
+	}
+}
+
+func TestLoadRoutes(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name string
+		cfg  config.ConfigProvider
+	}{
+		{
+			name: "empty config",
+			cfg:  &mockConfigProvider{},
+		},
+		{
+			name: "nil config",
+			cfg:  nil,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			routes := loadRoutes(tt.cfg)
+			// Currently loadRoutes returns empty slice
+			// This test ensures it doesn't panic
+			assert.NotNil(t, routes)
+		})
+	}
+}
+
+func TestGateway_NoRoute(t *testing.T) {
+	t.Parallel()
+
+	gateway := &Gateway{
+		config:        &mockConfigProvider{},
+		log:           &mockLogger{},
+		clientFactory: &client.ServiceClientFactory{},
+		registry:      &mockServiceRegistry{},
+		routes:        []RouteConfig{},
+	}
+
+	router := gin.New()
+	gateway.SetupRoutes(router)
+
+	req := httptest.NewRequest(http.MethodGet, "/unknown/path", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusNotFound, w.Code)
+
+	var response map[string]interface{}
+	err := json.Unmarshal(w.Body.Bytes(), &response)
+	require.NoError(t, err)
+	assert.Equal(t, "Route not found", response["error"])
+	assert.Equal(t, "/unknown/path", response["path"])
+}
+
+// mockConfigProvider implements config.ConfigProvider for testing.
+type mockConfigProvider struct {
+	values map[string]any
+}
+
+func (m *mockConfigProvider) Get(key string) any {
+	if m.values == nil {
+		return nil
+	}
+	return m.values[key]
+}
+
+func (m *mockConfigProvider) GetString(key string) string {
+	if m.values == nil {
+		return ""
+	}
+	if val, ok := m.values[key].(string); ok {
+		return val
+	}
+	return ""
+}
+
+func (m *mockConfigProvider) GetInt(key string) int {
+	if m.values == nil {
+		return 0
+	}
+	if val, ok := m.values[key].(int); ok {
+		return val
+	}
+	return 0
+}
+
+func (m *mockConfigProvider) GetBool(key string) bool {
+	if m.values == nil {
+		return false
+	}
+	if val, ok := m.values[key].(bool); ok {
+		return val
+	}
+	return false
+}
+
+func (m *mockConfigProvider) GetDuration(key string) time.Duration {
+	return 0
+}
+
+func (m *mockConfigProvider) GetStringSlice(key string) []string {
+	if m.values == nil {
+		return nil
+	}
+	if val, ok := m.values[key].([]string); ok {
+		return val
+	}
+	return nil
+}
+
+func (m *mockConfigProvider) IsSet(key string) bool {
+	if m.values == nil {
+		return false
+	}
+	_, ok := m.values[key]
+	return ok
+}
+
+func (m *mockConfigProvider) Unmarshal(v any) error {
+	return nil
+}
+
+// mockLogger implements logger.Logger for testing.
+type mockLogger struct {
+	infoLogs  []string
+	errorLogs []string
+	warnLogs  []string
+}
+
+func (m *mockLogger) Debug(msg string, fields ...logger.Field) {}
+func (m *mockLogger) Info(msg string, fields ...logger.Field) {
+	m.infoLogs = append(m.infoLogs, msg)
+}
+func (m *mockLogger) Warn(msg string, fields ...logger.Field) {
+	m.warnLogs = append(m.warnLogs, msg)
+}
+func (m *mockLogger) Error(msg string, fields ...logger.Field) {
+	m.errorLogs = append(m.errorLogs, msg)
+}
+func (m *mockLogger) With(fields ...logger.Field) logger.Logger {
+	return m
+}
+func (m *mockLogger) WithContext(ctx context.Context) logger.Logger {
+	return m
+}
+
+// mockServiceRegistry implements registry.ServiceRegistry for testing.
+type mockServiceRegistry struct {
+	instances     []*registry.ServiceInstance
+	discoverError error
+	registerError error
+	deregError    error
+}
+
+func (m *mockServiceRegistry) Register(ctx context.Context, service *registry.ServiceInstance) error {
+	return m.registerError
+}
+
+func (m *mockServiceRegistry) Deregister(ctx context.Context, serviceID string) error {
+	return m.deregError
+}
+
+func (m *mockServiceRegistry) Discover(ctx context.Context, serviceName string) ([]*registry.ServiceInstance, error) {
+	if m.discoverError != nil {
+		return nil, m.discoverError
+	}
+	return m.instances, nil
+}
+
+func (m *mockServiceRegistry) Watch(ctx context.Context, serviceName string) (<-chan []*registry.ServiceInstance, error) {
+	ch := make(chan []*registry.ServiceInstance, 1)
+	ch <- m.instances
+	close(ch)
+	return ch, nil
+}
+
+func (m *mockServiceRegistry) Health(ctx context.Context, serviceID string) (*registry.HealthStatus, error) {
+	return &registry.HealthStatus{
+		ServiceID: serviceID,
+		Status:    "healthy",
+	}, nil
+}