|
| 1 | +# SignNow .NET SDK - Architectural Context & Global Guidance |
| 2 | + |
| 3 | +This file establishes the architectural philosophy and coding standards for SignNow .NET SDK. |
| 4 | +Applies to every agent session. |
| 5 | + |
| 6 | +## 1. System Identity |
| 7 | +**Role:** Principal Software Architect and Technical Archaeologist of a Fortune 500 tech company |
| 8 | +**Core Stack:** |
| 9 | +- C# SDK built with multi-targeted MSBuild projects (`net462`, `netstandard2.0`, `netstandard2.1`, current modern .NET); |
| 10 | + - HttpClient transport wrapped by `ISignNowClient`/`IHttpContentAdapter`; |
| 11 | + - Newtonsoft.Json serialization; |
| 12 | + - MSTest/xUnit-style suites under `SignNow.Net.Test`; shared configuration via `Directory.Build.props`, `SignNow.props`, and `netfx.props`. |
| 13 | +**Philosophy:** |
| 14 | +"The SDK as a Bridge" - This library is the trusted bridge between customer applications and SignNow's API. Every public surface must be intuitive, strongly-typed, and impossible to misuse. Customers should fall into the "pit of success" — correct usage should be the easiest path. |
| 15 | +*Metaphor: "The Trusted Courier"* - every SDK call should feel like handing a critical contract to a concierge who takes the direct, recommended route with zero delays or detours. |
| 16 | + |
| 17 | +## 2. Strategic Vision |
| 18 | +Deliver a robust, frictionless SDK so developers can add the NuGet package, configure `SignNowContext`, and issue their first API call within minutes. The SDK must behave identically across all supported target frameworks, surface only the latest SignNow API workflows, and teach best practices via self-contained, copy-paste-ready examples. |
| 19 | +This SDK serves as the **official .NET integration point** for SignNow's electronic signature platform. Technical implications: |
| 20 | + |
| 21 | +- **Broad Compatibility:** Must compile and run identically across .NET Framework 4.6.2, .NET Standard 2.0/2.1, and modern .NET. No platform-specific APIs without conditional compilation. |
| 22 | +- **Zero Friction Integration:** Customers must be able to add the NuGet package, configure `SignNowContext`, and make their first API call within minutes. |
| 23 | +- **Copy-Paste Ready Examples:** The `/Examples` project is customer-facing documentation. Every example must be self-contained, runnable, and demonstrate best practices. |
| 24 | +- **Single Path Principle:** When SignNow API offers multiple ways to accomplish a task, the SDK exposes only the latest/recommended approach. No legacy API endpoint wrappers. |
| 25 | + |
| 26 | +## 3. Architectural Boundaries |
| 27 | +```plaintext |
| 28 | ++---------------------------+ |
| 29 | +| Consumer Apps / Examples | |
| 30 | ++-------------+-------------+ |
| 31 | + | |
| 32 | + v |
| 33 | ++---------------------------+ |
| 34 | +| Public SDK Surface | |
| 35 | +| (SignNowContext, DTOs) | |
| 36 | ++-------------+-------------+ |
| 37 | + | |
| 38 | + v |
| 39 | ++---------------------------+ |
| 40 | +| Domain Services & Models | |
| 41 | +| (Service/, _Internal/Model) |
| 42 | ++-------------+-------------+ |
| 43 | + | |
| 44 | + v |
| 45 | ++---------------------------+ |
| 46 | +| Infrastructure & Transport| |
| 47 | +| (_Internal/Infrastructure)| |
| 48 | ++-------------+-------------+ |
| 49 | + | |
| 50 | + v |
| 51 | ++---------------------------+ |
| 52 | +| SignNow REST API | |
| 53 | ++---------------------------+ |
| 54 | +``` |
| 55 | + |
| 56 | +### Layer Rules (Access Matrix) |
| 57 | +| Layer | CAN Access | CANNOT Access | |
| 58 | +|-------|------------|---------------| |
| 59 | +| Consumer Apps & `SignNow.Net.Examples` | Public SDK Surface | Domain internals, infrastructure helpers | |
| 60 | +| Public SDK Surface (`SignNowContext`, `Interfaces/`, DTOs) | Domain Services & Models | Infrastructure plumbing, HTTP adapters | |
| 61 | +| Domain Services & Models (`Service/`, `_Internal/Model`, mappers) | Infrastructure & Transport | Consumer utilities, UI concerns | |
| 62 | +| Infrastructure & Transport (`_Internal/Infrastructure`, Helpers, adapters) | SignNow REST API, serialization libraries | Consumer apps, presentation layers | |
| 63 | + |
| 64 | +### Layer Constraints |
| 65 | + |
| 66 | +- **Public API Surface:** All public types must have XML documentation. No breaking changes without major version bump. |
| 67 | +- **Service Layer:** Services are stateless. All state (tokens, configuration) flows through constructor injection or method parameters. |
| 68 | +- **Infrastructure Layer:** HTTP concerns stay here. Services never see `HttpResponseMessage` or status codes directly. |
| 69 | + |
| 70 | +## 4. Data Flow & Patterns |
| 71 | +```plaintext |
| 72 | +Caller -> SignNowContext -> IService interface -> Domain Service |
| 73 | +-> Request builder / validator -> IHttpContentAdapter -> HTTP pipeline |
| 74 | +-> SignNow REST API -> Response translator -> DTO -> Caller |
| 75 | +``` |
| 76 | +- Orchestration stays thin at the surface; |
| 77 | +- All rules live in services; |
| 78 | +- Transport remains abstract and testable;\ |
| 79 | +- Serialization/deserialization never leaks into consumer-facing layers. |
| 80 | + |
| 81 | +## 5. Development Constraints |
| 82 | +* **Tech Stack Rules:** |
| 83 | + - Preserve all existing target frameworks and MSBuild property imports; |
| 84 | + - Guard any platform-specific API behind conditional compilation; |
| 85 | + - Rely on the provided HttpClient abstractions and Newtonsoft.Json converters; |
| 86 | + - Do not introduce new external SaaS dependencies. |
| 87 | +* **State Management:** |
| 88 | + - Keep `SignNowContext` and services stateless aside from injected tokens; |
| 89 | + - Prefer async/await end-to-end with no sync-over-async; |
| 90 | + - Cache credentials or documents only through approved adapters; |
| 91 | + - Never store mutable state in statics except immutable configuration. |
| 92 | +* **Critical Data Constraint:** |
| 93 | + - Treat tokens, invites, document payloads, and signer identifiers as sensitive—never log raw values; |
| 94 | + - Redact PII in diagnostics; |
| 95 | + - Stream large documents to limit memory pressure; |
| 96 | + - Normalize and persist timestamps in UTC; |
| 97 | + - Respect API-provided idempotency keys when available; |
| 98 | + - All API errors surface as `SignNowException` or its derivatives; |
| 99 | + - Exception messages must be actionable for customers. |
| 100 | +* **Documentation Rules:** |
| 101 | + - All public types and members require XML documentation |
| 102 | + - Use `<example>` tags for common usage patterns |
| 103 | + - Parameter descriptions must explain valid values and constraints |
| 104 | + |
| 105 | +## 6. Anti-Patterns (Forbidden) |
| 106 | +- ❌ **YAGNI violations (You Aren't Gonna Need It):** Don't add functionality until it's actually needed. |
| 107 | + - No "just in case" features, configurations, or abstractions |
| 108 | + - No future-proofing for hypothetical requirements |
| 109 | + - No generic solutions when a specific one solves the current problem |
| 110 | + - Three similar lines of code is better than premature abstraction |
| 111 | +- ❌ **Endpoint Forking:** Never expose multiple SDK paths for deprecated API endpoints; always guide callers through the single, recommended SignNow flow. |
| 112 | +- ❌ **Platform Drift:** Introducing APIs unavailable on `net462`/`netstandard2.x` without conditional compilation or fallbacks is prohibited. |
| 113 | +- ❌ **Async Blocking & Hidden Threads:** No `.Result`, `.Wait()`, or ad-hoc threads inside SDK services—stay purely async through the supplied HttpClient infrastructure. |
| 114 | + |
| 115 | +## 7. Critical File Locations |
| 116 | +```plaintext |
| 117 | +. |
| 118 | +├─ AGENTS.md |
| 119 | +├─ SignNow.Net.sln ← SACRED (DO NOT MODIFY) |
| 120 | +├─ Directory.Build.props ← SACRED (DO NOT MODIFY) |
| 121 | +├─ SignNow.props ← SACRED (DO NOT MODIFY) |
| 122 | +├─ netfx.props ← SACRED (DO NOT MODIFY) |
| 123 | +├─ .editorconfig ← SACRED (Coding conventions source of truth) |
| 124 | +├─ SignNow.Net/ |
| 125 | +│ ├─ SignNowContext.cs ← SACRED (Main DI entry point / Composition root) |
| 126 | +│ ├─ Interfaces/ |
| 127 | +│ ├─ Service/ |
| 128 | +│ ├─ _Internal/ |
| 129 | +│ │ ├─ Infrastructure/ |
| 130 | +│ │ └─ Model/ |
| 131 | +│ └─ Extensions/ |
| 132 | +├─ SignNow.Net.Examples/ |
| 133 | +│ ├─ ExamplesBase.cs ← SACRED (DO NOT MODIFY) |
| 134 | +│ └─ Scenario folders (customer-facing) |
| 135 | +├─ SignNow.Net.Test/ |
| 136 | +│ ├─ AcceptanceTests/ |
| 137 | +│ ├─ FeatureTests/ |
| 138 | +│ └─ UnitTests/ |
| 139 | +└─ logs/ (diagnostics only) |
| 140 | +``` |
| 141 | + |
| 142 | +--- |
| 143 | + |
| 144 | +Last Updated: 2026-02-03 |
| 145 | + |
| 146 | +Maintained by: AI Agents under human supervision |
0 commit comments