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.

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.

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
• Overview
• Dependencies
• Operations and processes
• Business rules
• Configuration
• API reference

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