---
title: SAIF.SAIFCode.Core architecture
summary: Architectural responsibilities, boundaries, and interaction patterns.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-09-24
library: SAIF.SAIFCode.Core
reference_type: package
---

# SAIF.SAIFCode.Core architecture

SAIF.SAIFCode.Core (assembly `SAIF.Core`) is the shared contracts and abstractions layer of the SAIF solution: it defines about 509 classes, 150 interfaces and 35 enums under `SAIF.Core.Contracts.*` and `SAIF.Core.Services`, covering DTOs, request/response objects, filter criteria, code enumerations and roughly 145 service interfaces that SAIF.Services implements, while containing no persistence, configuration, HTTP or authorization-enforcement code of its own*.

## Responsibilities
- Define DTOs, filter/search criteria and code enumerations for the solution's functional areas, the largest being Claims (211 files), Legal (69), Policies (58), Collections (43) and Documents (40)
- Declare the ~145 service interfaces (for example `IBillService`, `IEbillingService`, `IClaimInformationService`, `IClaimSecurityService`, `IPolicySecurityService`, `ICertificateSecurityService`) that SAIF.Services implements
- Declare EDI file contracts (`I837File`, `I835File`, `I277File`, `I999File`, `I837AckFile`) deriving from `IEdiFile`
- Provide the `EnumerationBase<TCode,TEnum>` static dictionary-backed code/enum pairing pattern reused across code-enumeration types (`Core/SAIF.Core/Contracts/Core/EnumerationBase.cs`)
- Perform small in-memory computations on contracts, such as bill status flags, claim alert lists and banner-text assembly (see Operations/processes in the analysis findings)
- Declare AD resource-name constants and security service interfaces/DTOs that SAIF.Services implements and enforces*

## Component boundaries
- `SAIF.Core.Contracts.*` (~90 namespaces): pure data-carrier and code-enumeration types with no infrastructure dependencies; the boundary consumers (SAIF.Domain, SAIF.Services, SAIF.Services.Web.Proxies) program against these types
- `SAIF.Core.Services` (`IClaimCustomRepoService`, `IPdfTrackingService`, `IDbConnectionService`): a small set of service abstractions with no implementation in this library; `IDbConnectionService` has no compiled implementer anywhere in the repository**
- Security contracts and constants (`ClaimSecurityAccess`, `IClaimSecurityService`, `IPolicySecurityService`, `ICertificateSecurityService`, `IGroupImageSecurityProvider`, four `SecurityRoles` classes): declared here only; all enforcement is implemented in SAIF.Services, which owns the authorization boundary
- `IUserProfileService` (`SAIF.Core.Services.UserProfile`): referenced by consumers but not defined in this repository; most likely supplied by the external `SAIF.Framework.Core` package*

## Interaction model
- SAIF.Services implements the majority of the service interfaces declared here and is the primary consumer of the contracts
- SAIF.Domain and SAIF.Services.Web.Proxies also consume these contracts as DTOs and enumerations passed across layer boundaries
- This library holds a project reference to SAIF.Data, which is an unusual upward-looking reference for a contracts layer; SAIF.Data does not reference SAIF.Core back, and the purpose is inferred to be reuse of data enums or entity types within some contracts*
- Authorization is a declare-here, enforce-elsewhere pattern: the AD resource-name constants and security service interfaces are declared in this library, and `SAIF.Services` implementations call the external `IUserProfileService.GetCurrentUser().IsAuthorized(resource)` to enforce them*

## Architecture diagram
The following diagram shows high-level component interactions.

```mermaid
flowchart TD
	A["SAIF.Core.Contracts.*<br>DTOs, filters, enumerations"] --> B["SAIF.Core.Services<br>service interfaces"]
	B --> C["SAIF.Services<br>implements contracts and enforces security"]
	A --> D[SAIF.Domain]
	A --> E[SAIF.Services.Web.Proxies]
	A --> F["SAIF.Data<br>project reference for shared types"]
	C --> G["IUserProfileService<br>(external, SAIF.Framework.Core)"]
```

## Sequence diagram
The following diagram shows the primary request/response sequence.

```mermaid
sequenceDiagram
	participant Client
	participant Service as SAIF.Services implementation
	participant Contract as SAIF.Core contract/interface
	participant Auth as IUserProfileService (external)
	Client->>Service: Call service interface (e.g. IClaimSecurityService.GetClaimSecurity)
	Service->>Contract: Read/populate DTO defined in SAIF.Core
	Service->>Auth: IsAuthorized(resource)
	Auth-->>Service: Authorization result
	Service-->>Client: Populated contract (e.g. ClaimSecurityAccess)
```

## Design constraints
- This library must remain free of persistence, configuration and HTTP/authorization-enforcement logic; it is a contracts-only layer and enforcement responsibilities belong to SAIF.Services*
- Security is declared, not enforced, here: 16 AD resource-name constants and 9 security service contracts are defined in this library, but only SAIF.Services may perform the `IsAuthorized` checks against them; 6 of the 16 constants have no compiled enforcement point in the repository (referenced only by `NoteService.cs` files excluded from the SAIF.Services project build) and 4 (`ViewRole` constants) are never referenced anywhere in the repository**
- `ILegalSecurityOverrideService` has no implementation found in the repository; any consumer relying on it must supply an external implementer**
- The upward-looking project reference to SAIF.Data must not be treated as a two-way dependency; SAIF.Data does not reference this library back*
- The hard-coded path `SubpoenaDocuments.XPressionsFileAttachmentFolder = "D:\Attachments"` is an environment-specific constant baked into a contract type rather than externalized configuration

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

## Related documentation
- [Index](index.md)
- [Overview](overview.md)
- [Dependencies](dependencies.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [Security and authorization](security-authorization.md)
- [API reference](api/index.md)

## Sources
- Core/SAIF.Core/SAIF.SAIFCode.Core.csproj
- Core/SAIF.Core/SAIF.SAIFCode.Core.nuspec
- Core/SAIF.Core/packages.config
- Core/SAIF.Core/app.config
- Core/SAIF.Core/Services/IDbConnectionService.cs
- Core/SAIF.Core/Contracts/Core/EnumerationBase.cs
- Core/SAIF.Core/Contracts/Legal/Subpoenas/SubpoenaDocuments.cs
- Core/SAIF.Core/Contracts/Security/ClaimSecurityAccess.cs
- Core/SAIF.Core/Contracts/Security/IClaimSecurityService.cs
- Core/SAIF.Core/Contracts/Policies/Security/IPolicySecurityService.cs
- Core/SAIF.Core/Contracts/Policies/Certificates/ICertificateSecurityService.cs
- Core/SAIF.Core/Contracts/Groups/Imaging/IGroupImageSecurityProvider.cs
- Core/SAIF.Core/Contracts/Legal/SecurityOverrides/ILegalSecurityOverrideService.cs
- Core/SAIF.Core/Contracts/Agencies/Imaging/SecurityRoles.cs
- Core/SAIF.Core/Contracts/Agencies/Notes/SecurityRoles.cs
- Core/SAIF.Core/Contracts/Groups/Imaging/SecurityRoles.cs
- Core/SAIF.Core/Contracts/Groups/Notes/SecurityRoles.cs