feat: reword phase to epic, update mkdocs

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

@@ -0,0 +1,150 @@
+# Story 5.7: gRPC Service Definitions and Clients
+
+## Metadata
+- **Story ID**: 5.7
+- **Title**: gRPC Service Definitions and Clients
+- **Epic**: 5 - Infrastructure Adapters
+- **Status**: Pending
+- **Priority**: Medium
+- **Estimated Time**: 8-10 hours
+- **Dependencies**: 1.7, 3.5
+
+## Goal
+Implement gRPC service definitions and clients to enable microservices communication, allowing modules to be extracted as independent services.
+
+## 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.
+
+## Deliverables
+
+### 1. gRPC Service Definitions (`api/proto/`)
+- Define Protocol Buffer files for core services:
+  - `identity.proto` - Identity service
+  - `auth.proto` - Authentication service
+  - `authz.proto` - Authorization service
+  - `permission.proto` - Permission service
+  - `audit.proto` - Audit service
+- Use protobuf v3
+- Include proper message definitions
+- Include service definitions
+
+### 2. gRPC Server Implementations (`internal/services/grpc/server/`)
+- Implement gRPC servers for each service:
+  - `identity_server.go` - Identity gRPC server
+  - `auth_server.go` - Auth gRPC server
+  - `authz_server.go` - Authz gRPC server
+- Server implementations wrap existing services
+- Error handling and validation
+- Request/response conversion
+
+### 3. gRPC Client Implementations (`internal/services/grpc/client/`)
+- Implement gRPC clients that satisfy service client interfaces:
+  - `grpc_identity_client.go` - Identity gRPC client
+  - `grpc_auth_client.go` - Auth gRPC client
+  - `grpc_authz_client.go` - Authz gRPC client
+- Connection pooling
+- Retry logic
+- Circuit breaker support
+- Timeout handling
+
+### 4. gRPC Server Setup
+- gRPC server initialization
+- Service registration
+- Health check service
+- Reflection service (development)
+- Integration with HTTP server (gRPC-Gateway optional)
+
+### 5. Code Generation
+- `Makefile` target for protobuf generation
+- Generate Go code from `.proto` files
+- Generate gRPC server and client stubs
+
+### 6. Configuration
+- 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**
+   ```bash
+   go get google.golang.org/grpc
+   go get google.golang.org/protobuf
+   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**
+   - Create `api/proto/` directory
+   - Define `.proto` files for each service
+   - Define messages and services
+
+3. **Generate gRPC Code**
+   - Create `Makefile` target
+   - Generate Go code from protobuf
+
+4. **Implement gRPC Servers**
+   - Create server implementations
+   - Wrap existing services
+   - Handle errors and validation
+
+5. **Implement gRPC Clients**
+   - Create client implementations
+   - Implement service client interfaces
+   - 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
+- [ ] gRPC servers are implemented
+- [ ] gRPC clients implement service interfaces
+- [ ] Service factory can create gRPC clients
+- [ ] gRPC services can be enabled via configuration
+- [ ] Code generation works
+- [ ] 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)
+
+## Implementation Notes
+- Use protobuf v3
+- Support both unary and streaming RPCs
+- Implement proper error handling
+- Add OpenTelemetry instrumentation
+- Support service versioning
+
+## Testing
+```bash
+# Generate protobuf code
+make generate-proto
+
+# Test gRPC servers
+go test ./internal/services/grpc/server/...
+
+# Test gRPC clients
+go test ./internal/services/grpc/client/...
+```
+
+## Files to Create/Modify
+- `api/proto/identity.proto` - Identity service definition
+- `api/proto/auth.proto` - Auth service definition
+- `api/proto/authz.proto` - Authz service definition
+- `internal/services/grpc/server/` - gRPC server implementations
+- `internal/services/grpc/client/` - gRPC client implementations
+- `internal/services/factory.go` - Add gRPC client support
+- `Makefile` - Add protobuf generation
+- `config/default.yaml` - Add gRPC configuration
+