---
title: SAIF.Business.CustomerContact architecture
summary: Architectural responsibilities, boundaries, and interaction patterns.
status: draft
owner: SAIF
last_reviewed: 2026-07-24
library: SAIF.Business.CustomerContact
reference_type: package
---

# SAIF.Business.CustomerContact architecture

`SAIF.Business.CustomerContact` combines BOF aggregate persistence, reusable communication-record management, search orchestration, and external-ID conversion helpers in a single packaged business component.

## Responsibilities
- Model customer, contact, and relationship aggregates with lazy child retrieval and coordinated child saves.
- Provide reusable standalone address, email, and phone entities plus customer/contact link collections.
- Validate and execute combined customer/contact search requests.
- Convert external business identifiers into local BOF customer/contact records.
- Load localized phone and email code maps through shared SAIF business services.

## Component boundaries
- `Customer\clsCustomer`: owns the `COMPANY` aggregate, child association collections, and the customer note object.
- `Contact\clsContact`: owns the `PERSON` aggregate, child association collections, and the contact note object.
- `Customer\clsCustomerContact` / related collections: manages the `COMPANY_PERSON` relationship independently from the root contact row.
- `InfoItems` types and association collections: persist standalone `ADDRESS`, `EMAIL_ADDRESS`, and `PHONE` records and their intersection rows.
- `clsCustomerContactSearch`: validates requests and distributes result quotas across customer and contact loaders.
- `mdlCustomerContact`: bridges external identifiers to local BOF records and conversion-map rows.
- Legacy top-level `clsAddressInfo`, `clsEmailAddressInfo`, and `clsPhoneInfo` sources remain in the folder but are excluded from compilation.*

## Interaction model
- Root customer and contact aggregates obtain sequence-generated identifiers, persist the parent row, and then save child records after the parent write completes.
- Association collections track added and removed items and persist only the intersection rows that connect customers or contacts to standalone info-item records.
- Combined search validates request shape, normalizes formatted strings, and calls separate customer and contact direct-SQL loaders before merging results.
- External conversion helpers perform lookup-first logic and only create local BOF rows when a conversion mapping does not already exist.
- `mdlCodeMaps` loads shared code-table data and caches each map per culture.*

## Architecture diagram
The following diagram shows the major runtime responsibilities and data paths.

```mermaid
flowchart TD
    Caller[Consumer] --> Search[clsCustomerContactSearch]
    Caller --> Customer[clsCustomer]
    Caller --> Contact[clsContact]
    Caller --> Convert[mdlCustomerContact]
    Customer --> Company[(COMPANY)]
    Contact --> Person[(PERSON)]
    Customer --> Rel[clsCustomerContact]
    Rel --> CompanyPerson[(COMPANY_PERSON)]
    Customer --> Info[Info-item collections]
    Contact --> Info
    Info --> Address[(ADDRESS / EMAIL_ADDRESS / PHONE)]
    Info --> Links[(COMPANY_* / PERSON_*)]
    Convert --> External[(AGENCY / AGENT / POLICY / PROVIDER / others)]
    Convert --> Maps[(CUSTOMER_* mapping tables)]
    Caller --> CodeMaps[mdlCodeMaps]
    CodeMaps --> Shared[Shared SAIF code-table services]
```

## Sequence diagram
The following diagram shows the primary combined-search flow.

```mermaid
sequenceDiagram
    participant Client
    participant Search as clsCustomerContactSearch
    participant Contacts as clsContactCollection
    participant Customers as clsCustomerCollection
    participant Oracle
    Client->>Search: SearchForCustomerContacts(request)
    Search->>Search: Validate request and split limits
    Search->>Contacts: Execute contact search SQL
    Contacts->>Oracle: Query PERSON / COMPANY_PERSON
    Oracle-->>Contacts: Contact rows
    Search->>Customers: Execute customer search SQL
    Customers->>Oracle: Query COMPANY / COMPANY_PERSON
    Oracle-->>Customers: Customer rows
    Search-->>Client: Combined SearchResult
```

## Design constraints
- The library has no same-repository `<ProjectReference>` entries; SAIF business/framework dependencies are consumed as NuGet packages.
- Search execution enforces [BR-001](business-rules.md#br-001-search-requires-at-least-one-populated-criterion) and [BR-002](business-rules.md#br-002-search-results-are-capped-at-300) before any direct search SQL runs.
- Contact deletion is constrained by [BR-003](business-rules.md#br-003-contacts-with-customer-relationships-cannot-be-deleted), and relationship saves are constrained by [BR-004](business-rules.md#br-004-customer-contact-links-require-a-relationship-code).
- The library has no directly owned runtime-setting retrieval surface; configuration comes from driver registration and transitive dependency expectations.
- `Newtonsoft.Json` is imported in `mdlCustomerContact.vb`, but live JSON operations were not confirmed in the supplied findings.*

## 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)
- [Configuration](configuration.md)

> **Note:** Statements marked with `*` were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts. 

## Sources
- `Business\SAIF.Business.CustomerContact\SAIF.BOF.Business.CustomerContact.vbproj`
- `Business\SAIF.Business.CustomerContact\Customer\clsCustomer.vb`
- `Business\SAIF.Business.CustomerContact\Contact\clsContact.vb`
- `Business\SAIF.Business.CustomerContact\Customer\clsCustomerContact.vb`
- `Business\SAIF.Business.CustomerContact\InfoItems\clsAddressInfo.vb`
- `Business\SAIF.Business.CustomerContact\InfoItems\clsEmailAddressInfo.vb`
- `Business\SAIF.Business.CustomerContact\InfoItems\clsPhoneInfo.vb`
- `Business\SAIF.Business.CustomerContact\InfoItems\clsInfoCollection.vb`
- `Business\SAIF.Business.CustomerContact\clsCustomerContactSearch.vb`
- `Business\SAIF.Business.CustomerContact\mdlCustomerContact.vb`
- `Business\SAIF.Business.CustomerContact\mdlCodeMaps.vb`
- `Business\SAIF.Business.CustomerContact\packages.config`