NovusCore.Shared.Data 2.2.4

RetireAix Shared Service

A Clean Architecture .NET 8 Web API microservice following CQRS pattern with EF Core and Dapper.

🏗️ Architecture

This project follows a pragmatic architecture pattern optimized for 40 microservices sharing a single PostgreSQL database:

┌─────────────────────────────────────────┐
│         Presentation (WebApi)            │
├─────────────────────────────────────────┤
│   Infrastructure   │   Application      │
├─────────────────────────────────────────┤
│   Shared.Data (NuGet) │    Shared       │
└─────────────────────────────────────────┘

Layers

• Shared.Data (NuGet v2.0.0): Entities, repositories, migrations - shared across 40 microservices
• Shared: Common DTOs, models, and utilities
• Application: CQRS implementation with MediatR (Commands/Queries/Handlers)
• Infrastructure: AWS services (S3, Secrets Manager, SQS), Redis, Email
• WebApi: REST API controllers and middleware

🚀 Getting Started

Prerequisites

• .NET 8 SDK
• PostgreSQL 16+
• Redis (optional for caching)
• AWS Account (optional for cloud services)

Installation

1. Clone the repository

   git clone https://github.com/your-org/retireaix-shared-service.git
   cd retireaix-shared-service
   

2. Restore dependencies

   dotnet restore
   

3. Update connection string

   Edit src/RetireAix.SharedService.WebApi/appsettings.json:

   "ConnectionStrings": {
     "DefaultConnection": "Host=localhost;Port=5432;Database=sharedservice_db;Username=postgres;Password=yourpassword;"
   }
   

4. Create database migration

   cd src/RetireAix.Shared.Data
   dotnet ef migrations add InitialCreate --startup-project ../RetireAix.SharedService.WebApi
   dotnet ef database update --startup-project ../RetireAix.SharedService.WebApi
   

5. Run the application

   cd src/RetireAix.SharedService.WebApi
   dotnet run
   

6. Access Swagger UI

   Navigate to: https://localhost:5001 or http://localhost:5000

📁 Project Structure

RetireAix.SharedService/
├── src/
│   ├── RetireAix.Shared.Data/              # NuGet Package: Entities, Repos, Migrations
│   ├── RetireAix.SharedService.Shared/     # Models, DTOs, Constants
│   ├── RetireAix.SharedService.Application/    # CQRS, Handlers, Validators
│   ├── RetireAix.SharedService.Infrastructure/ # AWS, Redis, Email services
│   └── RetireAix.SharedService.WebApi/         # Controllers, Middleware, Health Checks
├── tests/
│   └── RetireAix.SharedService.Tests/
└── docs/
    ├── arch.md
    ├── CONFIGURATION_GUIDE.md
    ├── IMPLEMENTATION_GUIDE.md
    └── PROJECT_STRUCTURE.md

🛠️ Technology Stack

📊 Database

Commands (Write Operations)

• Uses EF Core with change tracking
• Automatic audit trail (CreatedAt, UpdatedAt, etc.)
• Soft delete support
• Transaction management via Unit of Work

Queries (Read Operations)

• Uses Dapper for high-performance reads
• Raw SQL queries
• No change tracking overhead
• Direct DTO mapping

🔧 Configuration

Environment Variables

# Database
ConnectionStrings__DefaultConnection="Host=localhost;Port=5432;Database=mydb;Username=postgres;Password=pass;"

# AWS
AWS_REGION="us-east-1"
AWS_ACCESS_KEY_ID="your-access-key"
AWS_SECRET_ACCESS_KEY="your-secret-key"

# Redis
Redis__ConnectionString="localhost:6379"

# Email
Email__SmtpHost="smtp.gmail.com"
Email__SmtpPort="587"
Email__Username="your-email@gmail.com"
Email__Password="your-app-password"

🏥 Health Checks

The service provides comprehensive health monitoring through multiple endpoints:

Health Check Endpoints

Complete Health Check

GET /health

Returns detailed health status of all dependencies:

{
  "status": "Healthy",
  "totalDuration": 45.23,
  "checks": [
    {
      "name": "postgresql",
      "status": "Healthy",
      "description": "No description provided",
      "duration": 23.45,
      "tags": ["db", "sql", "postgresql", "ready"]
    },
    {
      "name": "redis",
      "status": "Healthy",
      "description": "No description provided",
      "duration": 12.34,
      "tags": ["cache", "redis", "ready"]
    },
    {
      "name": "aws-s3",
      "status": "Healthy",
      "description": "No description provided",
      "duration": 9.44,
      "tags": ["aws", "s3", "storage", "ready"]
    }
  ],
  "timestamp": "2026-01-20T10:30:00Z"
}

Readiness Probe (Kubernetes)

GET /health/ready

Checks if the application is ready to serve traffic. Returns only checks tagged with "ready".

Liveness Probe (Kubernetes)

GET /health/live

Simple check to verify the application is running. Always returns "Healthy" if the app responds.

Health Check Configuration

Health checks are automatically configured for:

• PostgreSQL - Database connectivity (5s timeout)
• Redis - Cache connectivity (3s timeout)
• AWS S3 - Storage service availability (5s timeout)

Configure thresholds in appsettings.json:

"HealthChecks": {
  "TimeoutSeconds": {
    "PostgreSQL": 5,
    "Redis": 3,
    "S3": 5
  }
}

Kubernetes Integration

Use these probes in your Kubernetes deployment:

livenessProbe:
  httpGet:
    path: /health/live
    port: 80
  initialDelaySeconds: 10
  periodSeconds: 30

readinessProbe:
  httpGet:
    path: /health/ready
    port: 80
  initialDelaySeconds: 5
  periodSeconds: 10

🧪 Testing

# Run all tests
dotnet test

# Run tests with coverage
dotnet test /p:CollectCoverage=true

🐳 Docker

Build Image

docker build -t retireaix-shared-service:latest .

Run with Docker Compose

docker-compose up -d

✨ Production-Ready Features

This service includes enterprise-grade features for production deployments:

Observability & Monitoring

• ✅ Correlation ID Tracking - Distributed tracing across microservices
• ✅ Enhanced Logging - Structured logs with Serilog (IP, UserAgent, timing)
• ✅ Advanced Health Checks - Multiple endpoints with detailed JSON responses
  • /health - Complete health check (PostgreSQL, Redis, AWS S3)
  • /health/ready - Readiness probe for Kubernetes
  • /health/live - Liveness probe for container orchestration
• ✅ Request Logging - Every request logged with enriched context

Resilience & Reliability

• ✅ Retry Policies - Automatic retry with exponential backoff (Polly)
• ✅ Circuit Breaker - Prevent cascade failures
• ✅ EF Core Retry - Database connection resilience (3 retries, 30s delay)
• ✅ Rate Limiting - IP-based rate limiting (100 req/min)

Performance

• ✅ Response Compression - Gzip compression for JSON/XML
• ✅ Response Caching - HTTP-level caching for GET requests
• ✅ Memory Cache - In-process caching alongside Redis
• ✅ Async/Await - All I/O operations are asynchronous

Security

• ✅ HSTS Headers - Force HTTPS in production
• ✅ Input Validation - FluentValidation on all commands
• ✅ SQL Injection Prevention - Parameterized queries
• ✅ Error Information Hiding - Generic errors in production
• ✅ CORS Configuration - Cross-origin request control

API Features

• ✅ API Versioning - URL segment + header versioning
• ✅ Swagger/OpenAPI - Interactive API documentation
• ✅ Global Exception Handling - Consistent error responses
• ✅ Result Pattern - Standardized response format

Data Access

• ✅ CQRS Pattern - Separate read/write models
• ✅ Dapper snake_case Mapping - Auto-map PostgreSQL columns
• ✅ Soft Delete - Logical deletion with audit trail
• ✅ Centralized Configuration - Strongly-typed config with validation

See IMPLEMENTATION_GUIDE.md for detailed documentation.

📖 Documentation

• Implementation Guide - Complete feature documentation
• Configuration Guide - Environment setup and settings
• Architecture Documentation
• Clean Architecture Guide
• API Documentation

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License.

👥 Team

• RetireAix Development Team
• Contact: support@retireaix.com

🔗 Related Projects

• RetireAix-PlanSponsor
• RetireAix Contact Management
• RetireAix Document Service

Generated with ❤️ using Pragmatic Architecture and CQRS patterns