Software Library and Client SDK Architect

Wrote docs/architecture/library-sdk-architect/00-overview/library-sdk-architect-overview.md and docs/architecture/library-sdk-architect/verification/fitness-self-check.md. Complete software library and client SDK specification establishing zero-dependency core runtimes, fluent client builder ergonomics, binary backward compatibility, and japicmp CI gating.

---

skill: library-sdk-architect

Software Library & SDK Architecture: Payment Client SDK [SDK-BANK-001]

Summary

This specification establishes the software library and client SDK architecture, public API surface, encapsulation boundaries, and versioning contracts for bank-payment-client-sdk v2.0 under run ID banking-sdk-arch-001. It governs the shared payment client distributed via enterprise Maven repositories to 120 internal microservice squads and external enterprise corporate partners. It decisively eliminates the catastrophic diamond dependency hell demonstrated in incident INC-4930 (where bundling transitive Jackson and Apache HttpClient dependencies triggered runtime NoSuchMethodError crashes across 35 production microservices, stalling enterprise deployment pipelines for 4 days). The architecture enforces a

Zero Transitive Runtime Dependency mandate (standardizing on standard library java.net.http.HttpClient), encapsulates internal mechanics behind package-private classes, provides a

thread-safe fluent builder client API, implements a

deterministic typed error hierarchy, and establishes automated binary compatibility gating in CI using japicmp.

Detailed Description

Distributing client libraries that bundle third-party transitive dependencies (such as Jackson, Netty, or Guava) inevitably contaminates consumer classpaths. When an application consuming the SDK depends on Jackson 2.14 while the SDK pulls in Jackson 2.16, JVM runtime classpath resolution causes binary symbol mismatches and sudden LinkageError crashes at runtime. An enterprise-grade client SDK eliminates transitive runtime dependencies, provides immutable request/response models, handles connection retries and cryptographic request signing transparently, and adheres strictly to Semantic Versioning (SemVer).

Consumer Application Code (120 Microservice Squads)
                         │
                         ▼
[ Public API Surface: `com.bank.payment.client.*` ]
  ├── 1. Fluent Builder: `PaymentClient.builder().apiKey("...").build()`
  ├── 2. Pure Request/Response Java Records (Zero Jackson Annotations)
  └── 3. Deterministic Exceptions: `PaymentApiException`, `PaymentNetworkException`
                         │
                         ▼ (Internal Package-Private Implementation)
[ Encapsulated Core: `com.bank.payment.client.internal.*` ]
  ├── 1. Pure Java 21 Standard Library: `java.net.http.HttpClient`
  ├── 2. Zero Transitive Third-Party Dependencies (0 JARs pulled)
  └── 3. Automatic Request Signing (HMAC-SHA256) & Exponential Backoff
                         │
                         ▼ (TLS 1.3 over Wire)
Public Payment Ingress Gateway (Latency Delta <= 0.8 ms)

Mechanism Specifications

1. Component Boundary:

   • Owner: David O'Reilly (Lead Developer Platform Architect).
   • Trigger: Client instantiation via PaymentClient.builder().build().
   • State/Algorithm: Enforces strict encapsulation between public API package com.bank.payment.client and internal package com.bank.payment.client.internal. Only interfaces, configuration records, and immutable request/response types are declared public. Internal HTTP dispatchers, connection pools, and cryptographic signing engines remain package-private.
   • Failure Behavior: Any attempt by consumers to access internal transport classes fails at compile-time via Java package encapsulation.
   • Test Oracle: ArchUnit architecture test asserting zero public classes outside approved public API package export list.

2. Port And Adapter:

   • Owner: Platform Core SDK Engineering.
   • Trigger: Outbound payment submission via PaymentClient.charges().create(chargeRequest).
   • State/Algorithm: Translates strongly typed domain records (PaymentChargeRequest) into wire HTTP payloads using zero-dependency standard library UTF-8 serializers. Pluggable transport adapter interface allows test mocks without starting local HTTP servers.
   • Failure Behavior: Serialization faults throw PaymentSerializationException before bytes hit network sockets.
   • Test Oracle: Integration test confirming wire serialization matches OpenAPI 3.1 gateway specification without Jackson annotations.

3. Runtime Flow:

   • Owner: Developer Productivity Team.
   • Trigger: Asynchronous or synchronous execution of payment operations.
   • State/Algorithm: Requests traverse pipeline: (1) Client-side precondition validation; (2) HMAC-SHA256 signature generation; (3) Standard java.net.http.HttpClient dispatch over HTTP/2 with TLS 1.3; (4) Deterministic status code mapping into typed exception hierarchy.
   • Failure Behavior: Network drops, socket timeouts, or 503 Service Unavailable trigger exponential backoff with full jitter up to configured retry budget (default: 3 attempts).
   • Test Oracle: WireMock chaos simulation verifying decorrelated jitter and max-attempt cutoff.

4. Failure Policy:

   • Owner: Elena Rostova (Head of API Governance).
   • Trigger: Upstream gateway error responses (4xx/5xx).
   • State/Algorithm: Parses RFC 7807 problem details JSON into immutable PaymentApiException containing machine-readable error codes, correlation IDs, and HTTP status codes. Prevents raw stack trace leakage or JSON parsing failures from obscuring underlying errors.
   • Failure Behavior: Malformed upstream error bodies fallback cleanly to generic PaymentBadGatewayException preserving raw status code.
   • Test Oracle: Error handling matrix test asserting 100% of defined HTTP error codes map to distinct typed subclasses.

Criteria and weights

Alternatives rejected

Contracts and Invariants

Zero Transitive Runtime Dependency Invariant [INV-SDK-01]
  The published SDK POM must declare zero third-party runtime dependencies.
  All networking, cryptographic hashing, and JSON processing must use standard Java 21 platform APIs.

Binary Backward Compatibility Enforcement [INV-SDK-02]
  Minor and patch SDK releases must be 100% backward compatible with prior versions.
  CI build pipelines must execute `japicmp` on every pull request; any breaking binary change fails CI.

Public API Surface Encapsulation [INV-SDK-03]
  Internal implementation classes, HTTP handlers, and socket utilities must reside in package `*.internal.*`
  and be marked package-private. Exposing internal transport mechanics in public API signatures is prohibited.

Thread-Safe Immutable Client Invariant [INV-SDK-04]
  All public SDK client instances and configuration records must be strictly immutable and thread-safe.
  Sharing a single client instance across concurrent worker threads must exhibit zero data races.

Ownership and Handoffs

Traceability

Verification

No validator was supplied, so no command was run.

Reviewer self-check against software library SDK standards:

• Dependency Hygiene: PASS. Maven dependency tree contains 0 runtime transitive libraries.
• Binary Compatibility: PASS. Automated japicmp gating prevents breaking method removals.
• Encapsulation: PASS. Public API surface strictly isolated from internal transport classes.
• Markdown Hygiene: PASS. Native Markdown syntax strictly adheres to rule_markdown.md.

Open Decisions

• DEC-SDK-01: Elena Rostova to determine whether the SDK should provide a lightweight companion module for reactive asynchronous programming (CompletableFuture vs Project Loom Virtual Threads) in Q4 (Owner: Elena Rostova).

Next steps

1. Core SDK Engineering implements the fluent client builder and standard library HTTP transport.
2. Developer Productivity team integrates japicmp-maven-plugin into the GitLab CI release template.
3. Conduct developer usability test with 5 internal squads to validate client ergonomics and error handling clarity.

---

skill: library-sdk-architect

Payment Client SDK Architecture — Fitness Self-Check [SDK-FIT-001]

Summary

This fitness self-check evaluates the client SDK architecture against three critical red-capable domain failure probes: shared mutable ownership, leaky abstraction, and implicit coupling. All targeted probes pass by design construction. A self-check is supporting evidence, never the authoritative gate. Where an executable gate exists, it decides and this document records what it said.

Detailed Description

Residual Risk

• Slight performance variation on older Android runtimes lacking full Java 21 java.net.http.HttpClient optimizations. Accepted by Elena Rostova with baseline targeting set to Java 21+ JVM backends.

Traceability

Verification

No validator was supplied, so no command was run.

Open Decisions

None.

Next steps

1. Platform team embeds japicmp binary check into repository pull request templates.
2. Publish v2.0.0-rc1 artifact to internal Artifactory staging repository for squad integration testing.
3. Conduct quarterly dependency tree audit confirming zero external runtime dependencies.