toolz/goplt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Align documentation with true microservices architecture

Browse Source 
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
This commit is contained in:
0x1d
2025-11-06 08:47:27 +01:00
parent cab7cadf9e
commit 38a251968c
47 changed files with 3190 additions and 1613 deletions
Download Patch File Download Diff File Expand all files Collapse all files

138
docs/content/stories/epic2/2.2-identity-management.md
View File

@@ -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
- **Epic**: 2 - Authentication & Authorization
- **Title**: Identity Service - User Management
- **Epic**: 2 - Core Services (Authentication & Authorization)
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 8-10 hours
- **Dependencies**: 1.2, 2.1
- **Estimated Time**: 10-12 hours
- **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`)
- `UserRepository` interface for user data access
- `UserService` interface for user business logic
- User domain models
### 1. Service Entry Point (`cmd/identity-service/main.go`)
- Independent service entry point
- Bootstrap with core kernel services
- 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`)
- CRUD operations using Ent
- Password hashing (bcrypt or argon2)
- Email uniqueness validation
- User lookup by ID and email
- User search and pagination
### 2. gRPC Service Definition (`api/proto/identity.proto`)
- `CreateUserRequest` / `CreateUserResponse` - User registration
- `GetUserRequest` / `GetUserResponse` - Get user by ID
- `GetUserByEmailRequest` / `GetUserByEmailResponse` - Get user by email
- `UpdateUserRequest` / `UpdateUserResponse` - Update user profile
- `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
- `POST /api/v1/users` - Register new user
- `GET /api/v1/users/:id` - Get user profile (authorized)
- `PUT /api/v1/users/:id` - Update user profile (authorized)
- `DELETE /api/v1/users/:id` - Delete user (admin only)
- `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. User Repository (`services/identity/internal/repository/user_repo.go`)
- CRUD operations using Ent
- User lookup by ID and email
- User search and pagination
- Ent schema integration
### 5. gRPC Server (Microservices)
- Expose gRPC server for identity service
- gRPC service definition in `api/proto/identity.proto`
- gRPC server implementation in `internal/identity/grpc/server.go`
- Service registration in service registry
### 6. Database Connection and Schema (`services/identity/ent/schema/user.go`)
- Identity Service database connection (schema: `identity`)
- User entity schema:
- ID, email, password_hash, verified, created_at, updated_at
- Email verification token, password reset token
- Migration support
- Per-service connection pool
### 6. Integration
- Integration with email notification system (Epic 5 placeholder)
- Integration with audit logging
- Integration with authentication system
- Identity service is an independent service that can be deployed separately
### 7. Service Client Integration
- Uses `AuditServiceClient` to log user operations
- Service discovery via Consul
### 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
- [ ] Passwords are securely hashed
- [ ] Email verification tokens are generated and validated
- [ ] Password reset flow works end-to-end
- [ ] Users can update their profiles
- [ ] User operations require proper authentication
- [ ] All user actions are audited
- [ ] Email uniqueness is enforced
- [x] Identity Service is independently deployable
- [x] Service entry point exists at `cmd/identity-service/main.go`
- [x] Service registers with Consul on startup
- [x] gRPC server starts on configured port (8082)
- [x] CreateUser RPC registers new users with password hashing
- [x] GetUser/GetUserByEmail RPCs retrieve user data
- [x] UpdateUser RPC updates user profiles
- [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
- `internal/identity/user_repo.go` - User repository
- `internal/identity/user_service.go` - User service
- `internal/identity/handler.go` - User handlers
- `internal/di/providers.go` - Add identity providers
- `cmd/identity-service/main.go` - Service entry point
- `api/proto/identity.proto` - gRPC service definition
- `services/identity/internal/api/server.go` - gRPC server implementation
- `services/identity/internal/service/user_service.go` - User service logic
- `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