ADR-0008: Hand-Written SDK + Template-Generated Docs

Status: ACCEPTED Date: 2026-03-27 Scope: workspace Supersedes: N/A Superseded by: N/A

Context

SDK generation tools (OpenAPI Generator, Swagger Codegen) can produce client libraries automatically from OpenAPI specs. However, generated code tends to be non-idiomatic, hard to customize, and produces a maintenance burden when the generator's output does not match the target language's conventions. The platform's SDKs also include non-trivial logic (HMAC-SHA256 signing, RSA+AES-GCM encryption) that cannot be reliably generated.

Source: DevPortal design spec (2026-03-27-devportal-design.md, AD-3)

Decision

SDK source code (core logic + request/response models) is hand-written by developers to ensure idiomatic quality in each target language. Templates (FreeMarker) generate only documentation pages (SDK reference docs, getting-started guides) from the OpenAPI spec and shared protocol definitions. CI lint detects spec-model divergence to keep hand-written models in sync with the backend API contract.

Consequences

• Idiomatic SDKs: each language follows its own naming conventions, error handling patterns, and packaging standards.
• Cryptographic implementations (signing, encryption) are hand-written with explicit test coverage against shared test vectors.
• Higher initial development cost compared to code generation, but lower long-term maintenance burden.
• Documentation stays automatically consistent with the API spec via template regeneration on every backend push.
• CI divergence detection catches when a backend API change requires SDK model updates.

Alternatives Considered

• Fully generated SDKs (OpenAPI Generator): Rejected because generated code for signing/encryption logic is unreliable, and generated models lack language-idiomatic patterns.
• Generated code with manual patches: Rejected because re-generation overwrites patches, creating a fragile workflow.
• Hand-written everything including docs: Rejected because documentation can be reliably templated from structured data (OpenAPI JSON), saving significant manual effort.