IMPORTANT Server Guidelines

• ALWAYS Use Primary Constructors for classes.
• ALWAYS Prefer record types for immutable data structures.
• NEVER mix multiple classes or DTOs in a single file, even if they are small. Filename ALWAYS matches the class or DTO name, for example UserDto.cs for a UserDto class.
• Private fields should NOT be prefixed with _ (e.g., repository not _repository).
• Add (.) to the end of all server-side log messages.
• Use string? over string for nullable strings.
• Use var for local variables when type is obvious.
• Don't use Regions in code files.
• Use Collection initializers for collections: instead of new List<string>(), use new() { "item1", "item2" }, and instead of list.ToArray() use [.. list].
• Use Anonymous function static: instead of list.Select(x => new Dto(x.SameProperty)), use list.Select(static x => new Dto(x.SameProperty)).
• ALWAYS use sealed accessor for classes or records if not intended for inheritance.
• ALWAYS use internal accessor for internal classes or records.
• NEVER inject or create HttpClient and IHttpClientFactory, instead use the IRestClient interface.
• NEVER register services directly in IServiceCollection. Instead, use the ITransientService, IScopedService, or ISingletonService interfaces to register services with the appropriate lifetimes.
• ALWAYS use ILogger with Structured logging to log, no string interpolation and no other logging methods.
• ALWAYS use cancellation tokens for asynchronous methods.
• ALWAYS use IMemoryCore for time-based in-memory caching, NEVER use IMemoryCache.
• ALWAYS use Data Transfer Objects (DTO) for API communication, validated with attributes.
• ALWAYS use x as a parameter name in lambdas and anonymous functions.
• If any backend changes are made, run dotnet build in the root and ensure no build errors for the entire solution.

Code Organization Principles

Avoid Unnecessary Wrapper Methods

Rule: Do NOT create wrapper methods for specific cases that simply call another method with fixed parameters. Call the base method directly instead.

Example - DON'T:

// ❌ Don't create this wrapper method for a single use case:
public async Task<int> CreateAgentHistoryClearedMessageAsync(int sessionId)
{
    var request = new CreateMessageRequest(
        Type: MessageType.System,
        Content: "Agent history has been cleared",
        Status: MessageStatus.Done
    );
    return await CreateMessageAsync(sessionId, request);
}

Example - DO:

// ✅ Instead, call CreateMessageAsync directly where needed:
await messageService.CreateMessageAsync(
    sessionId,
    new CreateMessageRequest(
        MessageType.System,
        "Agent history has been cleared",
        MessageStatus.Done
    )
);

When to create a helper method:

• When there's complex logic beyond just parameter mapping
• When the same combination is used in multiple places (3+ times)
• When the method provides meaningful abstraction or validation