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
2025-11-06 08:47:27 +01:00
parent cab7cadf9e
commit 38a251968c
47 changed files with 3190 additions and 1613 deletions
--- a/docs/content/stories/epic4/4.1-blog-module.md
+++ b/docs/content/stories/epic4/4.1-blog-module.md
@@ -1,169 +1,194 @@
-# Story 4.1: Complete Blog Module
+# Story 4.1: Complete Blog Service

 ## Metadata
 - **Story ID**: 4.1
- **Title**: Complete Blog Module
- **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

--- a/docs/content/stories/epic4/README.md
+++ b/docs/content/stories/epic4/README.md
@@ -1,31 +1,39 @@
-# Epic 4: Sample Feature Module (Blog)
+# Epic 4: Sample Feature Service (Blog Service)

 ## Overview
-Create a complete sample module (Blog) to demonstrate the framework, showing how to add routes, permissions, database entities, and services. The Blog module is an independent service that uses service clients to communicate with core services. Provide reference implementation for future developers.
+Create a complete sample feature service (Blog Service) to demonstrate the framework. The Blog Service is an independent service with its own entry point (`cmd/blog-service/`), gRPC server, and database schema. It uses service clients to communicate with core services (Auth, Identity, Authz, Audit). This serves as a reference implementation for future developers creating feature services.
+
+**Key Principle:** Blog Service demonstrates how to create a feature service that integrates with the platform using service clients and Consul service discovery.

 ## Stories

-### 4.1 Complete Blog Module
- [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