Files
sor/Server/architecture.md
T
0f95a0721b Add C# programming architecture and update tech stack
- Server/architecture.md: full programming architecture reference in C# (.NET 8)
  covering repo/project structure, three-layer handler→service→repository pattern,
  multi-service runner (ENABLED_SERVICES env var for N services per box), DI,
  config (IOptions), gRPC handler pattern, NATS pub/sub, Redis, EF Core + PostgreSQL,
  Serilog logging, error handling (ServiceResult + exceptions), health checks,
  testing patterns (xUnit + Moq + FluentAssertions), naming conventions, and hard rules
- Server/initial-plan.md: add C# 12 (.NET 8), EF Core, Serilog to tech stack table;
  add C# to Decided table; reference architecture.md

Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>
2026-02-24 13:46:44 -05:00

55 KiB

SOR Server — Programming Architecture

This document defines the strict, repeatable architecture every service in the SOR backend follows. It is the canonical source of truth for how code is organized, how services communicate, and how patterns are applied consistently across the codebase.

Language: C# 12 (.NET 8) Build system: MSBuild via the .sln solution file Repo layout: Monorepo — all services and shared code live in one repository


Table of Contents

  1. Why C# / .NET 8
  2. Repository Structure
  3. Service Project Layout (3-Layer Pattern)
  4. Shared Library — SOR.Shared
  5. Protobuf Contracts — SOR.Shared.Proto
  6. Multi-Service Runner — SOR.Host
  7. Dependency Injection
  8. Configuration System
  9. gRPC Handlers
  10. NATS Integration
  11. Redis Integration
  12. Database — EF Core + PostgreSQL
  13. Logging — Serilog
  14. Error Handling
  15. Health Checks
  16. Testing Patterns
  17. Naming Conventions
  18. Hard Rules

1. Why C# / .NET 8

C# is a statically typed, compiled language in the same family as Java and Kotlin, but with a cleaner modern syntax and exceptional first-class support for async/await, which is critical for a server that handles thousands of concurrent connections.

.NET 8 is the current long-term support (LTS) release. It includes:

  • Native AOT compilation (faster startup, smaller containers — optional, enabled per service)
  • System.Threading.Channels — lock-free async queues (used in Gateway for message dispatch)
  • Top-level programs — less boilerplate in Program.cs
  • Source generators — compile-time code generation for Protobuf and serialization

ASP.NET Core is the web framework built into .NET. It hosts HTTP endpoints, gRPC endpoints, and WebSocket connections in the same process with a unified middleware pipeline. No external web framework is needed.


2. Repository Structure

SOR/
└── Server/
    ├── SOR.sln                          # Visual Studio solution — lists all projects
    ├── Directory.Build.props            # MSBuild properties shared across ALL projects
    ├── Directory.Packages.props         # Central NuGet package version management
    │
    ├── src/
    │   ├── SOR.Host/                    # Multi-service runner (the deployable binary)
    │   ├── SOR.Shared/                  # Shared utilities, base classes, interfaces
    │   ├── SOR.Shared.Proto/            # Protobuf .proto files + generated C# code
    │   │
    │   ├── SOR.Gateway/                 # Gateway service module
    │   ├── SOR.Auth/                    # Auth service module
    │   ├── SOR.Game/                    # Game service module
    │   ├── SOR.Chat/                    # Chat service module
    │   ├── SOR.Collection/              # Collection service module
    │   ├── SOR.Bazaar/                  # Bazaar service module
    │   ├── SOR.Admin/                   # Admin service module
    │   ├── SOR.Leaderboard/             # Leaderboard service module
    │   └── SOR.Content/                 # Content service module
    │
    └── tests/
        ├── SOR.Auth.Tests/
        ├── SOR.Game.Tests/
        ├── SOR.Chat.Tests/
        ├── SOR.Collection.Tests/
        ├── SOR.Bazaar.Tests/
        ├── SOR.Leaderboard.Tests/
        └── SOR.Content.Tests/

Directory.Build.props

This file applies MSBuild properties to every project without repeating them. It lives at the Server/ level and is automatically picked up by all .csproj files underneath it.

<!-- Server/Directory.Build.props -->
<Project>
  <PropertyGroup>
    <!-- Target .NET 8 in every project -->
    <TargetFramework>net8.0</TargetFramework>

    <!-- Enforce nullable reference types: the compiler will warn when a variable
         that can be null is used without a null check. This prevents NullReferenceException
         at runtime by catching issues at compile time. -->
    <Nullable>enable</Nullable>

    <!-- Enable all C# language features for the current version -->
    <LangVersion>latest</LangVersion>

    <!-- Treat compiler warnings as errors — keeps code quality high -->
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>

    <!-- Implicit using statements: automatically imports the most common
         namespaces (System, System.Linq, System.Collections.Generic, etc.)
         so every file doesn't need a wall of `using` directives at the top -->
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>
</Project>

Directory.Packages.props

Central package version management. All NuGet package versions are declared here once. Individual .csproj files reference package names without version numbers — they inherit from here. This prevents version drift across projects.

<!-- Server/Directory.Packages.props -->
<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>

  <ItemGroup>
    <!-- gRPC server implementation for ASP.NET Core -->
    <PackageVersion Include="Grpc.AspNetCore" Version="2.62.0" />

    <!-- Official NATS client for .NET -->
    <PackageVersion Include="NATS.Net" Version="2.3.0" />

    <!-- StackExchange.Redis — battle-tested Redis client for .NET -->
    <PackageVersion Include="StackExchange.Redis" Version="2.7.33" />

    <!-- Entity Framework Core — the ORM (Object-Relational Mapper) that lets
         us work with database rows as C# objects instead of raw SQL -->
    <PackageVersion Include="Microsoft.EntityFrameworkCore" Version="8.0.0" />

    <!-- PostgreSQL driver for EF Core (Npgsql) -->
    <PackageVersion Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="8.0.0" />

    <!-- EF Core design-time tools (migrations, scaffolding) -->
    <PackageVersion Include="Microsoft.EntityFrameworkCore.Design" Version="8.0.0" />

    <!-- Serilog: structured logging library -->
    <PackageVersion Include="Serilog.AspNetCore" Version="8.0.0" />
    <PackageVersion Include="Serilog.Sinks.Console" Version="5.0.0" />
    <PackageVersion Include="Serilog.Sinks.Seq" Version="7.0.0" />

    <!-- xUnit: the testing framework -->
    <PackageVersion Include="xunit" Version="2.6.6" />
    <PackageVersion Include="xunit.runner.visualstudio" Version="2.5.7" />

    <!-- Moq: mock objects for unit tests -->
    <PackageVersion Include="Moq" Version="4.20.70" />

    <!-- FluentAssertions: readable assertion syntax in tests -->
    <PackageVersion Include="FluentAssertions" Version="6.12.0" />

    <!-- Microsoft test host for integration tests -->
    <PackageVersion Include="Microsoft.AspNetCore.Mvc.Testing" Version="8.0.0" />
  </ItemGroup>
</Project>

3. Service Project Layout

Every service follows the identical three-layer structure. No exceptions.

src/SOR.Auth/
├── SOR.Auth.csproj
├── ServiceRegistration.cs        # The ONE public entry point for this module
│
├── Handlers/                     # Layer 1 — receives external calls (gRPC, NATS)
│   └── AuthGrpcHandler.cs        # Implements the gRPC service contract
│
├── Services/                     # Layer 2 — all business logic lives here
│   ├── IAuthService.cs           # Interface (used for testing / substitution)
│   └── AuthService.cs            # Implementation
│
├── Repositories/                 # Layer 3 — all database access lives here
│   ├── IAuthRepository.cs        # Interface
│   └── AuthRepository.cs        # Implementation using EF Core
│
├── Models/                       # Domain objects used inside this service
│   ├── User.cs
│   └── SessionToken.cs
│
└── Data/                         # EF Core database context for this service
    ├── AuthDbContext.cs
    └── Migrations/               # Auto-generated by EF Core; tracks schema changes

The Three Layers

Layer 1 — Handlers receive the incoming request from outside. They are thin:

  • Deserialize the incoming message
  • Call the appropriate Service method
  • Serialize and return the response
  • No business logic here

Layer 2 — Services contain all business logic:

  • Validation
  • Orchestrating calls to repositories and other services
  • Applying rules
  • Never talk directly to the database — always go through repositories

Layer 3 — Repositories contain all database access:

  • Query the database using EF Core
  • Return domain model objects (not raw database rows)
  • No business logic here

Why this separation matters

Each layer can be tested independently. A service test mocks the repository so no database is needed. A handler test mocks the service so no business logic runs. This makes tests fast, reliable, and easy to write.

ServiceRegistration.cs — the module's public contract

Every service module exposes exactly ONE public method: a static extension method called Add{ServiceName}Service. This is how SOR.Host enables a service. Nothing else in the module is public unless it must be.

// src/SOR.Auth/ServiceRegistration.cs

// 'namespace' groups related code together and prevents naming collisions.
// Convention: namespace matches folder path from solution root.
namespace SOR.Auth;

// 'static class' means this class can never be instantiated — it only holds
// static methods. Extension method containers are always static classes.
public static class ServiceRegistration
{
    // This is an extension method on IServiceCollection. The 'this' keyword
    // on the first parameter is what makes it an extension method — it can
    // be called as if it were a method on IServiceCollection itself:
    //   builder.Services.AddAuthService(builder.Configuration)
    //
    // IServiceCollection is the .NET dependency injection container that tracks
    // everything the app needs. You register things into it during startup, and
    // the framework injects them wherever they're needed at runtime.
    public static IServiceCollection AddAuthService(
        this IServiceCollection services,
        IConfiguration configuration)
    {
        // Bind the "Auth" section of appsettings.json to a typed options class.
        // IOptions<AuthOptions> can then be injected anywhere in this service.
        services.Configure<AuthOptions>(configuration.GetSection("Auth"));

        // Register the database context scoped to each request.
        // "Scoped" means one instance per request — all code within a single
        // request shares the same DbContext instance.
        services.AddDbContext<AuthDbContext>(options =>
            options.UseNpgsql(configuration.GetConnectionString("Auth")));

        // Register the repository and service.
        // AddScoped<interface, implementation>: whenever something asks for
        // IAuthRepository, the DI container creates an AuthRepository.
        services.AddScoped<IAuthRepository, AuthRepository>();
        services.AddScoped<IAuthService, AuthService>();

        // Register the gRPC handler. MapGrpcService (called later in Host)
        // routes incoming gRPC calls to this handler class.
        services.AddGrpc();

        return services;
    }
}

4. Shared Library — SOR.Shared

SOR.Shared is the one library every other project references. It contains code that would otherwise be duplicated across services. Strict rule: add to SOR.Shared only when two or more services need the same code. Do not preemptively add things here.

src/SOR.Shared/
├── SOR.Shared.csproj
│
├── Interfaces/
│   └── ISorService.cs             # Marker interface every service implements
│
├── Redis/
│   ├── RedisConnectionFactory.cs  # Builds and caches the Redis connection
│   └── RedisKeys.cs               # All Redis key name constants in one place
│
├── Nats/
│   ├── NatsConnectionFactory.cs   # Builds the NATS connection
│   └── NatsSubjects.cs            # All NATS subject name constants in one place
│
├── Models/
│   └── ServiceResult.cs           # Standardized operation result wrapper
│
├── Exceptions/
│   └── SorException.cs            # Base exception with error codes
│
└── Extensions/
    └── StringExtensions.cs        # Utility methods on string, Guid, etc.

ServiceResult — the standard return type

Business logic methods return ServiceResult<T> instead of throwing exceptions for expected failures (user not found, invalid password, etc.). Exceptions are reserved for truly unexpected failures (database down, out of memory).

// src/SOR.Shared/Models/ServiceResult.cs
namespace SOR.Shared.Models;

// A 'record' is an immutable data structure in C#. It generates equality checks,
// ToString(), and other utilities automatically based on its properties.
// The <T> makes it generic — T is replaced with the actual type at the call site,
// e.g., ServiceResult<User> or ServiceResult<string>.
public record ServiceResult<T>
{
    // 'required' means this property must be set when constructing the record.
    // The '?' after 'T' makes the type nullable — Value can be null.
    public required bool Success { get; init; }
    public T? Value { get; init; }
    public string? ErrorCode { get; init; }
    public string? ErrorMessage { get; init; }

    // Static factory methods — create results without calling 'new' directly.
    // 'static' means these belong to the type, not an instance.
    public static ServiceResult<T> Ok(T value) =>
        new() { Success = true, Value = value };

    public static ServiceResult<T> Fail(string errorCode, string message) =>
        new() { Success = false, ErrorCode = errorCode, ErrorMessage = message };
}

RedisKeys — all key names in one place

Every Redis key used across all services is defined as a constant here. This prevents typos, name collisions between services, and makes key naming auditable at a glance.

// src/SOR.Shared/Redis/RedisKeys.cs
namespace SOR.Shared.Redis;

public static class RedisKeys
{
    // String.Format-style method: call Session("abc123") → "session:abc123"
    // The 'static' modifier means no instance is needed to call these.
    public static string Session(string token) => $"session:{token}";
    public static string ActiveGame(string gameId) => $"game:active:{gameId}";
    public static string LeaderboardRanked() => "leaderboard:ranked";
    public static string FeatureFlag(string flag) => $"config:flag:{flag}";
    public static string ClientPushChannel(string userId) => $"push:{userId}";
}

NatsSubjects — all NATS subject names in one place

Same principle as RedisKeys. Centralizing subject names means a rename touches one file.

// src/SOR.Shared/Nats/NatsSubjects.cs
namespace SOR.Shared.Nats;

public static class NatsSubjects
{
    public const string GameEnded = "sor.game.ended";
    public const string PurchaseCompleted = "sor.bazaar.purchase.completed";
    public const string CardGranted = "sor.collection.card.granted";
    public const string MatchRated = "sor.game.match.rated";
    public const string PlayerBanned = "sor.admin.player.banned";
}

5. Protobuf Contracts — SOR.Shared.Proto

gRPC uses Protobuf (.proto files) as its interface definition language. The .proto files define the message types and service methods. The dotnet-grpc tooling generates C# code from them automatically on build — you never edit the generated files manually.

src/SOR.Shared.Proto/
├── SOR.Shared.Proto.csproj
│
└── Protos/
    ├── auth.proto             # Auth service contract
    ├── game.proto             # Game service contract
    ├── chat.proto             # Chat service contract
    ├── collection.proto       # Collection service contract
    ├── bazaar.proto           # Bazaar service contract
    ├── leaderboard.proto      # Leaderboard service contract
    └── content.proto          # Content service contract

Example: auth.proto

// src/SOR.Shared.Proto/Protos/auth.proto

// proto3 is the current version of the Protobuf language.
syntax = "proto3";

// The C# namespace the generated code will live in.
option csharp_namespace = "SOR.Shared.Proto";

// The package prevents naming collisions with other .proto files.
package sor.auth;

// A 'message' is a structured data type — equivalent to a C# class with properties.
// Each field has a type, a name, and a field number (used in binary encoding — never change these).
message LoginRequest {
  string email = 1;
  string password = 2;
}

message LoginResponse {
  bool success = 1;
  string session_token = 2;   // Only set on success
  string error_code = 3;      // Only set on failure
}

message ValidateTokenRequest {
  string session_token = 1;
}

message ValidateTokenResponse {
  bool valid = 1;
  string user_id = 2;
  string display_name = 3;
}

// A 'service' defines the RPC methods. The generated C# code creates a
// base class (AuthService.AuthServiceBase) that the handler inherits from.
service AuthService {
  rpc Login(LoginRequest) returns (LoginResponse);
  rpc ValidateToken(ValidateTokenRequest) returns (ValidateTokenResponse);
}

SOR.Shared.Proto.csproj

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <AssemblyName>SOR.Shared.Proto</AssemblyName>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" />
  </ItemGroup>

  <ItemGroup>
    <!-- GrpcServices="Both" generates both client and server code from each .proto file.
         Services that handle calls use the Server base class.
         Services that call other services use the Client stub. -->
    <Protobuf Include="Protos/*.proto" GrpcServices="Both" />
  </ItemGroup>
</Project>

6. Multi-Service Runner — SOR.Host

SOR.Host is the deployable binary. It is the only executable project in the solution. It reads the ENABLED_SERVICES environment variable and starts only the listed services.

This is how we run N services per box: set ENABLED_SERVICES=auth,chat,collection on a VM and that VM runs exactly those three services in a single .NET process.

Why a single process? Within one process, services share memory for config, the DI container, and connection pools. There is zero network overhead between co-located services since gRPC calls between them go through localhost. Deploying fewer processes also means fewer Kubernetes pods to manage on smaller infrastructure.

// src/SOR.Host/Program.cs

// 'using' imports a namespace so its types can be used without the full namespace prefix.
// Normally you'd need to write 'SOR.Auth.ServiceRegistration.AddAuthService(...)' —
// the using directive means you can just call 'AddAuthService(...)'.
using SOR.Auth;
using SOR.Chat;
using SOR.Collection;
using SOR.Bazaar;
using SOR.Admin;
using SOR.Leaderboard;
using SOR.Content;
using SOR.Gateway;
using Serilog;

// Read which services this instance should run.
// Environment.GetEnvironmentVariable returns null if the variable isn't set,
// so ?? "all" is a fallback: if unset, run everything (useful for development).
var rawServices = Environment.GetEnvironmentVariable("ENABLED_SERVICES") ?? "all";

// Split "auth,chat,collection" into ["auth", "chat", "collection"].
// ToHashSet() for O(1) Contains() lookups.
var enabledServices = rawServices
    .Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries)
    .ToHashSet(StringComparer.OrdinalIgnoreCase);

bool IsEnabled(string name) =>
    enabledServices.Contains("all") || enabledServices.Contains(name);

// WebApplication.CreateBuilder sets up the ASP.NET Core application builder.
// args are the command-line arguments passed at startup.
var builder = WebApplication.CreateBuilder(args);

// --- Logging ---
// Replace the default logger with Serilog (see §13 for details).
builder.Host.UseSerilog((context, config) =>
    config.ReadFrom.Configuration(context.Configuration));

// --- Shared infrastructure: registered once, used by all enabled services ---

// AddStackExchangeRedisCache registers IConnectionMultiplexer (the Redis client)
// as a singleton — one shared connection for the whole process lifetime.
builder.Services.AddSingleton<IConnectionMultiplexer>(
    ConnectionMultiplexer.Connect(builder.Configuration.GetConnectionString("Redis")!));

// NATS connection registered as singleton.
builder.Services.AddNatsClient(opts =>
    opts with { Url = builder.Configuration["Nats:Url"]! });

// --- Service registrations ---
// Each service registers its own DbContext, repositories, services, and handlers.
// Only services listed in ENABLED_SERVICES are registered.

if (IsEnabled("auth"))      builder.Services.AddAuthService(builder.Configuration);
if (IsEnabled("chat"))      builder.Services.AddChatService(builder.Configuration);
if (IsEnabled("collection")) builder.Services.AddCollectionService(builder.Configuration);
if (IsEnabled("bazaar"))    builder.Services.AddBazaarService(builder.Configuration);
if (IsEnabled("admin"))     builder.Services.AddAdminService(builder.Configuration);
if (IsEnabled("leaderboard")) builder.Services.AddLeaderboardService(builder.Configuration);
if (IsEnabled("content"))   builder.Services.AddContentService(builder.Configuration);
if (IsEnabled("gateway"))   builder.Services.AddGatewayService(builder.Configuration);

// Build the application from the configured builder.
var app = builder.Build();

// --- Middleware pipeline ---
// Middleware runs in the order it's added. Each piece can intercept a request,
// do something, and pass it to the next piece.
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();

// --- Route gRPC handlers ---
// MapGrpcService connects the URL route to the handler class.
// The handler class is only registered if the service is enabled.
if (IsEnabled("auth"))       app.MapGrpcService<SOR.Auth.Handlers.AuthGrpcHandler>();
if (IsEnabled("chat"))       app.MapGrpcService<SOR.Chat.Handlers.ChatGrpcHandler>();
if (IsEnabled("collection")) app.MapGrpcService<SOR.Collection.Handlers.CollectionGrpcHandler>();
if (IsEnabled("bazaar"))     app.MapGrpcService<SOR.Bazaar.Handlers.BazaarGrpcHandler>();
if (IsEnabled("leaderboard")) app.MapGrpcService<SOR.Leaderboard.Handlers.LeaderboardGrpcHandler>();
if (IsEnabled("content"))    app.MapGrpcService<SOR.Content.Handlers.ContentGrpcHandler>();

// Health check endpoint for Kubernetes liveness/readiness probes.
app.MapHealthChecks("/health");

// Start the application. This call blocks until the process is stopped.
await app.RunAsync();

Deployment examples

# Kubernetes deployment: Auth + Collection + Bazaar on one pod
env:
  - name: ENABLED_SERVICES
    value: "auth,collection,bazaar"

# Kubernetes deployment: Chat + Leaderboard on another pod
env:
  - name: ENABLED_SERVICES
    value: "chat,leaderboard"

# Development: run everything
env:
  - name: ENABLED_SERVICES
    value: "all"

7. Dependency Injection

.NET has a built-in dependency injection (DI) container. Understanding it is essential to reading and writing code in this codebase.

The concept

Instead of a class creating its own dependencies (new AuthRepository()), you declare what you need in the constructor and the DI container creates and injects the right instance.

// Without DI — bad: AuthService is tightly coupled to AuthRepository.
// You can't swap the repository for a mock in tests.
public class AuthService
{
    private readonly AuthRepository _repo = new AuthRepository(); // hard dependency
}

// With DI — good: AuthService depends on the interface, not the implementation.
// In tests, you inject a mock. In production, you inject the real repository.
public class AuthService : IAuthService
{
    private readonly IAuthRepository _repo;

    // The DI container sees that AuthService needs IAuthRepository,
    // looks up what was registered for that interface, creates it,
    // and passes it here automatically.
    public AuthService(IAuthRepository repo)
    {
        _repo = repo;
    }
}

Service lifetimes

When you register something in the DI container, you specify its lifetime:

Lifetime Meaning Use for
AddSingleton One instance for the entire process lifetime Redis connection, NATS connection, config
AddScoped One instance per request (HTTP request or gRPC call) DbContext, repositories, services
AddTransient New instance every time it's requested Rarely used; lightweight stateless utilities

Rule: DbContexts and repositories must always be AddScoped. Redis and NATS connections must always be AddSingleton. Business logic services (AddScoped — they depend on scoped repositories).

Injecting things

Once registered, anything can be injected into any constructor:

// The DI container automatically provides all three of these.
// No 'new' calls anywhere in business logic.
public class AuthService : IAuthService
{
    private readonly IAuthRepository _repo;
    private readonly IConnectionMultiplexer _redis;
    private readonly IOptions<AuthOptions> _options;

    public AuthService(
        IAuthRepository repo,
        IConnectionMultiplexer redis,
        IOptions<AuthOptions> options)
    {
        _repo = repo;
        _redis = redis;
        _options = options;
    }
}

8. Configuration System

Configuration follows the standard .NET layered approach:

  1. appsettings.json — base config checked into source control (no secrets)
  2. appsettings.{Environment}.json — environment overrides (Development, Staging, Production)
  3. Environment variables — override anything from the above files (used in Docker/K8s)

appsettings.json structure

{
  "ConnectionStrings": {
    "Auth": "Host=postgres;Database=sor_auth;Username=sor;Password=",
    "Chat": "Host=postgres;Database=sor_chat;Username=sor;Password=",
    "Redis": "redis:6379",
    "ChatColdStorage": "server=mysql;database=sor_chat_archive;user=sor;password="
  },
  "Nats": {
    "Url": "nats://nats:4222"
  },
  "Auth": {
    "SessionTtlMinutes": 1440,
    "MaxSessionsPerUser": 5
  },
  "Serilog": {
    "MinimumLevel": "Information",
    "WriteTo": [
      { "Name": "Console" }
    ]
  }
}

Strongly typed options classes

Instead of calling configuration["Auth:SessionTtlMinutes"] everywhere (string-based, no validation, no autocomplete), bind config sections to a typed class:

// src/SOR.Auth/AuthOptions.cs
namespace SOR.Auth;

// This class mirrors the structure of the "Auth" section in appsettings.json.
// Properties must match the key names exactly (case-insensitive by default).
public class AuthOptions
{
    // DataAnnotations attributes validate the values at startup.
    // If SessionTtlMinutes is 0, the app will throw before serving any requests.
    [Range(1, int.MaxValue)]
    public int SessionTtlMinutes { get; set; } = 1440;

    [Range(1, 100)]
    public int MaxSessionsPerUser { get; set; } = 5;
}

Registered in ServiceRegistration.cs:

services.Configure<AuthOptions>(configuration.GetSection("Auth"));

Injected and used:

public class AuthService : IAuthService
{
    private readonly AuthOptions _options;

    // IOptions<T> is the DI wrapper around a config section.
    // Calling .Value gives you the typed AuthOptions instance.
    public AuthService(IOptions<AuthOptions> options)
    {
        _options = options.Value;
    }

    public TimeSpan GetSessionTtl() =>
        TimeSpan.FromMinutes(_options.SessionTtlMinutes);
}

Environment variable overrides

.NET automatically maps environment variables with double underscores to nested config keys:

# Sets ConnectionStrings:Auth
ConnectionStrings__Auth="Host=prod-postgres;Database=sor_auth;Username=sor;Password=secret"

# Sets Auth:SessionTtlMinutes
Auth__SessionTtlMinutes=2880

In Kubernetes, secrets are injected as environment variables. The code never knows whether config came from a file or an environment variable.


9. gRPC Handlers

A gRPC handler is the Layer 1 entry point for a service. It inherits from the base class generated by the Protobuf tooling and delegates all logic to the service layer.

// src/SOR.Auth/Handlers/AuthGrpcHandler.cs
namespace SOR.Auth.Handlers;

// The generated base class is AuthService.AuthServiceBase (from auth.proto).
// It contains abstract or virtual methods for each rpc defined in the proto file.
// We override those methods to provide our implementation.
//
// [GrpcService] is not needed here — gRPC in ASP.NET Core finds the handler
// automatically when it's registered via MapGrpcService<T> in Program.cs.
public sealed class AuthGrpcHandler : AuthService.AuthServiceBase
{
    private readonly IAuthService _authService;
    private readonly ILogger<AuthGrpcHandler> _logger;

    // Constructor injection — the DI container provides these.
    public AuthGrpcHandler(IAuthService authService, ILogger<AuthGrpcHandler> logger)
    {
        _authService = authService;
        _logger = logger;
    }

    // Override the Login method defined in auth.proto.
    //
    // 'override' means we're replacing the base class's implementation.
    // Task<T> is the C# async return type — 'async' + 'await' let us write
    // async code that looks sequential without blocking threads.
    // ServerCallContext carries metadata about the gRPC call (deadline, peer address, etc.).
    public override async Task<LoginResponse> Login(
        LoginRequest request,
        ServerCallContext context)
    {
        // Validate inputs before calling business logic.
        // Return early with an error response — no exception needed for expected failures.
        if (string.IsNullOrWhiteSpace(request.Email) ||
            string.IsNullOrWhiteSpace(request.Password))
        {
            return new LoginResponse
            {
                Success = false,
                ErrorCode = "INVALID_INPUT"
            };
        }

        // Delegate to the service layer. The handler never touches the database directly.
        var result = await _authService.LoginAsync(request.Email, request.Password);

        // Map ServiceResult<T> to the Protobuf response message.
        if (!result.Success)
        {
            _logger.LogWarning("Login failed for {Email}: {ErrorCode}", request.Email, result.ErrorCode);
            return new LoginResponse
            {
                Success = false,
                ErrorCode = result.ErrorCode ?? "UNKNOWN_ERROR"
            };
        }

        return new LoginResponse
        {
            Success = true,
            SessionToken = result.Value!
        };
    }

    public override async Task<ValidateTokenResponse> ValidateToken(
        ValidateTokenRequest request,
        ServerCallContext context)
    {
        var result = await _authService.ValidateTokenAsync(request.SessionToken);

        if (!result.Success)
            return new ValidateTokenResponse { Valid = false };

        return new ValidateTokenResponse
        {
            Valid = true,
            UserId = result.Value!.UserId,
            DisplayName = result.Value.DisplayName
        };
    }
}

Calling another service via gRPC (client side)

When a service needs to call another service synchronously, it uses the generated gRPC client stub.

// In ServiceRegistration.cs for a service that needs to call Auth:
services.AddGrpcClient<AuthService.AuthServiceClient>(options =>
{
    // The address of the Auth service — a Kubernetes service DNS name.
    options.Address = new Uri(configuration["Services:Auth"]!);
});

// In a handler or service that calls Auth:
public class GatewayAuthValidator
{
    private readonly AuthService.AuthServiceClient _authClient;

    public GatewayAuthValidator(AuthService.AuthServiceClient authClient)
    {
        _authClient = authClient;
    }

    public async Task<bool> ValidateAsync(string token)
    {
        var response = await _authClient.ValidateTokenAsync(
            new ValidateTokenRequest { SessionToken = token });
        return response.Valid;
    }
}

10. NATS Integration

NATS is used for async fan-out events. One service publishes; zero or more services subscribe. Publishers and subscribers have no knowledge of each other.

Publishing an event

// src/SOR.Game/Services/GameService.cs (excerpt)

// INatsClient is the official NATS client interface — inject it from DI.
public class GameService : IGameService
{
    private readonly INatsClient _nats;

    public GameService(INatsClient nats) { _nats = nats; }

    public async Task RecordMatchResultAsync(MatchResult result)
    {
        // ... persist result ...

        // Publish an event to NATS. Any service subscribed to this subject
        // will receive it independently. Game service doesn't care who listens.
        //
        // PublishAsync<T> serializes T to JSON (or Protobuf if configured) automatically.
        await _nats.PublishAsync(NatsSubjects.GameEnded, new GameEndedEvent
        {
            GameId = result.GameId,
            WinnerId = result.WinnerId,
            LoserId = result.LoserId,
            EndedAt = DateTimeOffset.UtcNow
        });
    }
}

Subscribing to events

NATS subscribers are registered as IHostedService background workers — they run for the entire lifetime of the process and receive events as they arrive.

// src/SOR.Leaderboard/Subscribers/GameEndedSubscriber.cs
namespace SOR.Leaderboard.Subscribers;

// IHostedService is the .NET interface for background services.
// The framework starts it on app startup and stops it on shutdown.
public sealed class GameEndedSubscriber : IHostedService
{
    private readonly INatsClient _nats;
    private readonly IServiceScopeFactory _scopeFactory;
    private readonly ILogger<GameEndedSubscriber> _logger;

    // IServiceScopeFactory is needed because this is a Singleton (runs forever),
    // but it needs to create Scoped services (like repositories) per message.
    // Creating a scope per message ensures DbContext is not shared across messages.
    public GameEndedSubscriber(
        INatsClient nats,
        IServiceScopeFactory scopeFactory,
        ILogger<GameEndedSubscriber> logger)
    {
        _nats = nats;
        _scopeFactory = scopeFactory;
        _logger = logger;
    }

    // CancellationToken signals when the application is shutting down.
    // We pass it through so async operations can cancel cleanly.
    public async Task StartAsync(CancellationToken cancellationToken)
    {
        // SubscribeAsync returns an IAsyncEnumerable — an async stream of messages.
        // 'await foreach' processes each message as it arrives without blocking.
        await foreach (var msg in _nats.SubscribeAsync<GameEndedEvent>(
            NatsSubjects.GameEnded, cancellationToken: cancellationToken))
        {
            if (msg.Data is null) continue;

            try
            {
                // Create a fresh DI scope for each message so EF Core DbContext
                // is properly disposed after handling each event.
                await using var scope = _scopeFactory.CreateAsyncScope();
                var service = scope.ServiceProvider.GetRequiredService<ILeaderboardService>();
                await service.ProcessGameResultAsync(msg.Data);
            }
            catch (Exception ex)
            {
                // Log and continue — a bad message must not crash the subscriber.
                _logger.LogError(ex, "Failed to process GameEnded event {GameId}", msg.Data?.GameId);
            }
        }
    }

    public Task StopAsync(CancellationToken cancellationToken) => Task.CompletedTask;
}

Register the subscriber in ServiceRegistration.cs:

// IHostedService registrations use AddHostedService<T>.
services.AddHostedService<GameEndedSubscriber>();

11. Redis Integration

Redis is used for session storage, client push delivery, live game state, leaderboard Sorted Sets, and runtime feature flags.

Registering the connection

Registered once in Program.cs as a Singleton — the connection multiplexer manages an internal connection pool and is safe to share across the entire process.

// Program.cs (already shown in §6)
builder.Services.AddSingleton<IConnectionMultiplexer>(
    ConnectionMultiplexer.Connect(builder.Configuration.GetConnectionString("Redis")!));

Using Redis in a service

// src/SOR.Auth/Services/AuthService.cs (excerpt)
public class AuthService : IAuthService
{
    private readonly IDatabase _redis;
    private readonly AuthOptions _options;

    // IConnectionMultiplexer.GetDatabase() returns a lightweight IDatabase handle.
    // It is safe to call GetDatabase() on every request — it does not create new connections.
    public AuthService(IConnectionMultiplexer redis, IOptions<AuthOptions> options)
    {
        _redis = redis.GetDatabase();
        _options = options.Value;
    }

    public async Task<string> CreateSessionAsync(string userId, string displayName)
    {
        // Guid.NewGuid() generates a cryptographically random 128-bit identifier.
        // ToString("N") formats it as a 32-character hex string with no dashes.
        var token = Guid.NewGuid().ToString("N");
        var ttl = TimeSpan.FromMinutes(_options.SessionTtlMinutes);

        // Serialize session data to JSON.
        // System.Text.Json is the built-in .NET JSON library — fast and allocation-efficient.
        var sessionJson = JsonSerializer.Serialize(new
        {
            UserId = userId,
            DisplayName = displayName,
            CreatedAt = DateTimeOffset.UtcNow
        });

        // SET key value EX seconds — sets the key and its TTL atomically.
        // RedisKeys.Session(token) returns the namespaced key string "session:{token}".
        await _redis.StringSetAsync(
            RedisKeys.Session(token),
            sessionJson,
            expiry: ttl);

        return token;
    }

    public async Task RevokeSessionAsync(string token)
    {
        // DEL key — removes the key. If the key doesn't exist, this is a no-op.
        await _redis.KeyDeleteAsync(RedisKeys.Session(token));
    }
}

12. Database — EF Core + PostgreSQL

Entity Framework Core (EF Core) is the ORM. It lets you define your database schema as C# classes and query the database using LINQ (Language Integrated Query) instead of raw SQL. EF Core translates LINQ queries into optimized SQL at runtime.

DbContext

Each service has its own DbContext. A DbContext represents a database connection session and tracks all changes to entities loaded through it.

// src/SOR.Auth/Data/AuthDbContext.cs
namespace SOR.Auth.Data;

// DbContext is the EF Core base class. We inherit from it and add our DbSets.
public class AuthDbContext : DbContext
{
    // Constructor: passes options to the base class.
    // Options include the connection string — provided by DI from config.
    public AuthDbContext(DbContextOptions<AuthDbContext> options) : base(options) { }

    // DbSet<T> represents a database table. Querying _users runs a SELECT;
    // adding to it and calling SaveChanges() runs an INSERT.
    public DbSet<UserEntity> Users => Set<UserEntity>();
    public DbSet<OAuthLinkEntity> OAuthLinks => Set<OAuthLinkEntity>();

    // OnModelCreating configures the schema (table names, indexes, constraints).
    // This runs once when EF Core builds its internal model of the schema.
    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        // Configure the Users table.
        modelBuilder.Entity<UserEntity>(entity =>
        {
            // Explicit table name (default would be "Users" — being explicit is safer).
            entity.ToTable("users", schema: "auth");

            // Primary key. EF Core auto-detects properties named "Id" but being
            // explicit documents intent.
            entity.HasKey(u => u.Id);

            // Index for fast email lookups. IsUnique enforces the DB constraint.
            entity.HasIndex(u => u.Email).IsUnique();

            // Column type: varchar with a max length (enforced at DB level).
            entity.Property(u => u.Email).HasMaxLength(256).IsRequired();
            entity.Property(u => u.DisplayName).HasMaxLength(64).IsRequired();
        });
    }
}

Entity classes

Entities are plain C# classes that map to database rows. They live in the service's Data/ or Models/ folder. They are the internal database representation — not the API response.

// src/SOR.Auth/Models/UserEntity.cs
namespace SOR.Auth.Models;

public class UserEntity
{
    public Guid Id { get; set; }
    public required string Email { get; set; }
    public required string DisplayName { get; set; }
    public required string PasswordHash { get; set; }
    public DateTimeOffset CreatedAt { get; set; }
    public bool IsBanned { get; set; }
}

Repository implementation

// src/SOR.Auth/Repositories/AuthRepository.cs
namespace SOR.Auth.Repositories;

public class AuthRepository : IAuthRepository
{
    private readonly AuthDbContext _db;

    public AuthRepository(AuthDbContext db)
    {
        _db = db;
    }

    // FirstOrDefaultAsync returns the first matching row, or null if none.
    // The lambda expression 'u => u.Email == email' is the WHERE clause.
    // 'await' pauses this method until the database responds, without blocking the thread.
    public async Task<UserEntity?> FindByEmailAsync(string email, CancellationToken ct = default)
    {
        return await _db.Users
            .FirstOrDefaultAsync(u => u.Email == email, ct);
    }

    public async Task<UserEntity> CreateAsync(UserEntity user, CancellationToken ct = default)
    {
        // Add the entity to the change tracker.
        _db.Users.Add(user);

        // SaveChangesAsync flushes all pending changes to the database in one transaction.
        await _db.SaveChangesAsync(ct);

        return user;
    }
}

Migrations

Migrations are auto-generated files that track schema changes over time. When you change an entity class (add a column, change a type), you generate a new migration and apply it.

# Generate a migration (run from Server/ directory).
# <ServiceName>Initial is just a descriptive name for the migration.
dotnet ef migrations add AuthInitial \
  --project src/SOR.Auth \
  --startup-project src/SOR.Host \
  --context AuthDbContext

# Apply all pending migrations to the database.
dotnet ef database update \
  --project src/SOR.Auth \
  --startup-project src/SOR.Host \
  --context AuthDbContext

In production, migrations are applied automatically on startup:

// ServiceRegistration.cs — after the DbContext is registered:
services.AddHostedService<DatabaseMigratorHostedService<AuthDbContext>>();

13. Logging — Serilog

All logging uses Serilog with structured log output. Every log entry is a structured event, not just a string — this allows log aggregators (Seq, Grafana Loki, etc.) to query and filter on field values.

Log levels

Level When to use
LogTrace Extremely verbose — step-by-step flow. Disabled in production.
LogDebug Developer details — query parameters, intermediate values. Disabled in production.
LogInformation Normal operational events — service started, login succeeded, game created.
LogWarning Something unexpected but recoverable — login failed, retrying a DB query.
LogError An operation failed — unhandled exception, external call failed.
LogCritical System is broken — database unreachable on startup, OOM.

Usage

// Always inject ILogger<T> where T is the class using it.
// The T type name appears in log output so you know where the log came from.
private readonly ILogger<AuthService> _logger;

// Structured logging: use message templates with {Property} placeholders.
// Serilog captures the actual value as a named property — not just a string.
// This means you can search logs for "UserId = abc123" later.
_logger.LogInformation("User {UserId} logged in from {IpAddress}", userId, ipAddress);

// Log exceptions: pass the exception as the first argument.
// Serilog captures the full stack trace as a structured field.
try { ... }
catch (Exception ex)
{
    _logger.LogError(ex, "Login failed for {Email}", email);
    throw; // Re-throw after logging if the caller needs to handle it.
}

14. Error Handling

Expected failures: ServiceResult

Expected failures (user not found, invalid password, deck too large) are returned as ServiceResult.Fail(...). No exception is thrown. The caller checks result.Success and maps to an appropriate response.

public async Task<ServiceResult<string>> LoginAsync(string email, string password)
{
    var user = await _repo.FindByEmailAsync(email);

    // Expected failure — return a result, don't throw.
    if (user is null)
        return ServiceResult<string>.Fail("USER_NOT_FOUND", "Invalid credentials.");

    if (!PasswordHasher.Verify(password, user.PasswordHash))
        return ServiceResult<string>.Fail("INVALID_PASSWORD", "Invalid credentials.");

    if (user.IsBanned)
        return ServiceResult<string>.Fail("ACCOUNT_BANNED", "This account has been banned.");

    var token = await CreateSessionAsync(user.Id.ToString(), user.DisplayName);
    return ServiceResult<string>.Ok(token);
}

Unexpected failures: exceptions

Unexpected failures (DB connection lost, OOM, null where impossible) are allowed to throw. A global exception handler in ASP.NET Core catches them, logs them, and returns a generic 5xx response to the caller.

// Program.cs — catch-all for unhandled exceptions in the middleware pipeline.
app.UseExceptionHandler(exceptionHandlerApp =>
    exceptionHandlerApp.Run(async context =>
    {
        var feature = context.Features.Get<IExceptionHandlerFeature>();
        var logger = context.RequestServices.GetRequiredService<ILogger<Program>>();
        logger.LogError(feature?.Error, "Unhandled exception on {Path}", context.Request.Path);
        context.Response.StatusCode = 500;
    }));

Never swallow exceptions silently

// BAD: The exception disappears. The caller thinks nothing went wrong.
try { await _repo.SaveAsync(entity); }
catch (Exception) { }

// GOOD: Log and re-throw, or return a failure result.
try { await _repo.SaveAsync(entity); }
catch (Exception ex)
{
    _logger.LogError(ex, "Failed to save entity {Id}", entity.Id);
    throw;
}

15. Health Checks

Every running instance exposes /health for Kubernetes liveness and readiness probes. Health checks verify that the service's critical dependencies (database, Redis) are reachable.

// ServiceRegistration.cs — register health checks alongside services.
services.AddHealthChecks()
    .AddNpgSql(configuration.GetConnectionString("Auth")!, name: "auth-db")
    .AddRedis(configuration.GetConnectionString("Redis")!, name: "redis");

// Program.cs — expose the endpoint (already shown in §6).
app.MapHealthChecks("/health");

16. Testing Patterns

Unit tests

Unit tests test a single class in isolation. All dependencies are replaced with mocks. No database, no Redis, no network — tests run in milliseconds.

// tests/SOR.Auth.Tests/AuthServiceTests.cs
namespace SOR.Auth.Tests;

// [Fact] marks a test method. xUnit discovers and runs all methods marked with [Fact].
public class AuthServiceTests
{
    // Moq: create a mock implementation of the interface.
    // The mock records calls made to it and can be configured to return specific values.
    private readonly Mock<IAuthRepository> _repoMock = new();
    private readonly Mock<IConnectionMultiplexer> _redisMock = new();
    private readonly IAuthService _sut; // "sut" = System Under Test — common convention.

    public AuthServiceTests()
    {
        var options = Options.Create(new AuthOptions { SessionTtlMinutes = 60 });
        _sut = new AuthService(_repoMock.Object, _redisMock.Object, options);
    }

    [Fact]
    public async Task Login_WithValidCredentials_ReturnsSuccessResult()
    {
        // Arrange: configure the mock to return a specific user when queried.
        _repoMock
            .Setup(r => r.FindByEmailAsync("test@example.com", default))
            .ReturnsAsync(new UserEntity
            {
                Id = Guid.NewGuid(),
                Email = "test@example.com",
                DisplayName = "TestUser",
                PasswordHash = PasswordHasher.Hash("correct-password"),
                CreatedAt = DateTimeOffset.UtcNow
            });

        // Act: call the method being tested.
        var result = await _sut.LoginAsync("test@example.com", "correct-password");

        // Assert: verify the result. FluentAssertions provides readable assertions.
        result.Success.Should().BeTrue();
        result.Value.Should().NotBeNullOrEmpty();
    }

    [Fact]
    public async Task Login_WithWrongPassword_ReturnsFailResult()
    {
        _repoMock
            .Setup(r => r.FindByEmailAsync("test@example.com", default))
            .ReturnsAsync(new UserEntity
            {
                Id = Guid.NewGuid(),
                Email = "test@example.com",
                DisplayName = "TestUser",
                PasswordHash = PasswordHasher.Hash("correct-password"),
                CreatedAt = DateTimeOffset.UtcNow
            });

        var result = await _sut.LoginAsync("test@example.com", "wrong-password");

        result.Success.Should().BeFalse();
        result.ErrorCode.Should().Be("INVALID_PASSWORD");
    }
}

Integration tests

Integration tests spin up a real application with a real database (test-specific). Used to test the full stack — handler → service → repository → database — without mocks.

// tests/SOR.Auth.Tests/AuthIntegrationTests.cs

// WebApplicationFactory<T> starts the real app in-memory for testing.
// T is the entry point — usually Program.cs is referenced via a partial class.
public class AuthIntegrationTests : IClassFixture<WebApplicationFactory<Program>>
{
    private readonly WebApplicationFactory<Program> _factory;

    public AuthIntegrationTests(WebApplicationFactory<Program> factory)
    {
        _factory = factory.WithWebHostBuilder(builder =>
        {
            builder.ConfigureAppConfiguration((_, config) =>
            {
                // Override connection strings to point at a test database.
                config.AddInMemoryCollection(new Dictionary<string, string?>
                {
                    ["ConnectionStrings:Auth"] = "Host=localhost;Database=sor_auth_test;...",
                    ["ENABLED_SERVICES"] = "auth"
                });
            });
        });
    }

    [Fact]
    public async Task Login_ValidUser_ReturnsToken()
    {
        // Use the generated gRPC client against the in-memory server.
        var client = new AuthService.AuthServiceClient(
            GrpcChannel.ForAddress("http://localhost", new GrpcChannelOptions
            {
                HttpClient = _factory.CreateClient()
            }));

        var response = await client.LoginAsync(new LoginRequest
        {
            Email = "seed@example.com",
            Password = "testpassword"
        });

        response.Success.Should().BeTrue();
        response.SessionToken.Should().NotBeEmpty();
    }
}

Test file naming conventions

File What it tests
{Class}Tests.cs Unit tests for a single class
{Service}IntegrationTests.cs Integration tests for a full service stack
{Handler}HandlerTests.cs Tests for a gRPC handler (mock the service layer)

17. Naming Conventions

C# uses different casing conventions for different kinds of identifiers. These are enforced by the compiler for some cases and by team convention for others.

Kind Convention Example
Namespace PascalCase SOR.Auth.Services
Class / Interface / Record PascalCase AuthService, IAuthRepository
Method PascalCase LoginAsync, FindByEmailAsync
Property PascalCase SessionTtlMinutes, ErrorCode
Constant (const) PascalCase NatsSubjects.GameEnded
Private field _camelCase _repo, _logger
Local variable camelCase sessionToken, userId
Parameter camelCase email, password
Interface I prefix IAuthService, IAuthRepository
Async method Async suffix LoginAsync, SaveChangesAsync
Generic type parameter T prefix ServiceResult<T>, DbSet<TEntity>

File naming

  • One class per file.
  • File name must match class name exactly: AuthService.cs contains class AuthService.
  • Interface files: IAuthService.cs contains interface IAuthService.

Project naming

All projects in the solution are prefixed with SOR.:

  • SOR.Host — multi-service runner
  • SOR.Shared — shared library
  • SOR.Auth — Auth service module
  • SOR.Auth.Tests — tests for Auth

18. Hard Rules

These rules are non-negotiable. Every code review checks for violations.

  1. No cross-service database access. Each service's DbContext connects to its own schema. Service A never queries Service B's schema. Inter-service data goes through gRPC or NATS.

  2. No business logic in handlers. Handlers receive, validate inputs, call the service, and return. All business logic lives in the service layer.

  3. No database access in services. Services call repositories. They never instantiate DbContext directly or run SQL.

  4. No new for injected dependencies. If something is registered in the DI container, it is injected through the constructor — never created with new inside a class.

  5. All async methods must be awaited. Never call an async method and discard the Task. This hides exceptions and can cause subtle race conditions.

  6. All Redis key names go through RedisKeys. No inline string literals like "session:" + token.

  7. All NATS subject names go through NatsSubjects. No inline string literals.

  8. No shared mutable state between services. Services share DI infrastructure (Redis, NATS connections) but never share in-memory objects or static mutable state.

  9. Every service module exposes exactly one public entry point: Add{Name}Service. All other types in the module are internal unless explicitly needed by other assemblies.

  10. No catching Exception without re-throwing or returning a result. Swallowing exceptions silently is forbidden.

  11. Log at the correct level. Never log expected failures at Error. Never flood Information with per-message trace data in production.

  12. Entities are internal to their service. UserEntity from SOR.Auth is never referenced in SOR.Gateway. Share data through Protobuf messages or strongly-typed C# DTOs in SOR.Shared.