docs: bilingual architecture doc (EN + RU)

[BarisSozen]

What

Adds a deep, bilingual architecture reference for @hashlock-tech/sdk, mirroring the hashlock-markets master-doc template and cross-linking back to it.

• docs/architecture/ARCHITECTURE.md (English)
• docs/architecture/ARCHITECTURE.ru.md (Russian parity)
• README now links to the doc (EN + RU)

This is Phase 2 of the architecture-docs effort — per-repo docs inside each core product sibling repo (Phase 1 = the merged master doc).

Shape (matches the template)

• Language-switcher links at the top of each file
• Mermaid diagrams (system-at-a-glance + RFQ/HTLC sequence diagrams; English labels)
• Every non-obvious claim carries a path:line
• Mandatory "how this repo connects to hashlock-markets" section (§8)

Depth

Architecture & flow comprehension — points into code, doesn't duplicate it:

• The facade → transport → types/errors layering (HashLock over a private GraphQLClient)
• RFQ → quote → trade and the "SDK records, chain-watcher decides" HTLC boundary
• The experimental agent/attestation layer (documented honestly as a type-surface no-op not yet wired to the backend)
• Retry/error semantics, build/test/CI

Honest flags (not fixed here — out of scope for a docs PR)

The doc surfaces, rather than silently corrects, real doc-drift in the repo: README prose examples + .env.example still cite the superseded/compromised 142.93.106.129 IP while the code's canonical MAINNET_ENDPOINT is https://hashlock.markets/graphql; package is @hashlock-tech/sdk though some snippets import @hashlock/sdk; CHANGELOG.md lags package.json (0.1.4 vs 0.2.0).

Verification

• Mermaid fences balanced (3 per file, even total); mutual EN↔RU links resolve; every cited repo path exists
• Docs-only change — no source touched

🤖 Generated with Claude Code

Summary by CodeRabbit

Documentation

• Added comprehensive architecture documentation describing the SDK's structure, design patterns, and core operational flows (RFQ, quote, trade, settlement)
• Covers authentication mechanisms, HTLC settlement for EVM and Bitcoin networks, and cross-chain behavior
• Documentation available in English and Russian

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: dbf01c53-5993-4ee9-b6f6-21c3ed67ff2e

📥 Commits

Reviewing files that changed from the base of the PR and between bb2771f and 19c7cb1.

📒 Files selected for processing (3)

• README.md
• docs/architecture/ARCHITECTURE.md
• docs/architecture/ARCHITECTURE.ru.md

---

📝 Walkthrough

Walkthrough

This PR adds comprehensive architecture documentation for the hashlock-sdk TypeScript client. It introduces an English reference guide describing the SDK's layered design, GraphQL transport semantics, end-to-end trading flows, and integration with Hashlock Markets, plus a parallel Russian translation. The README is updated to link to both documents.

Changes

Architecture Documentation

Layer / File(s)	Summary
README architecture callout README.md	README adds an Architecture section with links to English and Russian architecture documents.
English architecture reference docs/architecture/ARCHITECTURE.md	Authoritative guide covering the HashLock facade, transport layer (HTTP POST, Bearer JWT, timeout, retry, error mapping), layered architecture (facade → transport → types/errors), end-to-end RFQ/quote/trade and HTLC settlement flows, Bitcoin PSBT construction, experimental agent/attestation typing with warning behavior, build/test/CI targets, and connections to hashlock-markets infrastructure. Includes explicit "known doc drift" callouts and a glossary.
Russian architecture translation docs/architecture/ARCHITECTURE.ru.md	Russian-language equivalent of the English architecture document, covering the same design principles, operational flows, authentication model, experimental features, tooling, and integration points, with cross-language navigation and documentation drift acknowledgment.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 Hops through docs with care,
English and Russian pair,
Layered facades gleam,
GraphQL flows like a dream,
Architecture sketched fair! 📚✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: bilingual architecture doc (EN + RU)' clearly and concisely describes the main change: addition of bilingual (English and Russian) architecture documentation files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/architecture-doc

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}