[huangji6693-max]

Summary

Documents the complete architecture and design decisions of @stellar-split/sdk and adds a programmatic ArchitectureRegistry catalog with automated verification tests.

Closes #1199

Changes

• Architecture Mapping (ARCHITECTURE.md, src/architectureRegistry.ts):
  • Mapped the 6-layer downward dependency architecture:
    1. Layer 1: Presentation, UI & Framework Bindings (./react, ./ui, ./lazy, src/qr)
    2. Layer 2: Client Orchestration & Event Bus (StellarSplitClient, NetworkEnvironment, TypedEventEmitter)
    3. Layer 3: Domain Engines (InvoiceStateMachine, PaymentOrchestrator, Signer, sep41Adapter)
    4. Layer 4: Plugin, Interceptor, Deduplication & Telemetry Pipeline (PluginRegistry, Deduplicator, TelemetryHookManager)
    5. Layer 5: Resilience, Caching & RPC Transport (RpcLoadBalancer, CircuitBreaker, OfflineQueue, RpcConnectionPool)
    6. Layer 6: Stellar Protocol Boundary (xdrDecoder, StellarSplitError taxonomy, horizonErrorClassifier)
• Design Decisions (ARCHITECTURE.md, docs/ARCHITECTURE_GUIDE.md):
  • Documented Architecture Decision Records (ADR-001 through ADR-006) covering strict bigint stroop representation, simulate-before-submit preflight pipeline, onion plugin middleware vs. fire-and-forget telemetry hooks, request deduplication for idempotency, multi-endpoint RPC load balancing with circuit breaking, and subpath exports for tree-shaking.
• Diagrams (ARCHITECTURE.md):
  • Added Mermaid diagrams for the 6-layer system architecture (flowchart TB), mutating transaction lifecycle (sequenceDiagram), and resilience circuit breaker state machine (stateDiagram-v2).
• Public API Surface & Extension Points (ARCHITECTURE.md, docs/ARCHITECTURE_GUIDE.md):
  • Documented all 8 package.json subpath entrypoints (., ./ui, ./react, ./testing, ./mock, ./telemetry, ./utils, ./lazy).
  • Documented 6 extension points (SdkPlugin, TelemetryHooks, custom Signer, request/response interceptors, HealthCheckRegistry, and registerUpgradeMigration) with working TypeScript examples.
  • Added complete internal documentation links and external Stellar/Soroban SEP references (SEP-0010, SEP-0024, SEP-0031, SEP-0041).
• Verification (test/architectureDocs.test.ts):
  • Added 8 unit tests validating ArchitectureRegistry, layer ordering, ADRs, Mermaid diagrams, package.json subpath coverage, extension points, and reference links.

Verification

• npx vitest run test/architectureDocs.test.ts (8/8 passing)
• npm test (all core client, retry policy, and network environment tests passing)