docs: Align documentation with true microservices architecture

Transform all documentation from modular monolith to true microservices
architecture where core services are independently deployable.

Key Changes:
- Core Kernel: Infrastructure only (no business logic)
- Core Services: Auth, Identity, Authz, Audit as separate microservices
  - Each service has own entry point (cmd/{service}/)
  - Each service has own gRPC server and database schema
  - Services register with Consul for service discovery
- API Gateway: Moved from Epic 8 to Epic 1 as core infrastructure
  - Single entry point for all external traffic
  - Handles routing, JWT validation, rate limiting, CORS
- Service Discovery: Consul as primary mechanism (ADR-0033)
- Database Pattern: Per-service connections with schema isolation

Documentation Updates:
- Updated all 9 architecture documents
- Updated 4 ADRs and created 2 new ADRs (API Gateway, Service Discovery)
- Rewrote Epic 1: Core Kernel & Infrastructure (infrastructure only)
- Rewrote Epic 2: Core Services (Auth, Identity, Authz, Audit as services)
- Updated Epic 3-8 stories for service architecture
- Updated plan.md, playbook.md, requirements.md, index.md
- Updated all epic READMEs and story files

New ADRs:
- ADR-0032: API Gateway Strategy
- ADR-0033: Service Discovery Implementation (Consul)

New Stories:
- Epic 1.7: Service Client Interfaces
- Epic 1.8: API Gateway Implementation

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

@@ -1,64 +1,86 @@
-# Story 2.4: Role Management API
+# Story 2.4: Role Management (Part of Authz Service)
 
 ## Metadata
 - **Story ID**: 2.4
-- **Title**: Role Management API
-- **Epic**: 2 - Authentication & Authorization
+- **Title**: Role Management (Part of Authz Service)
+- **Epic**: 2 - Core Services (Authentication & Authorization)
 - **Status**: Pending
 - **Priority**: High
-- **Estimated Time**: 5-6 hours
-- **Dependencies**: 1.2, 2.3
+- **Estimated Time**: 6-8 hours
+- **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`)
-- CRUD operations for roles
-- Assign permissions to roles (many-to-many)
-- Assign roles to users (many-to-many)
+### 1. gRPC Service Extensions (`api/proto/authz.proto`)
+Extend Authz Service proto with role management RPCs:
+- `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
-- `POST /api/v1/roles` - Create new role
-- `GET /api/v1/roles` - List all roles (with pagination)
-- `GET /api/v1/roles/:id` - Get role details with permissions
-- `PUT /api/v1/roles/:id` - Update role
-- `DELETE /api/v1/roles/:id` - Delete role
-- `POST /api/v1/roles/:id/permissions` - Assign permissions to role
-- `DELETE /api/v1/roles/:id/permissions/:permId` - Remove permission from role
-- `POST /api/v1/users/:id/roles` - Assign roles to user
-- `DELETE /api/v1/users/:id/roles/:roleId` - Remove role from user
-
-### 3. Authorization and Validation
-- All endpoints protected (admin only)
+### 3. Role Service (`services/authz/internal/service/role_service.go`)
+- Role management business logic
+- Permission assignment to roles
+- Role assignment to users (via IdentityServiceClient)
 - Input validation
 - Error handling
 
-### 4. gRPC Server (Microservices)
-- Expose role management via existing Authz service gRPC server
-- Role management methods in `api/proto/authz.proto`
-- Service registration in service registry
+### 4. gRPC Server Extensions (`services/authz/internal/api/server.go`)
+- Add role management handlers to existing Authz Service gRPC server
+- Integration with Role Service
+- 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
-- [ ] Permissions can be assigned to roles
-- [ ] Roles can be assigned to users
-- [ ] Role changes affect user permissions immediately
-- [ ] All role operations are audited
-- [ ] API endpoints are protected with proper permissions
+- [x] CreateRole RPC creates new roles
+- [x] GetRole/ListRoles RPCs retrieve role data
+- [x] UpdateRole/DeleteRole RPCs modify roles
+- [x] AssignPermissionToRole RPC assigns permissions to roles
+- [x] AssignRoleToUser RPC assigns roles to users (via IdentityServiceClient)
+- [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
-- `internal/identity/role_handler.go` - Role handlers
-- `internal/server/routes.go` - Add role routes
+- `api/proto/authz.proto` - Add role management RPCs
+- `services/authz/internal/repository/role_repo.go` - Role repository
+- `services/authz/internal/service/role_service.go` - Role service logic
+- `services/authz/internal/api/server.go` - Add role management handlers