---
title: SAIF.NetCore.ServiceContracts architecture
summary: Architectural responsibilities, boundaries, and interaction patterns.
status: draft
owner: Framework.NCore maintainers
last_reviewed: 2026-10-02
library: SAIF.NetCore.ServiceContracts
reference_type: package
---

# 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`](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.

```mermaid
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).

```mermaid
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`](../../../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](index.md)
- [Overview](overview.md)
- [Dependencies](dependencies.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [API reference](api/index.md)
- [SAIF.NetCore.AuthService architecture](../saif-netcore-authservice/architecture.md)

> **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`