Example: library architecture¶

architecture.md explains how a library is put together — its internal boundaries, how callers interact with it, and the constraints it operates under. Doc gen produces one per library alongside overview.md.

What reviewers should check¶

Both diagrams are present and use standard ```mermaid fences. The legacy Azure DevOps colon-prefixed fence style is a blocker, and a diagram that renders as raw text on the portal is a failed page.
Sections appear in template order: Responsibilities, Component boundaries, Interaction model, Architecture diagram, Sequence diagram, Design constraints, Related documentation, Sources.
The architecture diagram names real types from the library rather than generic boxes like "Component A", and the sequence diagram participants match those names.
## Component boundaries states what each component owns and what it must not do, not just a restatement of the type name.
Related documentation uses canonical document names and omits architecture.md, because that is this page.
Design constraints are specific to this library — target framework, threading behavior, packaging — and are traceable to the sources listed at the bottom.

Example¶

The document below is a complete, correct architecture.md for a fictional library.

View rendered example — the same document as a real page, so you can compare rendering as well as source.

---
title: SAIF.Framework.Validation architecture
summary: Architectural responsibilities, boundaries, and interaction patterns.
status: draft
owner: Policy Systems Team
last_reviewed: 2026-02-18
library: SAIF.Framework.Validation
reference_type: package
---

# SAIF.Framework.Validation architecture

SAIF.Framework.Validation is a passive, in-process library: it owns no threads,
opens no connections, and performs no I/O other than reading rule set XML from
disk on first use. Consuming applications construct a `ValidationEngine`, hand
it a record and an `IValidationContext`, and receive a `ValidationResult`. All
environment-specific behavior — jurisdiction, effective date, current user —
enters through the context interface, which keeps the rule evaluation core free
of any dependency on the hosting application.

## Responsibilities
- Resolves a named rule set to a cached, ordered collection of
  `ValidationRule` instances.
- Evaluates every rule in a set against the supplied record, without
  short-circuiting on the first failure.
- Aggregates failures and warnings into a single `ValidationResult` keyed by
  business rule identifier.
- Isolates callers from rule storage format, so rule set XML can change without
  a consumer code change.

## Component boundaries
- `ValidationEngine`: Owns rule execution and result aggregation. It does not
  read files, does not know the rule set XML schema, and never throws for a
  business validation failure.
- `RuleSetLoader`: Owns all file access and XML parsing, plus the in-memory
  rule set cache. It is the only component that touches the file system.
- `ValidationRule`: Owns evaluation of a single condition against one field or
  record. It holds no state between evaluations.
- `ValidationResult`: A read-only carrier of outcomes. It performs no
  evaluation and is safe to pass across application layers.
- `IValidationContext`: The boundary between the library and its host. The
  library defines the contract; consuming applications implement it.

## Interaction model
- The consuming application resolves or constructs a `ValidationEngine`,
  supplying a rule set name and an `IValidationContext` implementation.
- `ValidationEngine` asks `RuleSetLoader` for the named rule set.
  `RuleSetLoader` returns the cached collection, or parses the XML file on a
  cache miss and caches the result.
- `ValidationEngine` evaluates each `ValidationRule` in declaration order,
  passing the record and the context.
- Failures and warnings accumulate in a `ValidationResult`, which is returned
  to the caller. `SAIF.Claims.Intake` renders failures next to the offending
  fields; `SAIF.PremiumAudit.Batch` writes them to the batch error log and
  skips the record.

## Architecture diagram
The following diagram shows high-level component interactions.

```mermaid
flowchart TD
    A[SAIF.Claims.Intake] --> C[ValidationEngine]
    B[SAIF.PremiumAudit.Batch] --> C
    C --> D[RuleSetLoader]
    D --> E[(Rule set XML files)]
    C --> F[ValidationRule]
    F --> G[ValidationResult]
    H[IValidationContext] --> C
    H --> F
```

## Sequence diagram
The following diagram shows the primary request/response sequence.

```mermaid
sequenceDiagram
    participant Client as SAIF.Claims.Intake
    participant Engine as ValidationEngine
    participant Loader as RuleSetLoader
    participant Rule as ValidationRule
    Client->>Engine: Validate(claimRecord, context)
    Engine->>Loader: GetRuleSet("ClaimIntake")
    Loader-->>Engine: Ordered ValidationRule collection
    loop For each rule in the set
        Engine->>Rule: Evaluate(claimRecord, context)
        Rule-->>Engine: Pass, warning, or failure with rule ID
    end
    Engine-->>Client: ValidationResult with all failures
```

## Design constraints
- Targets .NET Framework 4.8 because both consuming applications remain on the
  full framework; no .NET Standard or .NET 6+ target is produced.
- The rule set cache is a shared static dictionary and is populated on first
  use, so rule set XML changes require an application recycle to take effect.
- `ValidationEngine` instances are not thread-safe and must not be shared
  across requests; `SAIF.Claims.Intake` creates one per request.
- The library must not reference any data access assembly. Rules receive
  already-materialized records so that batch and web callers behave
  identically.
- Validation failures are returned, never thrown. Exceptions escaping the
  engine indicate a configuration or rule authoring defect.

## Related documentation
- [Index](index.md)
- [Overview](overview.md)
- [Dependencies](dependencies.md)
- [Configuration](configuration.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [API reference](api/index.md)

## Sources
- src/SAIF.Framework.Validation/ValidationEngine.vb
- src/SAIF.Framework.Validation/RuleSetLoader.vb
- src/SAIF.Framework.Validation/Rules/ValidationRule.vb
- src/SAIF.Framework.Validation/IValidationContext.vb
- src/SAIF.Framework.Validation/SAIF.Framework.Validation.vbproj