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

# SAIF.Business.Utilities architecture

SAIF.Business.Utilities is a self-contained VB.NET class library (`OutputType=Library`) providing string/text-transformation helpers — title-casing with domain-specific abbreviation handling and numeric-to-English-words conversion. It has no project references, no BOF business-object base classes, and no data-access, UI, or service-hosting responsibilities.

## Responsibilities
- Convert free-text strings to title case, applying configured casing rules for abbreviations, minor words, mixed-case exceptions, and possessive suffixes (`TitleCase.ToTitleCase`).
- Provide string-extension convenience wrappers: `ToTitleCase`, `ToProperCase`, `ToPadCapitalLetters`, `ToLower`/`ToUpper` (array-level), `ContainsOnlyNumericCharacters` (`TitleCaseExtensions` module).
- Convert numeric amounts into their English-words representation, up to 999,999,999,999,999 (`mdlTextConversion.NumberToText`).
- Provide a sentence-case string extension (`ToSentenceCase`).

## Component boundaries
- `TitleCase` class: encapsulates the title-casing algorithm and its private word-list rule tables (`UpperCaseWordList`, `MixedCaseWordList`, `LowerCaseWordList`, `MixedCasePrefixList`, `MixedCaseSuffixList`, `NumberSuffixes`); no public state, purely functional (input string → output string).
- `TitleCaseExtensions` module: thin extension-method boundary over `String`, delegating most logic to `TitleCase` or to VB's built-in `StrConv`, except `ToPadCapitalLetters`, which delegates to an external `PadCapitalLettersFormat` type not defined in this library*.
- `mdlTextConversion` module: encapsulates numeric-to-text conversion logic (`NumberToText`, private `RoundDown` helper) and the unrelated `ToSentenceCase` string extension.
- No classes inherit BOF framework base types (`clsBusinessBase`, `clsBusinessCollectionBase`, `clsDataPortalInfo`, `clsRulesManager`); there is no business-object, data-portal, or rules-manager pattern in this library.

## Interaction model
- Consumers call the public shared/module-level functions and extension methods directly; there is no orchestration, lifecycle, or state shared across calls — each call is a stateless string/number transformation.
- `TitleCase.ToTitleCase` is invoked both directly and via the `String.ToTitleCase()` extension method, which simply forwards to it.
- The library exposes no interfaces or abstract types for consumers to implement; it is a pure downstream utility dependency.

The following diagram shows the two utility surfaces and how their extension methods route through the core functions.

```mermaid
flowchart TD
	Caller[Consuming library/application] --> TCExt["TitleCaseExtensions<br>(ToTitleCase, ToProperCase, ToPadCapitalLetters, ToLower/ToUpper, ContainsOnlyNumericCharacters)"]
	Caller --> TC["TitleCase.ToTitleCase"]
	Caller --> MTC["mdlTextConversion<br>(NumberToText, ToSentenceCase)"]
	TCExt --> TC
	TCExt --> PadFmt["PadCapitalLettersFormat<br>(external type, not defined in this library)"]
```

## Design constraints
- No `<ProjectReference>` elements — the library is self-contained VB.NET source with no internal dependency on other repository projects.
- References `SAIF.BOF.Framework`, `SAIF.Framework.Common`, `SAIF.HashUtil`, `SAIF.Web.API.Clients`/`Core`, `Oracle.ManagedDataAccess`, `Newtonsoft.Json`, and `RestSharp` at the project level, but none of these are exercised by the two live source files scanned (`TitleCase.vb`, `mdlTextConversion.vb`)*.
- `mdlTextConversion.NumberToText` enforces an explicit upper bound (999,999,999,999,999) and throws `ApplicationException` beyond it, rather than silently truncating or overflowing.
- No `<appSettings>`, no `IEnvironmentService`/`ConfigurationManager.AppSettings`/`DbConnectionManager` usage, no AD/security enforcement points, and no `IBusinessCriteria`/SQL usage were found — this library does not qualify for Phase 1b (DB), 1c (security), or 1d (config) documentation gates.

> **Note:** Statements marked with `*` are inferred from code behavior rather than explicit documentation or comments.

## 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)

## Sources
- `Business\SAIF.Business.Utilities\TitleCase.vb`
- `Business\SAIF.Business.Utilities\mdlTextConversion.vb`
- `Business\SAIF.Business.Utilities\SAIF.BOF.Business.Utilities.vbproj`
- `Business\SAIF.Business.Utilities\packages.config`
- `Business\SAIF.Business.Utilities\App.config`
- `Business\SAIF.Business.Utilities\Web.config`