---
title: Architecture
summary: How the proxy is constructed, configured, invoked, and disposed.
status: draft
owner: SAIF.Core documentation
last_reviewed: 2026-09-24
---

# Architecture

This repository reaches the third-party `SimpleCertifiedMail ADS API`† only through the authored `SimpleCertifiedMailServiceProxy` wrapper, which builds a `BasicHttpBinding(Transport)` in code and resolves its endpoint from an environment configuration setting rather than from the generated `app.config` entry.

## Proxy mechanism

| Aspect | Finding |
| --- | --- |
| Mechanism | Service Reference (svcutil) |
| Proxy type | `ADSAPISoapClient` (`public`) |
| Base type | `System.ServiceModel.ClientBase<T>` |
| Contract type | `public interface ADSAPISoap` |
| Constructed in | `SimpleCertifiedMailServiceProxy` constructor (`Services/SAIF.Services.Web.Proxies/SimpleCertifiedMailServiceProxy.cs:31-43`) |
| Binding configured in | Code — `BasicHttpBinding(BasicHttpSecurityMode.Transport)` built in the wrapper constructor |
| Address supplied by | `IEnvironmentService.GetConfigSetting("SimpleCertifiedMailService.Url")`, read in the wrapper constructor; the generated `<client><endpoint>` in `app.config` is bypassed |

## Architecture diagram

The following construction-path diagram visualizes how a call reaches the remote third-party service.

```mermaid
flowchart TD
    CALLER["SubpoenaLabelService<br>.GenerateRecipientLabels /<br>.GenerateOpposingCounselLabel"] --> WRAP["SimpleCertifiedMailServiceProxy<br>hand-written wrapper"]
    WRAP --> BIND["BasicHttpBinding(Transport)<br>built in code, unbounded quotas"]
    BIND --> ADDR["EndpointAddress from<br>SimpleCertifiedMailService.Url<br>(IEnvironmentService)"]
    ADDR --> PROXY["ADSAPISoapClient<br>generated proxy (public)"]
    PROXY --> REMOTE["SimpleCertifiedMail ADS API<br>third-party HTTPS service"]
    WRAP --> DISPOSE["Close() only<br>on Dispose()"]
```

## Hand-written wrapper

| Field | Value |
| --- | --- |
| **Type** | `SimpleCertifiedMailServiceProxy` |
| **Source** | `Services/SAIF.Services.Web.Proxies/SimpleCertifiedMailServiceProxy.cs` |
| **Visibility** | `public` |
| **Implements** | `IDisposable`, `ISimpleCertifiedMailServiceProxy` |
| **Responsibility** | Builds the HTTPS binding, resolves the endpoint from configuration, maps `CertifiedLabelData` into the wire request (including field truncation and credential fallback), calls `getCertifiedLabel`, converts an in-band failure into a typed exception, and can render the returned label to a `.gif` file |
| **Proxy lifetime** | Per `SimpleCertifiedMailServiceProxy` instance |

| Configuration applied | Value | Source |
| --- | --- | --- |
| `BasicHttpBinding` security mode | `Transport` (HTTPS) | `SimpleCertifiedMailServiceProxy.cs:31` |
| Transport client credential | `None` | `SimpleCertifiedMailServiceProxy.cs:40` |
| Message client credential | `Certificate` — **has no effect** under `BasicHttpSecurityMode.Transport`; message credentials apply only in `Message` / `TransportWithMessageCredential` modes* | `SimpleCertifiedMailServiceProxy.cs:41` |
| `MaxReceivedMessageSize` | `int.MaxValue` | `SimpleCertifiedMailServiceProxy.cs:33` |
| `MaxBufferSize` | `int.MaxValue` | `SimpleCertifiedMailServiceProxy.cs:34` |
| Reader quotas (`MaxArrayLength`) | `int.MaxValue` | `SimpleCertifiedMailServiceProxy.cs:35` |
| Timeouts | None set — binding defaults apply | `SimpleCertifiedMailServiceProxy.cs:31-41` |

## Endpoint resolution

| Environment | Address | Resolved from | Changeable without a rebuild |
| --- | --- | --- | --- |
| All | Unresolved** — `SimpleCertifiedMailService.Url` does not appear in `environments.xml` or any `*.config`/`*.xml` in this repository | `IEnvironmentService.GetConfigSetting("SimpleCertifiedMailService.Url")` (`SimpleCertifiedMailServiceProxy.cs:42`) | Yes — the value is read from configuration at construction time, not compiled in |

A commented-out literal on the same line (`https://api.simplecertifiedmail.com/v3.2/ADS.asmx`) suggests the intended production value*, matching the generation-time WSDL address.

## Lifetime and disposal

| Aspect | Finding |
| --- | --- |
| Proxy lifetime | Per `SimpleCertifiedMailServiceProxy` instance |
| Disposal | `Close()` only — `SimpleCertifiedMailServiceProxy.cs:159-173` |
| Faulted-channel handling | No `Abort()` path; `Close()` on a faulted channel throws `CommunicationObjectFaultedException` after a transport fault* |
| Thread safety | Not determined from source |

## Integration points

| System | Type | Purpose |
| --- | --- | --- |
| `SimpleCertifiedMail ADS API`† | SOAP service (third-party ASMX) | Generates certified-mail shipping labels for subpoena recipients and opposing counsel |

## Related documentation
- [Client index](index.md)
- [Overview](overview.md)
- [Contract](contract.md)
- [Operation map](operation-map.md)
- [Client reference](reference.md)
- [Consumption](consumption.md)
- [Dependencies](dependencies.md)
- [Business rules](business-rules.md)
- [Tech debt](tech-debt.md)

> **Note:** Statements marked with `†` are derived from dependency library
> documentation via the Legends CLI. Statements marked with `*` were inferred
> from code structure or contextual evidence. Statements marked with `**` could
> not be confirmed; treat as unknown until verified.

## Sources
- `Services/SAIF.Services.Web.Proxies/SimpleCertifiedMailServiceProxy.cs`
- `Services/SAIF.Services.Web.Proxies/app.config`
- `Services/SAIF.Services.Web.Proxies/Service References/SimpleCertifiedMail/Reference.svcmap`
- `Services/SAIF.Services.Web.Proxies/Service References/SimpleCertifiedMail/Reference.cs`
- `Services/SAIF.Services.WebApi/EnvironmentApi/App_Data/environments.xml`