goplt/docs/content/stories/epic2/2.5-audit-logging.md

Story 2.5: Audit Service - Audit Logging

Metadata

• Story ID: 2.5
• Title: Audit Service - Audit Logging
• Epic: 2 - Core Services (Authentication & Authorization)
• Status: Pending
• Priority: High
• Estimated Time: 6-8 hours
• Dependencies: 1.1, 1.2, 1.5, 1.7

Goal

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

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

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

• Audit Service is independently deployable
• Service entry point exists at cmd/audit-service/main.go
• Service registers with Consul on startup
• gRPC server starts on configured port (8084)
• Record RPC stores audit log entries
• Query RPC retrieves audit logs with filters
• Audit logs include complete context (actor, action, target, metadata)
• Audit logs are immutable (no updates/deletes)
• Service has its own database connection (audit schema)
• AuditLog entity schema is defined and migrated
• Other services can use AuditServiceClient to record events
• Service can be discovered by other services via Consul
• Health check endpoint works for Consul

Related ADRs

• ADR-0020: Audit Logging Storage
• ADR-0029: Microservices Architecture
• ADR-0030: Service Communication Strategy
• ADR-0033: Service Discovery Implementation

Testing

# 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

• 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