NovusCore.AuditService.Contracts 1.0.1

RetireAix Audit Service

Centralized audit microservice for the RetireAix platform. This service consumes audit events from 40+ microservices via Amazon SQS, enriches and stores them in PostgreSQL, and provides query APIs for compliance, debugging, and reporting.

Architecture

• AuditService.API: REST API for querying audit logs
• AuditService.Worker: Background service that consumes SQS messages and stores audit logs
• AuditService.Contracts: Shared NuGet package for audit event contracts
• AuditService.Application: Business logic and CQRS handlers
• AuditService.Domain: Domain entities
• AuditService.Infrastructure: Data access with EF Core (writes) and Dapper (reads)

Technology Stack

• .NET 8
• PostgreSQL 16
• Amazon SQS
• Entity Framework Core 8 (writes)
• Dapper (reads)
• MediatR (CQRS)
• FluentValidation
• Serilog

Quick Start with Docker

# Start all services (PostgreSQL, LocalStack, API, Worker)
docker-compose up -d

# Check API health
curl http://localhost:5100/health

# View API documentation
open http://localhost:5100/swagger

Local Development Setup

Prerequisites

• .NET 8 SDK
• PostgreSQL 16
• Docker and Docker Compose (for LocalStack)
• AWS CLI (for testing)

Running Locally

1. Start infrastructure:

docker-compose up -d postgres localstack localstack-init

2. Run API:

cd src/AuditService.API
dotnet run

3. Run Worker (in another terminal):

cd src/AuditService.Worker
dotnet run

Testing SQS Integration

Send a test message to LocalStack SQS:

aws --endpoint-url=http://localhost:4566 sqs send-message \
  --queue-url http://localhost:4566/000000000000/dev_retireaix-audit-queue \
  --message-body '{"entityName":"TestEntity","recordId":"123","action":"Added","sourceService":"TestService","timestamp":"2025-01-01T00:00:00Z"}'

Check DLQ for failed messages:

aws --endpoint-url=http://localhost:4566 sqs receive-message \
  --queue-url http://localhost:4566/000000000000/dev_retireaix-audit-dlq

API Endpoints

Query Endpoints

• GET /api/audit/entity/{entityName}/{recordId} - Get audit trail for entity
• GET /api/audit/user/{userId} - Get audit events by user
• GET /api/audit/trace/{traceId} - Get audit events by trace ID
• GET /api/audit/search - Advanced search with filters
• GET /api/audit/services - Get service summaries
• GET /api/audit/entities - Get entity summaries
• GET /health - Health check

Example Query

# Get audit trail for an entity
curl "http://localhost:5100/api/audit/entity/Employer/123?page=1&pageSize=10"

# Search audit events
curl "http://localhost:5100/api/audit/search?from=2025-01-01&to=2025-12-31&sourceService=PlanSponsor"

Database Setup

The database schema is automatically created when PostgreSQL starts using the migration scripts in the migrations/ folder.

To manually run migrations:

psql -h localhost -U postgres -d audit_db -f migrations/000_create_audit_logs.sql
psql -h localhost -U postgres -d audit_db -f migrations/001_add_source_service.sql

Building the Solution

# Restore dependencies
dotnet restore

# Build all projects
dotnet build

# Run tests (when available)
dotnet test

# Pack Contracts NuGet package
cd src/AuditService.Contracts
dotnet pack -c Release

Configuration

API (appsettings.json)

{
  "ConnectionStrings": {
    "AuditDb": "Host=localhost;Database=******;Username=******;Password=xxx"
  }
}

Worker (appsettings.json)

{
  "ConnectionStrings": {
    "AuditDb": "Host=localhost;Database=******;Username=******;Password=xxx"
  },
  "Aws": {
    "Region": "us-east-1",
    "Sqs": {
      "QueueUrl": "**************",
      "DeadLetterQueueUrl": "**************"
    }
  }
}

Project Structure

AuditService/
├── src/
│   ├── AuditService.Contracts/       # Shared contracts (NuGet package)
│   ├── AuditService.Domain/          # Domain entities
│   ├── AuditService.Application/     # CQRS handlers, DTOs, interfaces
│   ├── AuditService.Infrastructure/  # EF Core, Dapper, repositories
│   ├── AuditService.API/             # REST API
│   └── AuditService.Worker/          # SQS consumer
├── migrations/                        # Database migrations
├── docker-compose.yml
└── AuditService.sln

Publishing Contracts Package

cd src/AuditService.Contracts
dotnet pack -c Release
dotnet nuget push bin/Release/AuditService.Contracts.1.0.0.nupkg --source "your-nuget-feed"

Monitoring

• Health endpoint: GET /health
• Logs: Console output via Serilog
• Metrics: Available via health checks

License

Proprietary - RetireAix Platform