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

# SAIF.Framework.BaseN architecture

`SAIF.Framework.BaseN` is a small, self-contained numeric base-conversion utility library implemented as a Strategy-pattern toolkit: an `IConverter` contract, an abstract `ConverterBase` template implementation, four concrete converters (binary, octal, hex, Excel-style base-26), a custom exception type, and a VB extension-method facade (`BaseNConverter`) that exposes fluent `BaseNToDecimal`/`DecimalToBaseN` conversion over any `IConverter`. It has no dependency on the SAIF BOF business-object framework, no data access, no web/UI layer, and no security integration.

## Responsibilities
- Convert between decimal (`Long`/`Integer`) values and alphanumeric string representations in a configurable numeric base (binary, octal, hexadecimal, or Excel-style base-26 column naming).
- Define a common conversion contract (`IConverter`) so callers can plug in different base-N strategies interchangeably.
- Provide default template conversion logic (`ConverterBase`) that concrete converters override only where their base's digit mapping or formatting differs.
- Signal invalid digit values (exceeding a converter's base) via a dedicated exception type (`ConverterException`).
- Expose a fluent, extension-method-based API (`BaseNToDecimal`, `DecimalToBaseN`) that decouples calling code from a converter's internal digit-array plumbing.

## Component boundaries
- `IConverter`: Public interface defining the conversion contract — `Base`, `ConvertNumericToAlpha`, `ConvertAlphaToNumeric`, `FormatBaseN`.
- `ConverterBase`: Abstract (`MustInherit`) base class implementing `IConverter`; supplies default digit-conversion and formatting logic that subclasses override selectively.
- `BinaryConverter` / `OctalConverter`: Concrete converters overriding only `Base` (2 and 8 respectively); they rely on `ConverterBase`'s default alpha/numeric conversion, including its silent-zero behavior for non-numeric input.
- `HexConverter`: Concrete converter for base 16; overrides `Base`, `ConvertAlphaToNumeric`, and `ConvertNumericToAlpha` to map hex digits A–F and throws `ConverterException` on out-of-range values.
- `ExcelConverter`: Concrete converter for base 26; overrides `Base`, `ConvertNumericToAlpha`, `ConvertAlphaToNumeric`, and `FormatBaseN` to implement bijective Excel-style column-letter semantics (no zero digit), throwing `ConverterException` on out-of-range values.
- `ConverterException`: Exception type (inherits `System.Exception`) thrown by `HexConverter` and `ExcelConverter` when a digit exceeds the converter's `Base`.
- `BaseNConverter`: Public VB `Module` providing the extension-method facade (`BaseNToDecimal`, `DecimalToBaseN` with `Long`/`Integer` overloads) and private helpers (`ConvertBaseNToDecimal`, `ConvertDecimalToBaseN`, `ConvertToNumericArray`) that orchestrate calls into any `IConverter` implementation.

## Interaction model
- Calling code selects a concrete `IConverter` implementation (e.g., `HexConverter`, `ExcelConverter`) and invokes conversion via the `BaseNConverter` extension methods (`"<value>".BaseNToDecimal(converter)` or `decimalValue.DecimalToBaseN(converter)`), rather than calling converter methods directly.
- `BaseNConverter`'s helpers drive the conversion: decoding converts each character via `converter.ConvertAlphaToNumeric` into a digit array, then sums `digit * Base^position`; encoding recursively divides by `converter.Base` to build a digit list, then calls `converter.FormatBaseN` to render the final string.
- Concrete converters supply only the base-specific behavior (digit mapping, bounds checking, formatting) through `IConverter` method overrides; `ConverterBase` supplies shared/default behavior for converters that do not need custom digit mapping (`BinaryConverter`, `OctalConverter`).
- There are no other components in this repository that call into or are called by `SAIF.Framework.BaseN` — no `<ProjectReference>` links exist in either direction based on the reviewed `.vbproj` files.*

## Architecture diagram
The following diagram shows the Strategy-pattern component relationships within the library.

```mermaid
flowchart TD
	A[Caller code] --> B[BaseNConverter<br>extension methods]
	B --> C[IConverter contract]
	C --> D[ConverterBase<br>default template logic]
	D --> E[BinaryConverter<br>Base 2]
	D --> F[OctalConverter<br>Base 8]
	D --> G[HexConverter<br>Base 16]
	D --> H[ExcelConverter<br>Base 26]
	G --> I[ConverterException]
	H --> I
```

## Sequence diagram
The following diagram shows the primary decode (BaseNToDecimal) and encode (DecimalToBaseN) sequence.

```mermaid
sequenceDiagram
	participant Caller
	participant BaseNConverter
	participant Converter as IConverter implementation
	Caller->>BaseNConverter: "value".BaseNToDecimal(converter)
	BaseNConverter->>Converter: ConvertAlphaToNumeric(char) per character
	Converter-->>BaseNConverter: digit array
	BaseNConverter-->>Caller: Long result (positional sum)
	Caller->>BaseNConverter: decimalValue.DecimalToBaseN(converter)
	BaseNConverter->>Converter: ConvertNumericToAlpha(digit) per digit (recursive divide/mod)
	BaseNConverter->>Converter: FormatBaseN(digit array)
	Converter-->>BaseNConverter: formatted string
	BaseNConverter-->>Caller: BaseN string result
```

## Design constraints
- No cross-layer or cross-project dependencies exist within the repository — the library is not referenced by, nor does it reference, `clsBusinessBase`/`clsBusinessCollectionBase` or any other SAIF BOF component.*
- The library is packaged into the `SAIF.BOF.Framework` NuGet package via a source-glob mechanism in `SAIF.Framework.Core\SAIF.BOF.Framework.Core.nuspec` (`<file src="..\**\*.vb;..\**\*.cs" ... target="src"/>`), not via a `<ProjectReference>`/`IncludeReferencedProjects` build dependency.
- `ConverterBase`'s default `ConvertAlphaToNumeric` silently returns `0` for non-numeric input rather than throwing, which constrains `BinaryConverter` and `OctalConverter` (which rely on this default) to non-strict input validation.
- `HexConverter` and `ExcelConverter` enforce strict bounds checking and throw `ConverterException` for out-of-range digit values, differing in strictness from the default `ConverterBase` behavior.
- Target framework is .NET Framework 4.6.1 with only BCL/VB-runtime references (`System`, `System.Data`, `System.Xml`, `System.Core`, `System.Xml.Linq`, `System.Data.DataSetExtensions`, `Microsoft.VisualBasic`); no NuGet package dependencies exist.

## Related documentation
- [Index](index.md)
- [Overview](overview.md)
- [Dependencies](dependencies.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [Configuration](configuration.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
- `SAIF.Framework.BaseN\BaseNConverter.vb`
- `SAIF.Framework.BaseN\BinaryConverter.vb`
- `SAIF.Framework.BaseN\ConverterBase.vb`
- `SAIF.Framework.BaseN\ConverterException.vb`
- `SAIF.Framework.BaseN\ExcelConverter.vb`
- `SAIF.Framework.BaseN\HexConverter.vb`
- `SAIF.Framework.BaseN\IConverter.vb`
- `SAIF.Framework.BaseN\OctalConverter.vb`
- `SAIF.Framework.BaseN\SAIF.Framework.BaseN.vbproj`
- `SAIF.Framework.Core\SAIF.BOF.Framework.Core.nuspec`
- `Pipelines\build-vars.yml`