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

# SAIF.Framework.Version architecture

SAIF.Framework.Version is a small, self-contained value-object utility library that implements a custom four-part (`Major.Minor.Build.Revision`) version-number representation with parsing, formatting, comparison, and template-based incrementing. It is architecturally isolated from the rest of the SAIF Framework, with no dependencies on data access, security, UI, or other SAIF Framework projects.

## Responsibilities
- Represent a four-segment version number (`Major.Minor.Build.Revision`) as a value object via the public `Version` class, which implements `IComparable`.
- Parse a version string into its constituent segments, defaulting missing trailing segments to `"0"`.
- Format a `Version` instance back to its canonical `"{Major}.{Minor}.{Build}.{Revision}"` string form via `ToString()`.
- Compare two `Version` instances numerically (rather than as strings) via `CompareTo` and the overloaded `=`, `<>`, `<`, `>` operators.
- Produce an incremented version from a template `format` string via `Increment(format)`, supporting a `*` auto-increment token, empty-token "retain current value" semantics, and `{year}`/`{month}`/`{day}` date-template substitution.
- Provide a supporting `ToInt` string extension method (in the `Extensions` module) that coerces a version segment's leading digit run to an integer, treating non-numeric or conversion-failing input as `0`.

## Component boundaries
- `SAIF.Framework.Version.Version` (class): The sole domain type. Owns all parsing, formatting, comparison, and increment logic. Implements `IComparable`. Parallels but does not use or extend `System.Version`.
- `SAIF.Framework.Version.Extensions` (module): A single-purpose extension-method module providing `ToInt(value As String) As Integer` for the `String` type, used internally by `Version` to normalize segment values for comparison.
- No other components, layers, or sub-namespaces exist in this library — it is a flat, two-type module/class pair with no internal layering.

## Interaction model
- Callers construct a `Version` either from a delimited string (`New Version(input)`, which internally calls `Parse`) or from individual `major`/`minor`/`build`/`revision` parts, or by copying another `Version` instance.
- Callers read or compare `Version` instances using the `=`, `<>`, `<`, `>` operators or `CompareTo`, which all compare the four segments in Major → Minor → Build → Revision precedence using `ToInt`-normalized values.
- Callers request a new incremented version via `Increment(format)`, supplying a format string whose per-segment tokens can be a literal value, `*` (auto-increment relative to the prior value), an empty token (retain prior value), or date placeholders (`{year}`, `{month}`, `{day}`). `Increment` mutates the instance in place (via an internal `Update`) and returns `Me`.
- There are no calls into other SAIF Framework libraries, no I/O, no configuration reads, and no cross-layer dependencies of any kind.

## Architecture diagram

The following diagram shows the two-type component structure and the caller interaction surface.

```mermaid
flowchart TD
	Caller[Caller code] --> V[Version class<br>IComparable]
	V --> E[Extensions module<br>ToInt]
	V --> Parse[Parse]
	V --> ToString[ToString]
	V --> Compare[CompareTo / operators]
	V --> Increment[Increment]
```

The following diagram shows the primary parse-compare-increment sequence.

```mermaid
sequenceDiagram
	participant Caller
	participant Version
	participant Extensions
	Caller->>Version: New Version(input) / Parse(input)
	Version->>Version: Split on "." , default missing segments to "0"
	Caller->>Version: CompareTo / = / <> / < / >
	Version->>Extensions: ToInt(segment)
	Extensions-->>Version: normalized integer
	Version-->>Caller: comparison result
	Caller->>Version: Increment(format)
	Version->>Version: Resolve *, empty, literal, and date tokens, then update in place
	Version-->>Caller: Me (updated instance)
```

## Design constraints
- The library targets .NET Framework 3.5 and declares no `ProjectReference` or `PackageReference` dependencies, reinforcing its role as a leaf utility with zero required consumers within the build graph.
- No other project in the repository references `SAIF.Framework.Version.vbproj`; its only inclusion mechanism is the `SAIF.Framework.Core` nuspec's source-glob, which copies raw `.vb` files into a NuGet package's `src` folder rather than compiling the project itself.*
- The `ToInt` extension swallows conversion errors via an empty `Catch` block, coercing any non-numeric or unparsable segment to `0` rather than raising an exception — comparisons and increments will silently treat malformed version segments as `0`.
- **Possible copy-paste defect** (see [BR-007](business-rules.md#br-007-tautological-major-equality-check-in-the--and--operators)): in the `<` and `>` operator overloads, the "majors are equal" branch condition compares `v2.Major.ToInt = v2.Major.ToInt` (both operands reference `v2`) instead of the presumably intended `v1.Major.ToInt = v2.Major.ToInt`. Because Major is evaluated first and correctly gates entry into this branch, the tautological condition does not currently produce incorrect comparison results, but the condition itself does not verify what its structure implies and should be corrected for clarity and correctness.*

## 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.Version\Version.vb`
- `SAIF.Framework.Version\SAIF.Framework.Version.vbproj`
- `SAIF.Framework.Core\SAIF.BOF.Framework.Core.nuspec`