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

Story 4.1: Complete Blog Module

Metadata

• Story ID: 4.1
• Title: Complete Blog Module
• Epic: 4 - Sample Feature Module (Blog)
• Status: Pending
• Priority: High
• Estimated Time: 10-12 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.

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.

Deliverables

1. Blog Module Structure

• Create modules/blog/ directory with proper structure:

  modules/blog/
  ├── go.mod
  ├── module.yaml
  ├── internal/
  │   ├── api/
  │   │   └── handler.go
  │   ├── domain/
  │   │   ├── post.go
  │   │   └── post_repo.go
  │   ├── service/
  │   │   └── post_service.go
  │   └── ent/
  │       └── schema/
  │           └── post.go
  └── pkg/
      └── module.go
  

• Initialize go.mod for blog module

2. Module Manifest (modules/blog/module.yaml)

• Define module metadata (name, version, dependencies)
• Define permissions (blog.post.create, read, update, delete)
• Define routes with permission requirements

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)
  • Indexes: author_id, created_at
  • Timestamps: created_at, updated_at
• Generate Ent code for blog module

4. Blog Repository

• PostRepository interface in modules/blog/internal/domain/post_repo.go
• Implementation using Ent client (shared from core)
• CRUD operations: Create, FindByID, FindByAuthor, Update, Delete
• Pagination support

5. Blog Service

• PostService in modules/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)
• 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

Implementation Steps

1. Create Module Structure

   • Create directory structure
   • Initialize go.mod

2. Create Module Manifest

   • Create module.yaml
   • Define permissions and routes

3. Create Domain Model

   • Create Post entity
   • Create Ent schema
   • Generate Ent code

4. Create Repository

   • Create repository interface
   • Implement using Ent

5. Create Service

   • Create service with business logic
   • Add validation and authorization

6. Create API Handlers

   • Create handlers
   • Add authorization middleware
   • Register routes

7. Create Module Implementation

   • Implement IModule interface
   • Register module

8. Integrate with Platform

   • Import module in main
   • Generate permissions
   • Test integration

9. Add Tests

   • Create integration tests
   • Create unit tests

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

Related ADRs

• ADR-0029: Microservices Architecture
• ADR-0030: Service Communication Strategy
• See module framework ADRs

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