goplt/docs/content/stories/epic4/4.1-blog-module.md

Story 4.1: Complete Blog Service

Metadata

• Story ID: 4.1
• Title: Complete Blog Service
• Epic: 4 - Sample Feature Service (Blog Service)
• Status: Pending
• Priority: High
• Estimated Time: 12-15 hours
• Dependencies: 3.1, 3.2, 3.3, 2.3

Goal

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 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 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:

  cmd/blog-service/
  └── main.go                    # Service entry point
  
  services/blog/
  ├── go.mod
  ├── module.yaml
  ├── api/
  │   └── proto/
  │       └── blog.proto         # gRPC service definition
  ├── internal/
  │   ├── api/
  │   │   └── server.go          # gRPC server implementation
  │   ├── domain/
  │   │   ├── post.go
  │   │   └── post_repo.go
  │   ├── service/
  │   │   └── post_service.go
  │   └── database/
  │       └── client.go          # Database connection (blog schema)
  └── ent/
      └── schema/
          └── post.go
  

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 gRPC service information

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 service
• Database connection with blog schema

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

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 via AuthzServiceClient
• Uses service clients for inter-service communication:
  • IdentityServiceClient - to get user information
  • AuthzServiceClient - for authorization checks
  • AuditServiceClient - for audit logging

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 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
   • Create module.yaml

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 (blog schema)
   • Generate Ent code

5. Create Repository

   • Create repository interface
   • Implement using Ent (blog schema)

6. Create Service

   • Create service with business logic
   • Integrate with service clients (Identity, Authz, Audit)
   • Add validation and authorization

7. Implement gRPC Server

   • Create gRPC server implementation
   • Wire up handlers
   • Start server

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 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 (8091)
• CreatePost RPC requires blog.post.create permission (via AuthzServiceClient)
• User can create, read, update, delete posts via gRPC
• 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
• Integration test: full CRUD flow works via gRPC
• Service migrations run on startup

Related ADRs

• ADR-0029: Microservices Architecture
• ADR-0030: Service Communication Strategy
• ADR-0033: Service Discovery Implementation

Testing

# 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

• 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