SAIF.NetCore.ServiceContracts architecture

SAIF.NetCore.ServiceContracts is the foundation-layer contracts assembly of the SAIF .NET Core framework: it defines the interfaces, DTOs, enums, exception types, and event-args/delegates that every other SAIF.NetCore.* package implements or consumes, and it contains no service implementations, no DI registrations, no middleware, and no I/O of its own.

Responsibilities

• Declare the configuration contract (IEnvironmentClient) that implementation libraries use to read environment/section settings and secure settings.
• Declare the HTTP client contract (IHttpJsonClient, IHttpRequestResult, HttpClientOptions, HttpClientSerializer) used throughout the framework for outbound JSON calls.
• Declare the DB connection-string contract (IDBConnectionClient) and the system-hash contract (ISystemHashService).
• Declare the logging contracts (ISaifLoggable, ISaifLogService, ISaifWindowsServiceLogService) and supporting enums/log-info interfaces.
• Declare identity and authorization contracts (IIdentityService, IIdentityServiceAccessor, IUserProfile/UserProfile, IUserGroup/UserGroup, ExternalUser, ExternalUserType).
• Declare the OIDC contract set (IOidcSettings, OidcAppCredentials, IRoleClaimService, IClaimTransformCacheService, IJwtAuthorizationCookieClaimService, IJwtRefreshService, JwtSet, ILoginRedirectService, IDataProtectionCertService, IUrlCaseService).
• Declare the web error-handling contract set (SAIFException, HttpStatusCodeException, ExceptionEnum, IErrorHandleable, IErrorHandlerHook, IStandardErrorLogInfo, IWebErrorLogInfo) and the Windows-service error-handling contract set (IWindowsServiceErrorHandler, IWindowsServiceError, IErrorContextContainer, ISpecialErrorAction(<T>), SpecialErrorActionResult, ShutdownExemptExceptionType, and the two handling-event delegates).
• Declare the Windows-service worker contract (IServiceTaskRunner) implemented by consumers and driven by SAIF.NetCore.WindowsService.

Component boundaries

• Each functional contract group (configuration, HTTP, DB connection strings, system hash, logging, identity, OIDC, web error handling, Windows-service error handling, Windows-service worker) is a self-contained set of interfaces/DTOs with no cross-group behavioral coupling; grouping is by naming convention and XML-doc intent, not by namespace or assembly boundary*.
• A handful of concrete types carry executable logic that belongs to this library rather than to an implementer: OidcAppCredentials (parses and validates a raw credential string), ShutdownExemptExceptionType (validates the registered exception Type), HttpClientOptions (default values and two fluent setters), BeginErrorHandlingEventArgs/ErrorHandledEventArgs/SpecialErrorActionResult (event/result data carriers with defaults), and SAIFException/HttpStatusCodeException (exception data carriers). These are documented fully in this library because no other library defines their behavior.
• All other declared operations (for example, IEnvironmentClient.GetSettingValue, IHttpJsonClient.GetAsync, IIdentityService.IsAuthorized) are contract-only here; their executable behavior belongs to the implementation libraries listed under "Contract operation catalog" in operations-processes.md, not to this library's boundary.
• IErrorHandleable/IErrorHandlerHook and IServiceTaskRunner have no in-repo production implementer; only test code implements them*.

Interaction model

• This library has no runtime control or data flow. Every other SAIF.NetCore.* implementation library takes a NuGet reference on this package and implements one or more of its interfaces, or constructs/consumes one of its DTOs and exception types, as documented in each consuming library's own architecture page.
• SAIF.NetCore.ServiceExtensions, the top-layer composition package, references this library directly (alongside the implementation packages it composes) to wire concrete implementations of these contracts into IServiceCollection for consuming applications.
• Because this library sits at the bottom of the dependency graph, nothing in it ever calls into another SAIF.NetCore.* package; all arrows in the diagram below point inward, from the consuming implementation libraries into this foundation contracts assembly, representing their NuGet package references rather than any call this library makes.

Architecture diagram

The following diagram shows this library's position at the foundation of the SAIF .NET Core framework and the implementation libraries that depend on its contracts.

flowchart TD
    SC["SAIF.NetCore.ServiceContracts<br>(foundation: interfaces, DTOs, enums,<br>exceptions, event-args/delegates)"]
    ENV["SAIF.NetCore.EnvironmentClient<br>implements IEnvironmentClient"]
    HTTP["SAIF.NetCore.HttpClients<br>implements IHttpJsonClient"]
    DB["SAIF.NetCore.DBConnectionClient<br>implements IDBConnectionClient"]
    HASH["SAIF.NetCore.SystemHash<br>implements ISystemHashService"]
    LOG["SAIF.NetCore.Logging<br>implements ISaifLogService"]
    AUTH["SAIF.NetCore.AuthService<br>implements IIdentityService"]
    OIDC["SAIF.NetCore.OIDC<br>implements OIDC contracts"]
    ERR["SAIF.NetCore.ErrorHandler<br>implements IWindowsServiceErrorHandler"]
    WINSVC["SAIF.NetCore.WindowsService<br>drives IServiceTaskRunner"]
    SE["SAIF.NetCore.ServiceExtensions<br>(top-layer composition)"]
    ENV -.->|NuGet ref| SC
    HTTP -.->|NuGet ref| SC
    DB -.->|NuGet ref| SC
    HASH -.->|NuGet ref| SC
    LOG -.->|NuGet ref| SC
    AUTH -.->|NuGet ref| SC
    OIDC -.->|NuGet ref| SC
    ERR -.->|NuGet ref| SC
    WINSVC -.->|NuGet ref| SC
    SE -.->|NuGet ref| SC

Sequence diagram

The following diagram shows the general pattern by which an implementation library satisfies a contract declared here, using IEnvironmentClient/IHttpJsonClient consumption as a representative example (actual call targets vary per consuming library).

sequenceDiagram
    participant App as Consuming application
    participant SE as SAIF.NetCore.ServiceExtensions
    participant Impl as Implementation library<br>(e.g. EnvironmentClient, HttpClients)
    participant SC as ServiceContracts interface
    App->>SE: Register SAIF services
    SE->>Impl: Register concrete implementation for SC interface
    App->>SC: Call contract member (e.g. GetSettingValue)
    SC->>Impl: Dispatch to registered implementation
    Impl-->>App: Return result

Design constraints

• No project references between libraries in this repository; every dependency on this package from another SAIF.NetCore.* library is a NuGet package reference, consistent with the repository-wide layering in Architecture.md.
• This library must never take a dependency on any other SAIF.NetCore.* package, by design: it is the foundation layer, and dependencies flow strictly bottom-up (ServiceContracts/Common → implementation libraries → ServiceExtensions → applications).
• Contract changes here are cross-cutting: 16 in-repo libraries consume this package, so any breaking interface change has a wide blast radius across the framework*.
• ISaifLoggable declares void Dispose() without extending IDisposable, so implementers cannot be used in a using block through that interface alone.
• ISaifLogService/ISaifWindowsServiceLogService are two-phase: the contract requires Configure to be called before the logger is usable, and exposes IsConfigured for implementers to track that state.

Related documentation

• Index
• Overview
• Dependencies
• Operations and processes
• Business rules
• API reference
• SAIF.NetCore.AuthService architecture

Note: Statements marked with * were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts. Statements marked with ** could not be confirmed; treat as unknown until verified.

Sources

• src/SAIF.NetCore.ServiceContracts/SAIF.NetCore.ServiceContracts/SAIF.NetCore.ServiceContracts/SAIF.NetCore.ServiceContracts.csproj
• src/SAIF.NetCore.ServiceContracts/SAIF.NetCore.ServiceContracts/SAIF.NetCore.ServiceContracts/ — IEnvironmentClient.cs, IHttpJsonClient.cs, IHttpRequestResult.cs, IDBConnectionClient.cs, ISystemHashService.cs, ISaifLoggable.cs, ISaifLogService.cs, ISaifWindowsServiceLogService.cs, IIdentityService.cs, IIdentityServiceAccessor members in IIdentityService.cs, IOidcSettings.cs, OidcAppCredentials.cs, IRoleClaimService.cs, IClaimTransformCacheService.cs, IJwtAuthorizationCookieClaimService.cs, IJwtRefreshService.cs, JwtSet.cs, ILoginRedirectService.cs, IDataProtectionCertService.cs, IUrlCaseService.cs, SAIFException.cs, HttpStatusCodeException.cs, IErrorHandleable.cs, IErrorHandlerHook.cs, IStandardErrorLogInfo.cs, IWebErrorLogInfo.cs, IWindowsServiceErrorHandler.cs, IWindowsServiceError.cs, IErrorContextContainer.cs, ISpecialErrorAction.cs, SpecialErrorActionResult.cs, ShutdownExemptExceptionType.cs, BeginErrorHandlingEventArgs.cs, ErrorHandledEventArgs.cs, IServiceTaskRunner.cs, HttpClientOptions.cs
• Architecture.md