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

# SAIF.Domain architecture

SAIF.Domain is a domain-logic layer that sits between the contracts library SAIF.Core and the data-access libraries SAIF.Data / SAIF.Data.Guidewire below it, and the application-services library SAIF.Services above it, which is its only production consumer; it wraps NHibernate-mapped entities in domain objects (`DomainBase<TItem>`, `DomainQueryBase<TItem,TQueryProvider>`, `DomainRepositoryBase<TItem>`) and layers electronic-billing (ebilling), claims, audit, certificate-holder, packet-generation and EDI-processing behaviour on top of them, reading and writing exclusively through the framework `IRepositoryFactory` / `IUnitOfWork` abstractions and SAIF.Data query-provider interfaces, with no configuration reads, no authorization checks, and no direct transaction control of its own.

## Responsibilities
- Wrap SAIF.Data entities in domain objects that expose behaviour methods such as `Bill.ModifyStatus`, `Bill.SendToAudit`, `Audit.AllowAllServices` and `CertificateHolder.Expire`.
- Assign, index and generate CBP (converted-bill-processing) bills from inbound electronic bills (ebills), including patient, provider and bill-service indexing.
- Parse and build EDI files: inbound 837 claims (`File837Extractor`), outbound 835 remittances, 277 claim-acknowledgement responses and 837 acknowledgements.
- Generate explanation-of-benefits (EOB) records and their adjustments/remittance advices from Guidewire payment extracts.
- Manage bill audits, audit notes and bill regeneration.
- Manage policy certificate-holder lifecycle (create, update, expire, reinstate, supersede).
- Present a Guidewire-backed `Claim` read model that merges legacy WCIS entities with Guidewire ClaimCenter API data via `GuidewireToLegacyMapper`.
- Generate document packets (`PacketManager`, `PacketGenerator`, `PacketDefinition`) for policy correspondence.

## Component boundaries
- `SAIF.Domain` (root namespace): `DomainBase<TItem>`, `DomainQueryBase<TItem,TQueryProvider>`, `DomainRepositoryBase<TItem>` — shared base classes that inject a query provider or `IRepositoryFactory` into concrete domain types.
- `SAIF.Domain.Claims.Ebilling` and `.Indexing`: ebilling lifecycle — bill assignment (`BillAssignment`), patient/provider/service indexing (`PatientIndexer`, `ProviderIndexer`, `ProviderIndexerV2`, `BillServiceIndexer`, `ProviderMatcher`, match rules), CBP bill generation (`GenerateCbpBills`), EDI file processing (`File837Extractor`, `File835Builder`, `File277CaBuilder`, `File837AckBuilder`, `EdiBuildSegments`), EOB generation (`EobBuilder`), and service-code resolution (`ServiceCodeManager`).
- `SAIF.Domain.Model.Claims.Bills` and `.Audits` / `.Notes`: bill behaviours (`Bill`), audits (`Audit`, `AuditedService`), audit notes (`AuditNote`), and bill regeneration (`BillRegenerator`, in `Claims/Bills/`).
- `SAIF.Domain.Model.Claims`: the Guidewire-backed `Claim` read model, `ClaimAdjuster`, `ClaimReserveGenerator`, `SecureClaimAttributes` and `Worker`.
- `SAIF.Domain.Model.Policies(.Certificates)`: `Policy` and `CertificateHolder` lifecycle management.
- `SAIF.Domain.Tasks.Documents.Packets`: `PacketManager`, `PacketGenerator`, `PacketDefinition`, `PacketRequest` for document-packet assembly.
- `SAIF.Domain.Mappers` (internal): `GuidewireToLegacyMapper`, used by the `Claim` static constructor to configure AutoMapper maps.
- `SAIF.Domain.Model.Employees` / `.Imaging`: `Employee` (delegates to SAIF.Framework.Core `IUserProfileService`) and `Image`.

## Interaction model
- SAIF.Services is the sole production consumer and owns transaction boundaries: it calls into SAIF.Domain types and is responsible for `IUnitOfWork.Begin`/`Commit` around them.
- Domain wrapper types (`DomainBase<T>` subclasses) receive query providers or `IRepositoryFactory` through constructor injection and read/write SAIF.Data entities via `GetRepository<T>().Add/Delete/Query()`.
- Claim-centric operations delegate to SAIF.Data.Guidewire's `ICCClaimApiService`, `IClaimDataApiClient` and `IMedicalBillingApiService` for ClaimCenter data (contacts, MCO, conditions, financials, payment extracts) rather than reading claim data from the local database.
- Provider-location matching uses a strategy/rule-set pattern: `ProviderIndexerV2` builds candidate address lists, selects an ordered set of `IProviderMatchRule` implementations, and `ProviderMatcher` returns the first unique match.
- Inbound 837 files are parsed by a segment state machine in `File837Extractor`, which has static mutable state and is therefore not safe for concurrent use*.

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

```mermaid
flowchart TD
	Services["SAIF.Services<br>application services (only production consumer)"] --> Domain["SAIF.Domain<br>domain-logic layer"]
	Domain --> Core["SAIF.Core<br>contracts (SAIF.SAIFCode.Core)"]
	Domain --> Data["SAIF.Data<br>entities and query providers"]
	Domain --> Guidewire["SAIF.Data.Guidewire<br>ClaimCenter API clients"]
	Domain --> Framework["SAIF.Framework.Core / .Common<br>IRepositoryFactory, IUnitOfWork"]
	Data --> NHibernate["SAIF.Data.NHibernate<br>ClassMaps (Oracle*)"]
```

## Sequence diagram
The following diagram shows the primary request/response sequence for bill assignment (OP-DOM-01).

```mermaid
sequenceDiagram
	participant Client as SAIF.Services
	participant Service as BillAssignment (SAIF.Domain)
	participant Dependency as ICCClaimApiService (SAIF.Data.Guidewire)
	Client->>Service: AssignBillsResponsibily(ebill)
	Service->>Dependency: GetClaim(claimNumber)
	Dependency-->>Service: Claim data (contacts, MCO, conditions)
	Service-->>Client: Ebill status set to Assigned
```

## Design constraints
- No configuration reads: a scan found no `ConfigurationManager`, `IEnvironmentService`, `DbConnectionManager`, `AppSettings` or `GetConfigSetting` usage; hard-coded values that behave like configuration (thresholds 20000 and 900, responsible party "SYSTEM", packet definitions PKT001–PKT038, Vignette IFN constants) are treated as business rules instead.
- No authorization checks: there are no `IsAuthorized` calls or authorization attributes in this library; `Claim.BuildSecurityAttributes` only computes `SecureClaimAttributes` (`IsConflictClaim`, `IsSecureClaim`) for consumers such as SAIF.Services `ClaimSecurityService` to evaluate.
- No transaction control: callers in SAIF.Services own `IUnitOfWork.Begin`/`Commit`; SAIF.Domain never begins or commits a unit of work itself.
- `File837Extractor` uses static mutable state, so batch jobs that process files concurrently could corrupt each other*.
- No raw SQL, stored procedures or ADO.NET; all persistence goes through NHibernate ORM operations mediated by `IRepositoryFactory`/`IUnitOfWork`, with SQL generated at runtime from ClassMaps in `SAIF.Data.NHibernate`. See [Database tables](database-tables.md) and the [SQL catalog](sql/index.md) for the full 33-operation catalog.
- The database is inferred to be Oracle* (from the 900-row IN-list chunking comment in `EobBuilder` and from SAIF.Data entity mappings); no connection strings are held in this library.

## Related documentation
- [Index](index.md)
- [Overview](overview.md)
- [Dependencies](dependencies.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [Database tables](database-tables.md)
- [SQL catalog](sql/index.md)
- [API reference](api/index.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
- `Domain/SAIF.Domain/SAIF.Domain.csproj`
- `Domain/SAIF.Domain/DomainBase.cs`, `DomainQueryBase.cs`, `DomainRepositoryBase.cs`
- `Domain/SAIF.Domain/Claims/Ebilling/BillAssignment.cs`, `GenerateCBPBills.cs`, `File837Extractor.cs`, `File835Builder.cs`, `File277CaBuilder.cs`, `File837AckBuilder.cs`, `EdiBuildSegments.cs`, `EobBuilder.cs`, `ServiceCodeManager.cs`
- `Domain/SAIF.Domain/Claims/Ebilling/Indexing/*.cs`
- `Domain/SAIF.Domain/Claims/Bills/BillRegenerator.cs`
- `Domain/SAIF.Domain/Model/Claims/Bills/Bill.cs`, `Model/Claims/Bills/Audits/Audit.cs`, `Model/Claims/Bills/Notes/AuditNote.cs`
- `Domain/SAIF.Domain/Model/Claims/Claim.cs`, `ClaimReserveGenerator.cs`, `SecureClaimAttributes.cs`, `Worker.cs`
- `Domain/SAIF.Domain/Model/Policies/Certificates/CertificateHolder.cs`, `Model/Policies/Policy.cs`
- `Domain/SAIF.Domain/Mappers/GuidewireToLegacyMapper.cs`
- `Domain/SAIF.Domain/Tasks/Documents/Packets/PacketManager.cs`, `PacketGenerator.cs`, `PacketDefinition.cs`
- `Core/SAIF.Core/SAIF.SAIFCode.Core.nuspec`
- `Data/SAIF.Data.NHibernate/Mappings/Claims/Bills/CbpBillMap.cs`