AtlasNuc 1.0.5

AtlasCore

Shared contracts for Atlas platform services.

Purpose

AtlasCore provides reusable, service-agnostic audit contracts so all services can publish and query audit events in a consistent format.

Current shared contracts live under Audit/Contracts:

• AuditEventDto (includes ActorName and EventTimeUtc for actor identity and timestamp)
• AuditContext
• AuditQueryRequest
• UserType, ResultStatus
• AuditActionCodes (baseline/common examples)

Shared authorization artifacts live under Authorization:

• Contracts/IUserCategoryAccessor
• Contracts/ApiErrorResponse
• Filters/AdminUserFilter

Action Code Strategy (Generic + Reusable)

Do not rely on a single global enum/list for every service action.

Use this model:

1. AtlasCore keeps only common baseline action codes.
2. Each service defines its own local action catalog.
3. All action codes follow one naming convention.

Naming Convention

Use:

<Domain>.<Subdomain>.<Action>

Examples:

• Customer.Transfer.Initiated
• Admin.User.Disabled
• System.Integration.Call
• Loan.Application.Approved

Rules:

• PascalCase segments
• Dot-separated hierarchy
• Stable codes (append new, avoid renaming old)

Example: Service-Owned Action Catalog

namespace AtlasDigitalBank.Service.Audit;

public static class DigitalBankAuditActions
{
    public const string CustomerTransferInitiated = "Customer.Transfer.Initiated";
    public const string CustomerTransferCompleted = "Customer.Transfer.Completed";
    public const string AdminFeatureToggled = "Admin.Feature.Toggled";
    public const string LoanApplicationApproved = "Loan.Application.Approved";
}

Example: Publishing an Audit Event

using AtlasCore.Audit.Contracts;

var evt = new AuditEventDto
{
    UserType = UserType.Customer,
    UserId = customerId,
    ServiceName = "AtlasDigitalBank",
    ActionCode = DigitalBankAuditActions.CustomerTransferInitiated,
    ResultStatus = ResultStatus.Success,
    TargetType = "Wallet",
    TargetId = walletId,
    Context = new AuditContext
    {
        Channel = "API",
        CorrelationId = correlationId,
        AppVersion = appVersion
    }
};

Example: Querying with ATLAS Pagination Style

AuditQueryRequest follows the ATLAS request pattern:

• PageNumber
• PageSize

var query = new AuditQueryRequest
{
    UserType = UserType.Admin,
    ServiceName = "AtlasDigitalBank",
    FromUtc = DateTime.UtcNow.AddDays(-7),
    ToUtc = DateTime.UtcNow,
    PageNumber = 1,
    PageSize = 50
};

API Response Pattern

For consistency with existing ATLAS API style, list endpoints should return:

• list payload in Result
• total records in top-level Count

This avoids embedding custom paged wrapper objects in shared contracts.

Shared Admin Authorization Filter

AdminUserFilter is now reusable from AtlasCore.Authorization.Filters and checks that the current user category is AdminUser.

To use it in a service:

using AtlasCore.Authorization.Contracts;
using AtlasCore.Authorization.Filters;

public sealed class AuthUserCategoryAccessor : IUserCategoryAccessor
{
    private readonly IAuthUser _authUser;

    public AuthUserCategoryAccessor(IAuthUser authUser)
    {
        _authUser = authUser;
    }

    public string? UserCategory => _authUser.UserCategory;
}

services.AddScoped<IUserCategoryAccessor, AuthUserCategoryAccessor>();
services.AddScoped<AdminUserFilter>();

RabbitMQ Ingress Contract (Shared)

Use the shared messaging contracts under AtlasCore.Audit.Messaging to standardize producer and consumer behavior across services.

Shared types:

• AuditIngressEnvelope
• AuditIngressHeaders
• AuditIngressOptions
• AuditIngressValidationCode
• AuditIngressValidationResult

Producer Example

using System.Text;
using System.Text.Json;
using AtlasCore.Audit.Contracts;
using AtlasCore.Audit.Messaging;

var evt = new AuditEventDto
{
    EventId = Guid.NewGuid().ToString("N"),
    EventTimeUtc = DateTime.UtcNow,
    UserType = UserType.Customer,
    UserId = "cus-001",
    ServiceName = "ATLAS",
    ActionCode = "Transfer.Initiated",
    ResultStatus = ResultStatus.Success
};

var envelope = new AuditIngressEnvelope
{
    SchemaVersion = "1.0",
    Event = evt
};

var body = Encoding.UTF8.GetBytes(JsonSerializer.Serialize(envelope));
var props = channel.CreateBasicProperties();
props.Persistent = true;
props.MessageId = evt.EventId;
props.Headers = new Dictionary<string, object>
{
    [AuditIngressHeaders.EventType] = Encoding.UTF8.GetBytes(AuditIngressHeaders.DefaultEventType),
    [AuditIngressHeaders.ServiceName] = Encoding.UTF8.GetBytes(evt.ServiceName),
    [AuditIngressHeaders.SchemaVersion] = Encoding.UTF8.GetBytes(envelope.SchemaVersion)
};

channel.BasicPublish("atlas_audit_exchange", "atlas.customer.transfer", props, body);

Consumer Behavior

Consumers should validate:

1. Payload can be deserialized to AuditIngressEnvelope
2. schemaVersion matches expected version
3. Required headers are present and valid
4. Required AuditEventDto fields are present

When validation fails, reject-route with deterministic code using AuditIngressValidationCode (for example: reject.payload-invalid-json).

Rollout Guidance

1. Add AtlasNuc 1.0.4 in producer and consumer services.
2. Start with AllowLegacyPayload=true only during migration.
3. Disable legacy mode after all producers publish AuditIngressEnvelope with required headers.