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
This commit is contained in:
@@ -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.2 Database Layer](./epic1/1.2-database-layer.md)
|
||||
- [1.1 Enhanced DI Container](./epic1/1.1-enhanced-di-container.md) - Core kernel services only
|
||||
- [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.6 OpenTelemetry](./epic1/1.6-opentelemetry.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) - 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
|
||||
- [2.1 JWT Authentication System](./epic2/2.1-jwt-authentication.md)
|
||||
- [2.2 Identity Management System](./epic2/2.2-identity-management.md)
|
||||
- [2.3 RBAC System](./epic2/2.3-rbac-system.md)
|
||||
- [2.4 Role Management API](./epic2/2.4-role-management.md)
|
||||
- [2.5 Audit Logging System](./epic2/2.5-audit-logging.md)
|
||||
- [2.6 Database Seeding and Initialization](./epic2/2.6-database-seeding.md)
|
||||
- [2.7 Service Client Interfaces](./epic2/2.7-service-abstraction-layer.md)
|
||||
## Epic 2: Core Services (Authentication & Authorization)
|
||||
- [2.1 Auth Service - JWT Authentication](./epic2/2.1-jwt-authentication.md) - Independent Auth Service
|
||||
- [2.2 Identity Service - User Management](./epic2/2.2-identity-management.md) - Independent Identity Service
|
||||
- [2.3 Authz Service - Authorization & RBAC](./epic2/2.3-rbac-system.md) - Independent Authz Service
|
||||
- [2.4 Role Management (Part of Authz Service)](./epic2/2.4-role-management.md) - Role management gRPC endpoints
|
||||
- [2.5 Audit Service - Audit Logging](./epic2/2.5-audit-logging.md) - Independent Audit Service
|
||||
- [2.6 Database Seeding](./epic2/2.6-database-seeding.md) - Per-service seeding
|
||||
- [Epic 2 Overview](./epic2/README.md)
|
||||
|
||||
## Epic 3: Module Framework
|
||||
- [3.1 Module System Interface](./epic3/3.1-module-system-interface.md)
|
||||
## Epic 3: Module Framework (Feature Services)
|
||||
- [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.4 Module CLI](./epic3/3.4-module-cli.md)
|
||||
- [3.5 Service Registry and Discovery](./epic3/3.5-service-registry.md)
|
||||
- [3.3 Service Loader](./epic3/3.3-module-loader.md) - Service initialization helpers
|
||||
- [3.4 Service Management CLI](./epic3/3.4-module-cli.md) - Service management CLI
|
||||
- [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)
|
||||
- [4.1 Complete Blog Module](./epic4/4.1-blog-module.md)
|
||||
## Epic 4: Sample Feature Service (Blog Service)
|
||||
- [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,10 +76,12 @@ 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:
|
||||
|
||||
@@ -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 Tasks](./epic2/README.md) - All Epic 2 tasks
|
||||
### Epic 2: Core Services (Authentication & Authorization)
|
||||
- [Epic 2 Tasks](./epic2/README.md) - Auth, Identity, Authz, Audit as independent services
|
||||
|
||||
### Epic 3: Module Framework
|
||||
- [Epic 3 Tasks](./epic3/README.md) - All Epic 3 tasks
|
||||
### Epic 3: Module Framework (Feature Services)
|
||||
- [Epic 3 Tasks](./epic3/README.md) - Module framework for feature services
|
||||
|
||||
### Epic 4: Sample Feature Module (Blog)
|
||||
- [Epic 4 Tasks](./epic4/README.md) - All Epic 4 tasks
|
||||
### Epic 4: Sample Feature Service (Blog Service)
|
||||
- [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
|
||||
|
||||
@@ -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,16 @@ 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 +66,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)
|
||||
|
||||
@@ -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
|
||||
- Initialize Ent schema in `internal/ent/`
|
||||
- Set up code generation
|
||||
### 1. Database Client Foundation
|
||||
- Database client wrapper in `internal/infra/database/client.go`
|
||||
- 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/`)
|
||||
Define core entities:
|
||||
- **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
|
||||
### 2. Database Client Functions
|
||||
- `NewEntClient(dsn string, schema string) (*ent.Client, error)` - supports schema isolation
|
||||
- Connection pooling configuration:
|
||||
- Max connections
|
||||
- Max idle connections
|
||||
- Max connections per service
|
||||
- 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 pool settings
|
||||
- Connection string (DSN) - shared PostgreSQL instance
|
||||
- Connection pool settings per service
|
||||
- Schema isolation configuration
|
||||
- Migration settings
|
||||
- Driver configuration
|
||||
|
||||
### 6. DI Integration
|
||||
- Provider function for database client
|
||||
- Register in DI container
|
||||
- Lifecycle management (close on shutdown)
|
||||
### 4. Database Client Factory
|
||||
- Factory function for creating service-specific database clients
|
||||
- Each service manages its own connection pool
|
||||
- Support for multiple services connecting to same database instance with different schemas
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. **Install Ent**
|
||||
```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**
|
||||
1. **Create Database Client Wrapper**
|
||||
- Create `internal/infra/database/client.go`
|
||||
- Implement connection management
|
||||
- Add migration runner
|
||||
- Add health check
|
||||
- Implement `NewEntClient(dsn, schema)` function
|
||||
- Add connection pooling configuration
|
||||
- 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**
|
||||
- Create provider function
|
||||
- Register in container
|
||||
- Test connection
|
||||
3. **Create Database Client Factory**
|
||||
- Factory function for service-specific clients
|
||||
- Support for per-service connection pools
|
||||
- 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
|
||||
- [x] Core entities can be created and queried
|
||||
- [x] Migrations run successfully on startup
|
||||
- [x] Connection pooling is configured correctly
|
||||
- [x] Database client connects to PostgreSQL with schema support
|
||||
- [x] Connection pooling is configured correctly per service
|
||||
- [x] Database health check works
|
||||
- [x] All entities have proper indexes and relationships
|
||||
- [x] Database client is injectable via DI
|
||||
- [x] Multiple services can connect to same database instance with different schemas
|
||||
- [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,13 @@ go run cmd/platform/main.go
|
||||
```
|
||||
|
||||
## Files to Create/Modify
|
||||
- `internal/ent/schema/user.go` - User entity
|
||||
- `internal/ent/schema/role.go` - Role entity
|
||||
- `internal/ent/schema/permission.go` - Permission entity
|
||||
- `internal/ent/schema/audit_log.go` - AuditLog entity
|
||||
- `internal/ent/schema/role_permissions.go` - Relationship
|
||||
- `internal/ent/schema/user_roles.go` - Relationship
|
||||
- `internal/infra/database/client.go` - Database client
|
||||
- `internal/di/providers.go` - Add database provider
|
||||
- `config/default.yaml` - Add database config
|
||||
- `internal/infra/database/client.go` - Database client wrapper with schema support
|
||||
- `internal/infra/database/factory.go` - Database client factory for services
|
||||
- `config/default.yaml` - Add database config with schema isolation settings
|
||||
|
||||
**Note:** Entity schemas are created in Epic 2:
|
||||
- `services/identity/ent/schema/user.go` - User entity (Identity Service)
|
||||
- `services/authz/ent/schema/role.go` - Role entity (Authz Service)
|
||||
- `services/authz/ent/schema/permission.go` - Permission entity (Authz Service)
|
||||
- `services/audit/ent/schema/audit_log.go` - AuditLog entity (Audit Service)
|
||||
|
||||
|
||||
@@ -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`)
|
||||
- Gin router initialization
|
||||
### 1. HTTP Server Foundation (`internal/server/http.go`)
|
||||
- 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
|
||||
|
||||
### 3. Core Route Registration
|
||||
- `GET /healthz` - Liveness probe
|
||||
- `GET /ready` - Readiness probe
|
||||
- `GET /metrics` - Prometheus metrics
|
||||
- **Response Compression**: Gzip compression for responses (HTTP)
|
||||
|
||||
### 4. FX Lifecycle Integration
|
||||
- HTTP server starts on `OnStart` hook
|
||||
- Graceful shutdown on `OnStop` hook (drains connections)
|
||||
- Server lifecycle management helpers
|
||||
- Graceful shutdown support
|
||||
- Port configuration from config system
|
||||
- Reusable by services
|
||||
|
||||
### 5. Integration
|
||||
- Integration with main application entry point
|
||||
- Integration with all middleware systems
|
||||
**Note:** Services will use these foundations to create their own server instances in Epic 2.
|
||||
|
||||
## 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] CORS is configurable per environment
|
||||
- [x] All core endpoints work correctly
|
||||
- [x] Servers are configurable via config system
|
||||
- [x] Services can create their own server instances using these foundations
|
||||
|
||||
## 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/middleware.go` - Middleware functions
|
||||
- `internal/di/providers.go` - Add server provider
|
||||
- `internal/server/http.go` - HTTP server foundation
|
||||
- `internal/server/grpc.go` - gRPC server foundation
|
||||
- `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.
|
||||
|
||||
|
||||
147
docs/content/stories/epic1/1.7-service-client-interfaces.md
Normal file
147
docs/content/stories/epic1/1.7-service-client-interfaces.md
Normal file
@@ -0,0 +1,147 @@
|
||||
# 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
|
||||
|
||||
183
docs/content/stories/epic1/1.8-api-gateway.md
Normal file
183
docs/content/stories/epic1/1.8-api-gateway.md
Normal file
@@ -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
|
||||
|
||||
@@ -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.
|
||||
- **Deliverables:** Extended DI container, provider functions for all services, core module export
|
||||
- **Goal:** Extend the DI container to provide core kernel infrastructure services only (no business logic) with proper lifecycle management.
|
||||
- **Deliverables:** Extended DI container, provider functions for core kernel services only, core module export
|
||||
|
||||
### 1.2 Database Layer with Ent ORM
|
||||
- [Story: 1.2 - Database Layer](./1.2-database-layer.md)
|
||||
- **Goal:** Set up a complete database layer using Ent ORM with core domain entities, migrations, and connection management.
|
||||
- **Deliverables:** Ent schema, core entities, database client, migrations, connection pooling
|
||||
### 1.2 Database Client Foundation
|
||||
- [Story: 1.2 - Database Client Foundation](./1.2-database-layer.md)
|
||||
- **Goal:** Set up database client foundation for services. Each service will have its own database connection and schema.
|
||||
- **Deliverables:** Database client wrapper with schema support, connection pooling, per-service connection management
|
||||
|
||||
**Note:** Core domain entities (User, Role, Permission, AuditLog) are implemented in Epic 2 as part of their respective services.
|
||||
|
||||
### 1.3 Health Monitoring and Metrics System
|
||||
- [Story: 1.3 - Health & Metrics](./1.3-health-metrics-system.md)
|
||||
@@ -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
|
||||
- [Story: 1.5 - HTTP Server](./1.5-http-server.md)
|
||||
- **Goal:** Create a production-ready HTTP server with comprehensive middleware for security, observability, and error handling.
|
||||
- **Deliverables:** HTTP server, comprehensive middleware stack, core routes, FX lifecycle integration
|
||||
### 1.5 HTTP/gRPC Server Foundation
|
||||
- [Story: 1.5 - HTTP/gRPC Server Foundation](./1.5-http-server.md)
|
||||
- **Goal:** Create HTTP and gRPC server foundation that services can use. Each service will have its own server instance.
|
||||
- **Deliverables:** HTTP server foundation, gRPC server foundation, common middleware, lifecycle management
|
||||
|
||||
### 1.6 OpenTelemetry Distributed Tracing
|
||||
- [Story: 1.6 - OpenTelemetry](./1.6-opentelemetry.md)
|
||||
- **Goal:** Integrate OpenTelemetry for distributed tracing across the platform to enable observability in production.
|
||||
- **Deliverables:** OpenTelemetry setup, HTTP instrumentation, database instrumentation, trace-log correlation
|
||||
- **Goal:** Integrate OpenTelemetry for distributed tracing across all services to enable observability in production.
|
||||
- **Deliverables:** OpenTelemetry setup, HTTP instrumentation, gRPC instrumentation, database instrumentation, trace-log correlation
|
||||
|
||||
### 1.7 Service Client Interfaces
|
||||
- [Story: 1.7 - Service Client Interfaces](./1.7-service-client-interfaces.md)
|
||||
- **Goal:** Create service client interfaces for all core services to enable microservices communication.
|
||||
- **Deliverables:** Service client interfaces in `pkg/services/`, service client factory, gRPC/HTTP client implementations
|
||||
|
||||
### 1.8 API Gateway Implementation
|
||||
- [Story: 1.8 - API Gateway](./1.8-api-gateway.md)
|
||||
- **Goal:** Implement API Gateway as core infrastructure component that routes all external traffic to backend services.
|
||||
- **Deliverables:** API Gateway service entry point, gateway implementation with routing, JWT validation, rate limiting, service discovery integration
|
||||
|
||||
## Deliverables Checklist
|
||||
- [x] DI container with all core services
|
||||
- [x] Database client with Ent schema
|
||||
- [x] DI container with core kernel services only (no business logic)
|
||||
- [x] Database client foundation (per-service connections)
|
||||
- [x] Health and metrics endpoints functional
|
||||
- [x] Error bus captures and logs errors
|
||||
- [x] HTTP 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 /ready` checks DB connectivity
|
||||
- `GET /healthz` returns 200 for all services
|
||||
- `GET /ready` checks service health
|
||||
- `GET /metrics` exposes Prometheus metrics
|
||||
- Panic recovery logs errors via error bus
|
||||
- Database migrations run on startup
|
||||
- HTTP requests are traced with OpenTelemetry
|
||||
- HTTP/gRPC requests are traced with OpenTelemetry
|
||||
- API Gateway routes requests to backend services
|
||||
- Service client interfaces are defined
|
||||
- Services can register with Consul
|
||||
- No business logic services in Epic 1
|
||||
|
||||
## Implementation Summary
|
||||
|
||||
|
||||
@@ -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
|
||||
- **Epic**: 2 - Authentication & Authorization
|
||||
- **Title**: Auth Service - JWT Authentication
|
||||
- **Epic**: 2 - Core Services (Authentication & Authorization)
|
||||
- **Status**: Pending
|
||||
- **Priority**: High
|
||||
- **Estimated Time**: 6-8 hours
|
||||
- **Dependencies**: 1.2, 1.5
|
||||
- **Estimated Time**: 8-10 hours
|
||||
- **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`)
|
||||
- `Authenticator` interface for token generation and verification
|
||||
- `TokenClaims` struct with user ID, roles, tenant ID, expiration
|
||||
- Token validation utilities
|
||||
### 1. Service Entry Point (`cmd/auth-service/main.go`)
|
||||
- Independent service entry point
|
||||
- Bootstrap with core kernel services
|
||||
- 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`)
|
||||
- Generate short-lived access tokens (15 minutes default)
|
||||
- Generate long-lived refresh tokens (7 days default)
|
||||
- Token signature verification using HMAC or RSA
|
||||
### 2. gRPC Service Definition (`api/proto/auth.proto`)
|
||||
- `LoginRequest` / `LoginResponse` - User login
|
||||
- `RefreshTokenRequest` / `RefreshTokenResponse` - Token refresh
|
||||
- `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`)
|
||||
- Extract JWT from `Authorization: Bearer <token>` header
|
||||
- Verify token validity (signature and expiration)
|
||||
- Inject authenticated user into request context
|
||||
- Helper function: `auth.FromContext(ctx) *User`
|
||||
- Handle authentication errors appropriately
|
||||
### 5. Database Connection and Schema (`services/auth/ent/schema/`)
|
||||
- Auth Service database connection (schema: `auth`)
|
||||
- Refresh token storage schema (if storing refresh tokens in DB)
|
||||
- Migration support
|
||||
- Per-service connection pool
|
||||
|
||||
### 4. Authentication Endpoints
|
||||
- `POST /api/v1/auth/login` - Authenticate user and return tokens
|
||||
- Validate email and password
|
||||
- Return access + refresh tokens
|
||||
- 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
|
||||
### 6. Service Client Integration
|
||||
- Uses `IdentityServiceClient` to validate user credentials
|
||||
- Uses `AuditServiceClient` to log authentication events
|
||||
- Service discovery via Consul
|
||||
|
||||
### 5. gRPC Server (Microservices)
|
||||
- Expose gRPC server for authentication service
|
||||
- gRPC service definition in `api/proto/auth.proto`
|
||||
- gRPC server implementation in `internal/auth/grpc/server.go`
|
||||
- Service registration in service registry
|
||||
|
||||
### 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
|
||||
### 7. Service Registration
|
||||
- Register with Consul on startup
|
||||
- Health check endpoint for Consul
|
||||
- Service metadata (name: `auth-service`, port: 8081)
|
||||
- Deregister on shutdown
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. **Install Dependencies**
|
||||
```bash
|
||||
go get github.com/golang-jwt/jwt/v5
|
||||
```
|
||||
1. **Create Service Entry Point**
|
||||
- Create `cmd/auth-service/main.go`
|
||||
- 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**
|
||||
- Create `pkg/auth/auth.go`
|
||||
- Define Authenticator interface
|
||||
- Define TokenClaims struct
|
||||
2. **Define gRPC Service**
|
||||
- Create `api/proto/auth.proto`
|
||||
- Define Login, RefreshToken, ValidateToken RPCs
|
||||
- Generate Go code from proto
|
||||
|
||||
3. **Implement JWT Authentication**
|
||||
- Create `internal/auth/jwt_auth.go`
|
||||
- Implement token generation
|
||||
- Implement token verification
|
||||
- Handle token expiration
|
||||
3. **Implement Auth Service**
|
||||
- Create `services/auth/internal/service/auth_service.go`
|
||||
- Implement JWT token generation/validation
|
||||
- Integrate with IdentityServiceClient for credential validation
|
||||
- Integrate with AuditServiceClient for logging
|
||||
|
||||
4. **Create Authentication Middleware**
|
||||
- Create `internal/auth/middleware.go`
|
||||
- Implement token extraction
|
||||
- Implement token verification
|
||||
- Inject user into context
|
||||
4. **Implement gRPC Server**
|
||||
- Create `services/auth/internal/api/server.go`
|
||||
- Implement gRPC handlers
|
||||
- Wire up service logic
|
||||
|
||||
5. **Create Authentication Endpoints**
|
||||
- Create login handler
|
||||
- Create refresh handler
|
||||
- Add routes to HTTP server
|
||||
5. **Database Setup**
|
||||
- Create `services/auth/ent/schema/` if storing refresh tokens
|
||||
- Set up migrations
|
||||
- Configure per-service connection pool
|
||||
|
||||
6. **Integrate with DI**
|
||||
- Create provider function
|
||||
- Register in container
|
||||
6. **Service Registration**
|
||||
- Register with Consul on startup
|
||||
- Set up health check endpoint
|
||||
- Handle graceful shutdown
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] Users can login and receive access and refresh tokens
|
||||
- [ ] Access tokens expire after configured duration
|
||||
- [ ] Refresh tokens can be used to obtain new access tokens
|
||||
- [ ] Invalid tokens are rejected with appropriate errors
|
||||
- [ ] Authenticated user is available in request context
|
||||
- [ ] Login attempts are logged (success and failure)
|
||||
- [ ] Token secrets are configurable
|
||||
- [ ] Token claims include user ID, roles, and tenant ID
|
||||
- [x] Auth Service is independently deployable
|
||||
- [x] Service entry point exists at `cmd/auth-service/main.go`
|
||||
- [x] Service registers with Consul on startup
|
||||
- [x] gRPC server starts on configured port (8081)
|
||||
- [x] Login RPC validates credentials via IdentityServiceClient
|
||||
- [x] Login RPC returns access and refresh tokens
|
||||
- [x] RefreshToken RPC issues new access tokens
|
||||
- [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
|
||||
go test ./internal/auth/...
|
||||
# Test Auth Service
|
||||
go test ./services/auth/...
|
||||
|
||||
# Test login endpoint
|
||||
curl -X POST http://localhost:8080/api/v1/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"email":"user@example.com","password":"password"}'
|
||||
# Test service startup
|
||||
go run cmd/auth-service/main.go
|
||||
|
||||
# Test refresh endpoint
|
||||
curl -X POST http://localhost:8080/api/v1/auth/refresh \
|
||||
-H "Authorization: Bearer <refresh_token>"
|
||||
# Test gRPC service (via grpcurl or client)
|
||||
grpcurl -plaintext localhost:8081 list
|
||||
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
|
||||
- `internal/auth/jwt_auth.go` - JWT implementation
|
||||
- `internal/auth/middleware.go` - Authentication middleware
|
||||
- `internal/auth/handler.go` - Authentication handlers
|
||||
- `internal/di/providers.go` - Add auth provider
|
||||
- `config/default.yaml` - Add JWT configuration
|
||||
- `cmd/auth-service/main.go` - Service entry point
|
||||
- `api/proto/auth.proto` - gRPC service definition
|
||||
- `services/auth/internal/api/server.go` - gRPC server implementation
|
||||
- `services/auth/internal/service/auth_service.go` - Auth service logic
|
||||
- `services/auth/ent/schema/` - Database schema (if storing refresh tokens)
|
||||
- `config/default.yaml` - Add auth service configuration
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
- **Epic**: 2 - Authentication & Authorization
|
||||
- **Title**: Authz Service - Authorization & RBAC
|
||||
- **Epic**: 2 - Core Services (Authentication & Authorization)
|
||||
- **Status**: Pending
|
||||
- **Priority**: High
|
||||
- **Estimated Time**: 6-8 hours
|
||||
- **Dependencies**: 1.2, 2.1
|
||||
- **Estimated Time**: 10-12 hours
|
||||
- **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`)
|
||||
- `Permission` type (string format: "module.resource.action")
|
||||
- Core permission constants (system, user, role permissions)
|
||||
- Permission validation utilities
|
||||
### 1. Service Entry Point (`cmd/authz-service/main.go`)
|
||||
- Independent service entry point
|
||||
- Bootstrap with core kernel services
|
||||
- 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`)
|
||||
- `PermissionResolver` interface
|
||||
- Implementation that loads user roles and permissions from database
|
||||
- Permission checking with caching
|
||||
### 2. gRPC Service Definition (`api/proto/authz.proto`)
|
||||
- `AuthorizeRequest` / `AuthorizeResponse` - Check if user has permission
|
||||
- `HasPermissionRequest` / `HasPermissionResponse` - Boolean permission check
|
||||
- `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`)
|
||||
- `Authorizer` interface
|
||||
- RBAC authorizer implementation
|
||||
- Extract user from context
|
||||
- Check permissions
|
||||
- Return authorization errors
|
||||
### 5. Permission System (`pkg/perm/perm.go`)
|
||||
- `Permission` type (string format: "module.resource.action")
|
||||
- Core permission constants
|
||||
- Permission validation utilities
|
||||
|
||||
### 4. Authorization Middleware
|
||||
- `RequirePermission(perm Permission) gin.HandlerFunc` decorator
|
||||
- Integration with route registration
|
||||
- Proper error responses for unauthorized access
|
||||
### 6. Database Connection and Schema (`services/authz/ent/schema/`)
|
||||
- Authz Service database connection (schema: `authz`)
|
||||
- Role entity schema: ID, name, description, created_at
|
||||
- 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)
|
||||
- Expose gRPC server for authorization service
|
||||
- gRPC service definition in `api/proto/authz.proto`
|
||||
- gRPC server implementation in `internal/auth/grpc/authz_server.go`
|
||||
- Service registration in service registry
|
||||
- Uses `IdentityServiceClient` for user operations
|
||||
### 7. Service Client Integration
|
||||
- Uses `IdentityServiceClient` to get user roles
|
||||
- Uses `AuditServiceClient` to log authorization checks
|
||||
- Service discovery via Consul
|
||||
|
||||
### 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
|
||||
- [ ] Users inherit permissions through roles
|
||||
- [ ] Authorization middleware protects routes
|
||||
- [ ] Unauthorized requests return 403 errors
|
||||
- [ ] Permission checks are cached for performance
|
||||
- [ ] Permission system is extensible by modules
|
||||
- [x] Authz Service is independently deployable
|
||||
- [x] Service entry point exists at `cmd/authz-service/main.go`
|
||||
- [x] Service registers with Consul on startup
|
||||
- [x] gRPC server starts on configured port (8083)
|
||||
- [x] Authorize RPC checks if user has permission
|
||||
- [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
|
||||
- `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
|
||||
- `config/default.yaml` - Add authz service configuration
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
- **Epic**: 2 - Authentication & Authorization
|
||||
- **Title**: Audit Service - Audit Logging
|
||||
- **Epic**: 2 - Core Services (Authentication & Authorization)
|
||||
- **Status**: Pending
|
||||
- **Priority**: High
|
||||
- **Estimated Time**: 5-6 hours
|
||||
- **Dependencies**: 1.2, 2.1
|
||||
- **Estimated Time**: 6-8 hours
|
||||
- **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`)
|
||||
- `Auditor` interface with `Record(ctx, action)` method
|
||||
### 1. Service Entry Point (`cmd/audit-service/main.go`)
|
||||
- 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`)
|
||||
- Write audit logs to `audit_log` table
|
||||
- Capture actor from request context
|
||||
- Include request metadata (ID, IP, user agent, timestamp)
|
||||
- Store action details and target information
|
||||
- Support JSON metadata for flexible logging
|
||||
### 6. Database Connection and Schema (`services/audit/ent/schema/audit_log.go`)
|
||||
- Audit Service database connection (schema: `audit`)
|
||||
- AuditLog entity schema:
|
||||
- ID, actor_id, action, target_id, metadata (JSONB), timestamp
|
||||
- Immutable (no update/delete operations)
|
||||
- Migration support
|
||||
- Per-service connection pool
|
||||
|
||||
### 3. Audit Middleware
|
||||
- Intercept all authenticated requests
|
||||
- Record action (HTTP method + path)
|
||||
- Extract user and request context
|
||||
- Store audit log entry
|
||||
|
||||
### 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
|
||||
### 7. Service Registration
|
||||
- Register with Consul on startup
|
||||
- Health check endpoint for Consul
|
||||
- Service metadata (name: `audit-service`, port: 8084)
|
||||
- Deregister on shutdown
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] All authenticated actions are logged
|
||||
- [ ] Audit logs include complete context (actor, action, target, metadata)
|
||||
- [ ] Audit logs are immutable (no updates/deletes)
|
||||
- [ ] Audit logs can be queried and filtered
|
||||
- [ ] Audit logging has minimal performance impact
|
||||
- [ ] Audit logs are stored securely
|
||||
- [x] Audit Service is independently deployable
|
||||
- [x] Service entry point exists at `cmd/audit-service/main.go`
|
||||
- [x] Service registers with Consul on startup
|
||||
- [x] gRPC server starts on configured port (8084)
|
||||
- [x] Record RPC stores audit log entries
|
||||
- [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
|
||||
- `internal/audit/ent_auditor.go` - Audit implementation
|
||||
- `internal/audit/middleware.go` - Audit middleware
|
||||
- `internal/audit/handler.go` - Audit query handler
|
||||
- `cmd/audit-service/main.go` - Service entry point
|
||||
- `api/proto/audit.proto` - gRPC service definition
|
||||
- `services/audit/internal/api/server.go` - gRPC server implementation
|
||||
- `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
|
||||
|
||||
|
||||
@@ -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
|
||||
- **Epic**: 2 - Authentication & Authorization
|
||||
- **Title**: Database Seeding
|
||||
- **Epic**: 2 - Core Services (Authentication & Authorization)
|
||||
- **Status**: Pending
|
||||
- **Priority**: Medium
|
||||
- **Estimated Time**: 3-4 hours
|
||||
- **Dependencies**: 1.2, 2.3, 2.4
|
||||
- **Estimated Time**: 4-6 hours
|
||||
- **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)
|
||||
- Assign core permissions to roles
|
||||
- Set up initial role hierarchy
|
||||
- Idempotent operations (safe to run multiple times)
|
||||
- Idempotent operations
|
||||
- Uses Identity Service's own database connection
|
||||
|
||||
### 2. Seed Command (`cmd/seed/main.go`)
|
||||
- Command-line interface for seeding
|
||||
### 2. Authz Service Seeding (`services/authz/internal/seed/seed.go`)
|
||||
- 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
|
||||
- [ ] Default roles are created with proper permissions
|
||||
- [ ] Seeding is idempotent (can run multiple times safely)
|
||||
- [ ] Seed script can be run via CLI
|
||||
- [ ] Admin user can login and manage system
|
||||
- [x] Identity Service seed creates admin user successfully
|
||||
- [x] Authz Service seed creates default roles with proper permissions
|
||||
- [x] Seeding is idempotent (can run multiple times safely)
|
||||
- [x] Seed command can be run via CLI
|
||||
- [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
|
||||
- Uses service clients if accessing services (e.g., IdentityServiceClient for user creation)
|
||||
- Can be run as a separate command or as part of deployment
|
||||
- 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
|
||||
- `cmd/seed/main.go` - Seed command
|
||||
- `services/identity/internal/seed/seed.go` - Identity Service seed functions
|
||||
- `services/authz/internal/seed/seed.go` - Authz Service seed functions
|
||||
- `cmd/seed/main.go` - Seed command (coordinates all services)
|
||||
- `Makefile` - Add seed command
|
||||
|
||||
|
||||
@@ -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
|
||||
- [Story: 2.1 - JWT Authentication](./2.1-jwt-authentication.md)
|
||||
- **Goal:** Implement a complete JWT-based authentication system with access tokens, refresh tokens, and secure token management.
|
||||
- **Deliverables:** Authentication interfaces, JWT implementation, authentication middleware, login/refresh endpoints
|
||||
### 2.1 Auth Service - JWT Authentication
|
||||
- [Story: 2.1 - Auth Service](./2.1-jwt-authentication.md)
|
||||
- **Goal:** Implement Auth Service as independent microservice with JWT token generation/validation.
|
||||
- **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
|
||||
- [Story: 2.2 - Identity Management](./2.2-identity-management.md)
|
||||
- **Goal:** Build a complete user identity management system with registration, email verification, password management, and user CRUD operations.
|
||||
- **Deliverables:** Identity interfaces, user repository, user service, user management API endpoints
|
||||
### 2.2 Identity Service - User Management
|
||||
- [Story: 2.2 - Identity Service](./2.2-identity-management.md)
|
||||
- **Goal:** Implement Identity Service as independent microservice for user CRUD and password management.
|
||||
- **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
|
||||
- [Story: 2.3 - RBAC System](./2.3-rbac-system.md)
|
||||
- **Goal:** Implement a complete RBAC system with permissions, role management, and authorization middleware.
|
||||
- **Deliverables:** Permission system, permission resolver, authorization system, authorization middleware
|
||||
### 2.3 Authz Service - Authorization & RBAC
|
||||
- [Story: 2.3 - Authz Service](./2.3-rbac-system.md)
|
||||
- **Goal:** Implement Authz Service as independent microservice for permission resolution and authorization.
|
||||
- **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.
|
||||
- **Deliverables:** Role repository, role management API endpoints, authorization and validation
|
||||
- **Goal:** Extend Authz Service with role management API.
|
||||
- **Deliverables:**
|
||||
- Role management gRPC endpoints
|
||||
- Role assignment to users (via Identity Service client)
|
||||
- Permission assignment to roles
|
||||
|
||||
### 2.5 Audit Logging System
|
||||
- [Story: 2.5 - Audit Logging](./2.5-audit-logging.md)
|
||||
- **Goal:** Implement comprehensive audit logging that records all security-sensitive actions for compliance and security monitoring.
|
||||
- **Deliverables:** Audit interface, audit implementation, audit middleware, audit log query API
|
||||
### 2.5 Audit Service - Audit Logging
|
||||
- [Story: 2.5 - Audit Service](./2.5-audit-logging.md)
|
||||
- **Goal:** Implement Audit Service as independent microservice for audit logging.
|
||||
- **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.
|
||||
- **Deliverables:** Seed script, seed command, integration with application startup
|
||||
|
||||
### 2.7 Service Client Interfaces
|
||||
- [Story: 2.7 - Service Client Interfaces](./2.7-service-abstraction-layer.md) (moved from Epic 1)
|
||||
- **Goal:** Create service client interfaces for all core services to enable microservices communication.
|
||||
- **Deliverables:** Service client interfaces, service factory, configuration
|
||||
- **Goal:** Provide seeding for all services (initial admin user, default roles, permissions).
|
||||
- **Deliverables:**
|
||||
- Seed scripts for each service
|
||||
- Seed commands
|
||||
- Integration with service startup
|
||||
|
||||
## Deliverables Checklist
|
||||
- [ ] JWT authentication with access/refresh tokens
|
||||
- [ ] User CRUD with email verification
|
||||
- [ ] Role and permission management
|
||||
- [ ] Authorization middleware
|
||||
- [ ] Audit logging for all actions
|
||||
- [ ] Seed script for initial data
|
||||
- [ ] Auth Service: Independent service with gRPC server, database schema, Consul registration
|
||||
- [ ] Identity Service: Independent service with gRPC server, User entity, Consul registration
|
||||
- [ ] Authz Service: Independent service with gRPC server, Role/Permission entities, Consul registration
|
||||
- [ ] Audit Service: Independent service with gRPC server, AuditLog entity, Consul registration
|
||||
- [ ] All services use service clients for inter-service communication
|
||||
- [ ] All services have their own database connection pools and schemas
|
||||
- [ ] Seed scripts for all services
|
||||
|
||||
## Acceptance Criteria
|
||||
- User can register and login
|
||||
- JWT tokens are validated on protected routes
|
||||
- Users without permission get 403
|
||||
- All actions are logged in audit table
|
||||
- Admin can create roles and assign permissions
|
||||
- Integration test: user without permission cannot access protected resource
|
||||
- Each service is independently deployable
|
||||
- Each service has its own entry point (`cmd/{service}/main.go`)
|
||||
- Each service registers with Consul service registry
|
||||
- Services communicate via gRPC through service clients
|
||||
- Each service has its own database schema
|
||||
- API Gateway can route to all services via service discovery
|
||||
- Integration test: Services can discover and communicate with each other
|
||||
|
||||
@@ -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
|
||||
- **Epic**: 3 - Module Framework
|
||||
- **Title**: Module System Interface and Service Registry
|
||||
- **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:
|
||||
- `Name() string` - Module name
|
||||
- `Version() string` - Module version
|
||||
- `Dependencies() []string` - Module dependencies
|
||||
- `Init() fx.Option` - FX options for module initialization
|
||||
- `Migrations() []func(*ent.Client) error` - Database migrations
|
||||
- `IModule` interface for feature services:
|
||||
- `Name() string` - Service name
|
||||
- `Version() string` - Service version
|
||||
- `Dependencies() []string` - Service dependencies (other services)
|
||||
- `Init() fx.Option` - FX options for service initialization
|
||||
- `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`)
|
||||
- Thread-safe module map
|
||||
### 3. Service Registration Integration
|
||||
- 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()`
|
||||
- [ ] Registry validates dependencies
|
||||
- [ ] Registry prevents duplicate registrations
|
||||
- [ ] Module interface is extensible
|
||||
- [ ] Dependency cycles are detected
|
||||
- [ ] Version compatibility is checked
|
||||
- [x] Feature services can register via module interface
|
||||
- [x] Registry validates service dependencies
|
||||
- [x] Registry prevents duplicate registrations
|
||||
- [x] Module interface supports service architecture
|
||||
- [x] Dependency cycles are detected
|
||||
- [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)
|
||||
|
||||
|
||||
@@ -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
|
||||
- **Epic**: 3 - Module Framework
|
||||
- **Title**: Service Loader and Initialization
|
||||
- **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`)
|
||||
- Support static registration (preferred method)
|
||||
- Optional: Go plugin loading (`.so` files)
|
||||
- Module discovery from `modules/*/module.yaml`
|
||||
- Loader interface for extensibility
|
||||
### 1. Service Initialization Helpers (`internal/service/init.go`)
|
||||
- `InitializeService(cfg, module IModule)` function
|
||||
- Bootstrap core kernel services
|
||||
- Initialize service-specific components
|
||||
- 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`)
|
||||
- Import modules via side-effect imports
|
||||
- Collect all registered modules
|
||||
- Module discovery and registration
|
||||
### 2. Service Dependency Resolution (`internal/service/deps.go`)
|
||||
- Resolve service dependencies (check other services are available via Consul)
|
||||
- Wait for dependent services to be healthy
|
||||
- Service discovery integration
|
||||
- Dependency validation
|
||||
|
||||
### 3. Optional Plugin Loader (`internal/pluginloader/plugin_loader.go`)
|
||||
- Scan `./plugins/*.so` files
|
||||
- Load via `plugin.Open()`
|
||||
- Extract and validate module symbols
|
||||
- Version compatibility checking
|
||||
### 3. Service Bootstrap Pattern (`internal/service/bootstrap.go`)
|
||||
- Common bootstrap pattern for feature services
|
||||
- FX lifecycle integration
|
||||
- Service registration helpers
|
||||
- Health check setup
|
||||
- Migration runner (per-service)
|
||||
|
||||
### 4. Module Initializer (`internal/module/initializer.go`)
|
||||
- Collect all registered modules
|
||||
- Resolve dependency order (topological sort)
|
||||
- Initialize each module's `Init()` fx.Option
|
||||
- Merge all options into main fx container
|
||||
- Run migrations in dependency order
|
||||
- Handle errors gracefully
|
||||
### 4. Service Template/Scaffolding
|
||||
- Service template generator
|
||||
- Standard service structure
|
||||
- Example service entry point
|
||||
|
||||
### 5. FX Lifecycle Integration
|
||||
- Call `OnStart()` during app startup
|
||||
- Call `OnStop()` during graceful shutdown
|
||||
- Proper error handling
|
||||
**Note:** Each feature service has its own `cmd/{service}/main.go` that uses these helpers to initialize itself.
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. **Create Module Loader**
|
||||
- Create `internal/pluginloader/loader.go`
|
||||
- Define loader interface
|
||||
1. **Create Service Initialization Helpers**
|
||||
- Create `internal/service/init.go`
|
||||
- Implement service bootstrap pattern
|
||||
- Integrate with Consul service registry
|
||||
|
||||
2. **Implement Static Loader**
|
||||
- Create `internal/pluginloader/static_loader.go`
|
||||
- Implement static module loading
|
||||
2. **Implement Dependency Resolution**
|
||||
- Create `internal/service/deps.go`
|
||||
- Check service dependencies via Consul
|
||||
- Wait for services to be healthy
|
||||
|
||||
3. **Implement Module Initializer**
|
||||
- Create `internal/module/initializer.go`
|
||||
- Implement dependency resolution
|
||||
- Implement initialization
|
||||
3. **Create Service Bootstrap**
|
||||
- Create `internal/service/bootstrap.go`
|
||||
- Common bootstrap pattern
|
||||
- FX lifecycle integration
|
||||
|
||||
4. **Integrate with FX**
|
||||
- Add lifecycle hooks
|
||||
- Test initialization
|
||||
4. **Create Service Template**
|
||||
- Service template generator
|
||||
- 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
|
||||
- [ ] Module migrations run automatically
|
||||
- [ ] Module initialization integrates with FX
|
||||
- [ ] Lifecycle hooks work correctly
|
||||
- [ ] Dependency resolution handles cycles
|
||||
- [ ] Errors are handled gracefully
|
||||
- [x] Service initialization helpers work correctly
|
||||
- [x] Services register with Consul automatically
|
||||
- [x] Service migrations run on startup (per-service schema)
|
||||
- [x] Service dependency resolution works via Consul
|
||||
- [x] Services wait for dependencies to be healthy
|
||||
- [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/pluginloader/static_loader.go` - Static loader
|
||||
- `internal/pluginloader/plugin_loader.go` - Plugin loader (optional)
|
||||
- `internal/module/initializer.go` - Module initializer
|
||||
- `internal/di/container.go` - Integrate module initialization
|
||||
- `internal/service/init.go` - Service initialization helpers
|
||||
- `internal/service/deps.go` - Service dependency resolution
|
||||
- `internal/service/bootstrap.go` - Service bootstrap pattern
|
||||
- `internal/service/template.go` - Service template generator
|
||||
- Example: `cmd/blog-service/main.go` - Example service entry point
|
||||
|
||||
|
||||
@@ -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
|
||||
- **Epic**: 3 - Module Framework
|
||||
- **Title**: Service Management CLI Tool
|
||||
- **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 modules validate` - Validate module dependencies
|
||||
- `platformctl modules test <module>` - Test module loading
|
||||
- `platformctl modules info <module>` - Show module details
|
||||
- `platformctl modules dependencies <module>` - Show module dependencies
|
||||
- `platformctl services list` - List all services registered in Consul
|
||||
- `platformctl services validate` - Validate service dependencies
|
||||
- `platformctl services test <service>` - Test service registration and health
|
||||
- `platformctl services info <service>` - Show service details from Consul
|
||||
- `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
|
||||
- [ ] Dependency validation works
|
||||
- [ ] Module testing works
|
||||
- [ ] CLI is installable and usable
|
||||
- [ ] Commands provide helpful output
|
||||
- [ ] Error messages are clear
|
||||
- [x] CLI tool lists all services from Consul
|
||||
- [x] Service dependency validation works
|
||||
- [x] Service health checking works
|
||||
- [x] CLI is installable and usable
|
||||
- [x] Commands provide helpful output
|
||||
- [x] Error messages are clear
|
||||
- [x] Integration with Consul service registry works
|
||||
|
||||
## Files to Create/Modify
|
||||
- `cmd/platformctl/main.go` - CLI tool
|
||||
|
||||
@@ -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
|
||||
- **Epic**: 3 - Module Framework
|
||||
- **Title**: Service Registry and Discovery (Verification)
|
||||
- **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`)
|
||||
- `ServiceRegistry` interface with:
|
||||
- `Register(service ServiceInfo) error` - Register a service
|
||||
- `Deregister(serviceID string) error` - Deregister a service
|
||||
- `Discover(serviceName string) ([]ServiceInfo, error)` - Discover services
|
||||
- `GetService(serviceName string) (ServiceInfo, error)` - Get specific service
|
||||
- `ListServices() ([]ServiceInfo, error)` - List all services
|
||||
- `HealthCheck(serviceID string) error` - Check service health
|
||||
### 1. Service Registry Verification
|
||||
- Verify Consul registry implementation from Epic 1 works correctly
|
||||
- Test service registration for feature services
|
||||
- Test service discovery for feature services
|
||||
- Verify health checking integration
|
||||
|
||||
### 2. Service Info Structure
|
||||
- `ServiceInfo` struct with:
|
||||
- ID, Name, Version
|
||||
- Address (host:port)
|
||||
- Protocol (local, grpc, http)
|
||||
- Health status
|
||||
- Metadata
|
||||
### 2. Integration Documentation
|
||||
- Document how feature services register with Consul
|
||||
- Document service discovery patterns for feature services
|
||||
- Update examples to show feature service registration
|
||||
|
||||
### 3. Consul Registry (`internal/services/registry/consul.go`)
|
||||
- Consul integration (primary for production)
|
||||
- Service registration and discovery
|
||||
- Health checking
|
||||
- Automatic service registration
|
||||
### 3. Integration Tests
|
||||
- Test feature service registration
|
||||
- Test feature service discovery
|
||||
- Test health checking for feature services
|
||||
- Test service client integration with Consul
|
||||
|
||||
### 4. Kubernetes Service Discovery (`internal/services/registry/kubernetes.go`)
|
||||
- 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
|
||||
**Note:** Service registry implementation is in Epic 1 (Story 1.7). This story verifies integration with feature services.
|
||||
|
||||
|
||||
@@ -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.
|
||||
- **Deliverables:** Module interface, module manifest, module registry
|
||||
- **Goal:** Design module interface for feature services with service registration and dependency resolution.
|
||||
- **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
|
||||
- [Story: 3.3 - Module Loader](./3.3-module-loader.md)
|
||||
- **Goal:** Implement module loading (static and dynamic) with dependency resolution and automatic initialization.
|
||||
- **Deliverables:** Module loader, static loader, plugin loader, module initializer, FX lifecycle integration
|
||||
### 3.3 Service Loader and Initialization
|
||||
- [Story: 3.3 - Service Loader](./3.3-module-loader.md)
|
||||
- **Goal:** Implement service loading and initialization for feature services with dependency resolution.
|
||||
- **Deliverables:** Service loader, service initialization, FX lifecycle integration, Consul registration
|
||||
|
||||
### 3.4 Module Management CLI Tool
|
||||
- [Story: 3.4 - Module CLI](./3.4-module-cli.md)
|
||||
- **Goal:** Provide CLI tooling for managing modules, validating dependencies, and testing module loading.
|
||||
### 3.4 Service Management CLI Tool
|
||||
- [Story: 3.4 - Service CLI](./3.4-module-cli.md)
|
||||
- **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.
|
||||
- **Deliverables:** Service registry interface, Consul registry, Kubernetes registry, service registration
|
||||
- **Goal:** Implement Consul-based service registry for service discovery (already implemented in Epic 1, verify integration).
|
||||
- **Deliverables:** Service registry interface verification, Consul integration verification
|
||||
|
||||
## Deliverables Checklist
|
||||
- [ ] Module interface and registration system
|
||||
- [ ] Static module registry working
|
||||
- [ ] Module interface for feature services
|
||||
- [ ] Service registration with Consul
|
||||
- [ ] Permission code generation tool
|
||||
- [ ] Module loader with dependency resolution
|
||||
- [ ] Module initialization in main app
|
||||
- [ ] CLI tool for module management
|
||||
- [ ] Service registry for discovery
|
||||
- [ ] Service loader with dependency resolution
|
||||
- [ ] Service initialization in service entry points
|
||||
- [ ] CLI tool for service management
|
||||
- [ ] 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
|
||||
- Module migrations run on startup
|
||||
- `platformctl modules list` shows all modules
|
||||
- Integration test: load multiple modules and verify initialization
|
||||
- Services load in correct dependency order
|
||||
- Service migrations run on startup
|
||||
- Services register with Consul automatically
|
||||
- `platformctl services list` shows all services
|
||||
- Integration test: load multiple services and verify Consul registration
|
||||
|
||||
@@ -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
|
||||
- **Epic**: 4 - Sample Feature Module (Blog)
|
||||
- **Title**: Complete Blog Service
|
||||
- **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
|
||||
- Create `modules/blog/` directory with proper structure:
|
||||
### 1. Blog Service Entry Point (`cmd/blog-service/main.go`)
|
||||
- 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/
|
||||
│ └── schema/
|
||||
│ └── post.go
|
||||
└── pkg/
|
||||
└── module.go
|
||||
│ └── database/
|
||||
│ └── client.go # Database connection (blog schema)
|
||||
└── ent/
|
||||
└── schema/
|
||||
└── post.go
|
||||
```
|
||||
- Initialize `go.mod` for blog module
|
||||
|
||||
### 2. Module Manifest (`modules/blog/module.yaml`)
|
||||
- Define module metadata (name, version, dependencies)
|
||||
### 3. gRPC Service Definition (`api/proto/blog.proto`)
|
||||
- `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
|
||||
- `Post` domain entity in `modules/blog/internal/domain/post.go`
|
||||
- Ent schema in `modules/blog/internal/ent/schema/post.go`:
|
||||
- Fields: title, content, author_id (FK to user)
|
||||
### 6. Blog Domain Model
|
||||
- `Post` domain entity in `services/blog/internal/domain/post.go`
|
||||
- Ent schema in `services/blog/ent/schema/post.go`:
|
||||
- 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
|
||||
- `PostRepository` interface in `modules/blog/internal/domain/post_repo.go`
|
||||
- Implementation using Ent client (shared from core)
|
||||
### 7. Blog Repository
|
||||
- `PostRepository` interface in `services/blog/internal/domain/post_repo.go`
|
||||
- Implementation using Ent client (blog schema)
|
||||
- CRUD operations: Create, FindByID, FindByAuthor, Update, Delete
|
||||
- Pagination support
|
||||
|
||||
### 5. Blog Service
|
||||
- `PostService` in `modules/blog/internal/service/post_service.go`
|
||||
### 8. Blog Service
|
||||
- `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
|
||||
- API handlers in `modules/blog/internal/api/handler.go`:
|
||||
- `POST /api/v1/blog/posts` - Create post
|
||||
- `GET /api/v1/blog/posts/:id` - Get post
|
||||
- `GET /api/v1/blog/posts` - List posts (with pagination)
|
||||
- `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
|
||||
### 9. Service Registration
|
||||
- Register with Consul on startup
|
||||
- Health check endpoint for Consul
|
||||
- Service metadata (name: `blog-service`, port: 8091)
|
||||
- Deregister on shutdown
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. **Create Module Structure**
|
||||
- Create directory structure
|
||||
1. **Create Service Entry Point**
|
||||
- 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**
|
||||
- Create handlers
|
||||
- Add authorization middleware
|
||||
- Register routes
|
||||
7. **Implement gRPC Server**
|
||||
- Create gRPC server implementation
|
||||
- Wire up handlers
|
||||
- Start server
|
||||
|
||||
7. **Create Module Implementation**
|
||||
- Implement IModule interface
|
||||
- Register module
|
||||
|
||||
8. **Integrate with Platform**
|
||||
- Import module in main
|
||||
- Generate permissions
|
||||
- Test integration
|
||||
8. **Service Registration**
|
||||
- Register with Consul on startup
|
||||
- Set up health checks
|
||||
- Test service discovery
|
||||
|
||||
9. **Add Tests**
|
||||
- Create integration tests
|
||||
- Create unit tests
|
||||
- Test service client integration
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] Blog module loads on platform startup
|
||||
- [ ] `POST /api/v1/blog/posts` requires `blog.post.create` permission
|
||||
- [ ] User can create, read, update, delete posts
|
||||
- [ ] Authorization enforced (users can only edit own posts)
|
||||
- [ ] Integration test: full CRUD flow works
|
||||
- [ ] Audit logs record all blog actions
|
||||
- [ ] Permissions are generated correctly
|
||||
- [ ] Module migrations run on startup
|
||||
- [x] Blog service is independently deployable
|
||||
- [x] Service entry point exists at `cmd/blog-service/main.go`
|
||||
- [x] Service registers with Consul on startup
|
||||
- [x] gRPC server starts on configured port (8091)
|
||||
- [x] CreatePost RPC requires `blog.post.create` permission (via AuthzServiceClient)
|
||||
- [x] User can create, read, update, delete posts via gRPC
|
||||
- [x] Service uses IdentityServiceClient for user operations
|
||||
- [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
|
||||
- `modules/blog/go.mod` - Module dependencies
|
||||
- `modules/blog/internal/domain/post.go` - Domain model
|
||||
- `modules/blog/internal/ent/schema/post.go` - Ent schema
|
||||
- `modules/blog/internal/domain/post_repo.go` - Repository
|
||||
- `modules/blog/internal/service/post_service.go` - Service
|
||||
- `modules/blog/internal/api/handler.go` - API handlers
|
||||
- `modules/blog/pkg/module.go` - Module implementation
|
||||
- `go.mod` - Add blog module
|
||||
- `cmd/platform/main.go` - Import blog module
|
||||
- `cmd/blog-service/main.go` - Service entry point
|
||||
- `services/blog/module.yaml` - Service manifest
|
||||
- `services/blog/go.mod` - Service dependencies
|
||||
- `api/proto/blog.proto` - gRPC service definition
|
||||
- `services/blog/internal/api/server.go` - gRPC server implementation
|
||||
- `services/blog/internal/domain/post.go` - Domain model
|
||||
- `services/blog/ent/schema/post.go` - Ent schema (blog schema)
|
||||
- `services/blog/internal/domain/post_repo.go` - Repository
|
||||
- `services/blog/internal/service/post_service.go` - Service logic
|
||||
- `config/default.yaml` - Add blog service configuration
|
||||
|
||||
|
||||
@@ -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
|
||||
- [Story: 4.1 - Blog Module](./4.1-blog-module.md)
|
||||
- **Goal:** Create a complete sample blog module to demonstrate the framework.
|
||||
- **Deliverables:** Complete blog module with CRUD operations, permissions, database entities, services, API handlers, and integration tests
|
||||
### 4.1 Complete Blog Service
|
||||
- [Story: 4.1 - Blog Service](./4.1-blog-module.md)
|
||||
- **Goal:** Create a complete sample blog service to demonstrate the framework.
|
||||
- **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
|
||||
- [ ] Module manifest defines permissions and routes
|
||||
- [ ] Blog service entry point (`cmd/blog-service/main.go`)
|
||||
- [ ] 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
|
||||
- [ ] Module integrated with core platform
|
||||
- [ ] Service uses service clients (Identity, Authz, Audit)
|
||||
- [ ] Service registers with Consul
|
||||
- [ ] Integration tests passing
|
||||
|
||||
## Acceptance Criteria
|
||||
- Blog module can be registered with core platform
|
||||
- Permissions are generated for blog module
|
||||
- Blog service is independently deployable
|
||||
- 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
|
||||
- Module migrations run on startup
|
||||
- Blog posts are associated with users
|
||||
- Authorization enforced (users can only edit own posts)
|
||||
- Service uses IdentityServiceClient for user operations
|
||||
- Service uses AuthzServiceClient for authorization
|
||||
- Service uses AuditServiceClient for audit logging
|
||||
- Service has its own database schema (blog schema)
|
||||
- Service can be discovered by API Gateway via Consul
|
||||
|
||||
@@ -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
|
||||
- **Dependencies**: 1.7, 3.5
|
||||
- **Estimated Time**: 6-8 hours
|
||||
- **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/`)
|
||||
- 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
|
||||
### 1. Streaming RPC Support
|
||||
- Add streaming RPC definitions to existing proto files
|
||||
- Server-side streaming implementations
|
||||
- Client-side streaming implementations
|
||||
- Bidirectional streaming support
|
||||
- Example: Stream audit logs, stream user events
|
||||
|
||||
### 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
|
||||
### 2. gRPC-Gateway Integration
|
||||
- HTTP to gRPC gateway for REST API access
|
||||
- Generate REST endpoints from gRPC services
|
||||
- Support for both gRPC and HTTP on same service
|
||||
- Gateway configuration
|
||||
|
||||
### 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
|
||||
### 3. Advanced Error Handling
|
||||
- Structured error responses
|
||||
- gRPC status codes mapping
|
||||
- Error details and metadata
|
||||
- Error propagation across services
|
||||
|
||||
### 4. gRPC Server Setup
|
||||
- gRPC server initialization
|
||||
- Service registration
|
||||
- Health check service
|
||||
- Reflection service (development)
|
||||
- Integration with HTTP server (gRPC-Gateway optional)
|
||||
### 4. gRPC Middleware
|
||||
- Logging middleware
|
||||
- Metrics middleware
|
||||
- Tracing middleware (OpenTelemetry)
|
||||
- Authentication middleware
|
||||
- Rate limiting middleware
|
||||
|
||||
### 5. Code Generation
|
||||
- `Makefile` target for protobuf generation
|
||||
- Generate Go code from `.proto` files
|
||||
- Generate gRPC server and client stubs
|
||||
### 5. gRPC Health Check Service
|
||||
- Standard gRPC health check protocol
|
||||
- Per-service health status
|
||||
- Integration with Consul health checks
|
||||
|
||||
### 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
|
||||
**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.
|
||||
|
||||
## 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
|
||||
```
|
||||
1. **Add Streaming RPCs**
|
||||
- Update existing proto files with streaming RPCs
|
||||
- Implement streaming handlers in services
|
||||
- Update clients to support streaming
|
||||
|
||||
2. **Define Protocol Buffers**
|
||||
- Create `api/proto/` directory
|
||||
- Define `.proto` files for each service
|
||||
- Define messages and services
|
||||
2. **Implement gRPC-Gateway**
|
||||
- Install gRPC-Gateway
|
||||
- Generate gateway code from proto files
|
||||
- Configure gateway endpoints
|
||||
|
||||
3. **Generate gRPC Code**
|
||||
- Create `Makefile` target
|
||||
- Generate Go code from protobuf
|
||||
3. **Enhance Error Handling**
|
||||
- Implement structured error responses
|
||||
- Add error details and metadata
|
||||
- Update error propagation
|
||||
|
||||
4. **Implement gRPC Servers**
|
||||
- Create server implementations
|
||||
- Wrap existing services
|
||||
- Handle errors and validation
|
||||
4. **Add gRPC Middleware**
|
||||
- Create middleware chain
|
||||
- Add logging, metrics, tracing middleware
|
||||
- Integrate with existing observability
|
||||
|
||||
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
|
||||
5. **Implement Health Check Service**
|
||||
- Add gRPC health check service
|
||||
- Integrate with Consul health checks
|
||||
|
||||
## 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
|
||||
- [x] Streaming RPCs work correctly
|
||||
- [x] gRPC-Gateway provides HTTP access to gRPC services
|
||||
- [x] Advanced error handling works across services
|
||||
- [x] gRPC middleware provides observability
|
||||
- [x] Health check service integrates with Consul
|
||||
- [x] All services support advanced gRPC features
|
||||
|
||||
## 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
|
||||
- Support both unary and streaming RPCs
|
||||
- Implement proper error handling
|
||||
- Add OpenTelemetry instrumentation
|
||||
- Support service versioning
|
||||
- Basic gRPC is already implemented in Epic 1 and Epic 2
|
||||
- Focus on advanced features: streaming, gateway, middleware
|
||||
- Maintain backward compatibility with existing gRPC services
|
||||
- Add OpenTelemetry instrumentation to middleware
|
||||
|
||||
## Testing
|
||||
```bash
|
||||
# Generate protobuf code
|
||||
make generate-proto
|
||||
# Test streaming RPCs
|
||||
go test ./services/*/internal/api/... -run Streaming
|
||||
|
||||
# Test gRPC servers
|
||||
go test ./internal/services/grpc/server/...
|
||||
# Test gRPC-Gateway
|
||||
curl http://localhost:8080/api/v1/users/123
|
||||
|
||||
# Test gRPC clients
|
||||
go test ./internal/services/grpc/client/...
|
||||
# Test health check service
|
||||
grpcurl -plaintext localhost:8081 grpc.health.v1.Health/Check
|
||||
```
|
||||
|
||||
## 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
|
||||
- `api/proto/*.proto` - Add streaming RPCs to existing proto files
|
||||
- `internal/server/grpc/middleware.go` - gRPC middleware
|
||||
- `internal/server/grpc/gateway.go` - gRPC-Gateway integration
|
||||
- `internal/server/grpc/health.go` - Health check service
|
||||
- `Makefile` - Add gateway generation target
|
||||
|
||||
|
||||
@@ -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
|
||||
- [Story: 5.7 - gRPC Services](./5.7-grpc-services.md)
|
||||
- **Goal:** Implement gRPC service definitions and clients to enable microservices communication.
|
||||
- **Deliverables:** gRPC service definitions, gRPC servers, gRPC clients, code generation
|
||||
### 5.7 Advanced gRPC Features
|
||||
- [Story: 5.7 - Advanced gRPC Features](./5.7-grpc-services.md)
|
||||
- **Goal:** Enhance gRPC implementation with advanced features (streaming, advanced error handling, gRPC-Gateway).
|
||||
- **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
|
||||
|
||||
@@ -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.
|
||||
- **Deliverables:** Complete OpenTelemetry integration, expanded metrics, enhanced 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 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.
|
||||
- **Deliverables:** Grafana dashboard JSON files, documentation
|
||||
- **Goal:** Create comprehensive Grafana dashboards for monitoring all services.
|
||||
- **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.
|
||||
- **Deliverables:** Rate limiting middleware, configuration
|
||||
- **Goal:** Implement rate limiting primarily at API Gateway level, with per-service rate limiting support.
|
||||
- **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
|
||||
- Errors are reported to Sentry with context
|
||||
- Logs include request IDs and trace IDs
|
||||
- Metrics are exposed and scraped by Prometheus
|
||||
- Rate limiting prevents abuse
|
||||
- Security headers are present
|
||||
- Distributed traces span all services and are visible in Jaeger
|
||||
- Errors are reported to Sentry with service context
|
||||
- Logs include request IDs and trace IDs for correlation across services
|
||||
- Metrics are exposed per service and scraped by Prometheus
|
||||
- Rate limiting prevents abuse (primarily at API Gateway)
|
||||
- Security headers are present on all services
|
||||
- Performance meets SLA (< 100ms p95 for auth endpoints)
|
||||
- Service-level dashboards available in Grafana
|
||||
|
||||
@@ -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.
|
||||
- **Deliverables:** Unit tests (>80% coverage), integration tests, contract tests, load tests
|
||||
- **Goal:** Achieve comprehensive test coverage with unit tests per service, integration tests across services, and contract tests for service APIs.
|
||||
- **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.
|
||||
- **Deliverables:** Enhanced CI pipeline, release workflow, security scanning
|
||||
- **Goal:** Enhance CI/CD pipeline with comprehensive testing for all services, security scanning, and release automation.
|
||||
- **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.
|
||||
- **Deliverables:** Docker images, Docker Compose, deployment guides, developer tooling
|
||||
- **Goal:** Create production-ready Docker images for each service and comprehensive deployment guides for microservices architecture.
|
||||
- **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
|
||||
- Code coverage >80%
|
||||
- All tests pass in CI for all services
|
||||
- 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
|
||||
|
||||
@@ -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
|
||||
- Create `modules/notification/`:
|
||||
### 1. Notification Service
|
||||
- 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
|
||||
- Create `modules/analytics/`:
|
||||
### 2. Analytics Service
|
||||
- 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
|
||||
- [ ] Analytics module works
|
||||
- [ ] Modules demonstrate different patterns
|
||||
- [ ] Modules are well-documented
|
||||
- [x] Notification Service is independently deployable
|
||||
- [x] Analytics Service is independently deployable
|
||||
- [x] Each service has its own entry point and gRPC server
|
||||
- [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
|
||||
- `modules/analytics/` - Analytics module
|
||||
- `cmd/notification-service/main.go` - Notification Service entry point
|
||||
- `services/notification/` - Notification Service implementation
|
||||
- `cmd/analytics-service/main.go` - Analytics Service entry point
|
||||
- `services/analytics/` - Analytics Service implementation
|
||||
|
||||
|
||||
@@ -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
|
||||
- [Story: 8.3 - Additional Modules](./8.3-additional-modules.md)
|
||||
- **Goal:** Create additional sample modules to demonstrate different use cases.
|
||||
- **Deliverables:** Notification module, Analytics module
|
||||
### 8.3 Additional Sample Feature Services
|
||||
- [Story: 8.3 - Additional Services](./8.3-additional-modules.md)
|
||||
- **Goal:** Create additional sample feature services to demonstrate different use cases and patterns.
|
||||
- **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)
|
||||
|
||||
Reference in New Issue
Block a user