From f71b19de17642fe2e3d09a8a3c536f63f4a3cf2f Mon Sep 17 00:00:00 2001 From: Henry Palacios Date: Mon, 4 May 2026 14:09:09 -0300 Subject: [PATCH 1/2] docs: embed mermaid diagrams inline, drop docs/diagrams folder GitHub does not embed linked .mmd files inline in another markdown, so the previous setup forced readers to click through to see each diagram. Move each diagram to a fenced mermaid block where it is consumed: - C1 system context inline in docs/overview.md - C2 container architecture inline in the root README under Architecture - Trade execution sequence inline in docs/flows/trade-execution.md Remove docs/diagrams/ as a separate folder and drop the broken docs/packages/protocol-core.md link in docs/overview.md left over from the previous follow-up. --- README.md | 36 +++++++++++++++++++++++++++++++-- docs/diagrams/c1-context.mmd | 29 -------------------------- docs/diagrams/c2-containers.mmd | 33 ------------------------------ docs/diagrams/flow-trade.mmd | 30 --------------------------- docs/flows/chain-onboarding.md | 6 +++--- docs/flows/trade-execution.md | 31 ++++++++++++++++++++++++++-- docs/overview.md | 34 ++++++++++++++++++++++++++++--- 7 files changed, 97 insertions(+), 102 deletions(-) delete mode 100644 docs/diagrams/c1-context.mmd delete mode 100644 docs/diagrams/c2-containers.mmd delete mode 100644 docs/diagrams/flow-trade.mmd diff --git a/README.md b/README.md index e76d364..af07af7 100755 --- a/README.md +++ b/README.md @@ -7,7 +7,6 @@ Overview • Packages • Flows • - Diagrams • Glossary • ADRs

@@ -27,6 +26,40 @@ Consumers pick metadata only, or the full trading toolkit on top of it. | [`@quickswap-defi/protocol-core`](packages/protocol-core/) | Chain configs, protocol versions, fees, native + stablecoin metadata | Published | | [`@quickswap-defi/sdk`](packages/sdk/) | V2 entities (`Token`, `Pair`, `Route`, `Trade`), fetcher, router | Published | +## Architecture + +```mermaid +graph TB + subgraph EXTERNAL["External"] + CONSUMER["dApp / Consumer
Imports the SDK"] + ETHERS["ethers v5
Peer dependency"] + JSBI_LIB["JSBI
BigInt polyfill"] + CHAIN["EVM Chain RPC
On-chain reads"] + end + + subgraph SYSTEM["QuickSwap SDK monorepo"] + subgraph PACKAGES["Packages"] + CORE["@quickswap-defi/protocol-core
Chains, fees, tokens, versions"] + SDK["@quickswap-defi/sdk
V2 entities, fetcher, router"] + end + end + + CONSUMER -->|"imports"| SDK + CONSUMER -->|"imports (metadata only)"| CORE + SDK -->|"depends on"| CORE + SDK -->|"peer dep"| ETHERS + SDK -->|"depends on"| JSBI_LIB + SDK -->|"reads via provider"| CHAIN + + classDef entity fill:#4a1f6e,stroke:#9b59b6,color:#f0e6ff,font-weight:bold + classDef infra fill:#1a3a5c,stroke:#2e86c1,color:#d6eaf8 + classDef external fill:#1e3a2f,stroke:#27ae60,color:#d5f5e3 + + class CORE,SDK entity + class ETHERS,JSBI_LIB infra + class CONSUMER,CHAIN external +``` + ## How It Works 1. **Resolve chain metadata** — read chain config and addresses from `protocol-core`. @@ -62,7 +95,6 @@ Documentation follows [Diátaxis](https://diataxis.fr/) — each doc stays in it | [Overview](docs/overview.md) | Explanation | What the SDK is and why the split exists | | [Packages](#packages) | Reference | Per-package READMEs (also published to npm) | | [Flows](docs/flows/) | Explanation | Trade execution and chain onboarding | -| [Diagrams](docs/diagrams/) | Reference | C4 + sequence mermaid sources | | [Glossary](docs/glossary.md) | Reference | Domain terms | | [ADRs](docs/adr/) | Decisions | Architecture decision records | diff --git a/docs/diagrams/c1-context.mmd b/docs/diagrams/c1-context.mmd deleted file mode 100644 index 99dc1c1..0000000 --- a/docs/diagrams/c1-context.mmd +++ /dev/null @@ -1,29 +0,0 @@ -%% C4 Level 1 — System Context -%% QuickSwap SDK as a black box in its ecosystem. -%% Edit this file; GitHub renders the diagram natively in markdown previews. - -graph TB - subgraph PEOPLE["Consumers"] - ACTOR_1["dApp / Frontend
Swap UIs, aggregators"] - ACTOR_2["Backend / Indexer
Analytics, off-chain services"] - end - - SYSTEM[["QuickSwap SDK
V2 entities + multi-chain protocol metadata"]] - - subgraph EXT["External Systems"] - EXT_1["EVM Chains
Polygon, Base, zkEVM, others"] - EXT_2["ethers v5
RPC provider library"] - end - - ACTOR_1 -->|"imports entities, builds trades"| SYSTEM - ACTOR_2 -->|"imports chain registry"| SYSTEM - SYSTEM <-->|"reads pair reserves and token metadata"| EXT_1 - SYSTEM -->|"uses provider for on-chain reads"| EXT_2 - - classDef system fill:#4a1f6e,stroke:#9b59b6,color:#f0e6ff,font-weight:bold - classDef external fill:#1e3a2f,stroke:#27ae60,color:#d5f5e3 - classDef person fill:#3d2b1f,stroke:#e67e22,color:#fdebd0 - - class SYSTEM system - class EXT_1,EXT_2 external - class ACTOR_1,ACTOR_2 person diff --git a/docs/diagrams/c2-containers.mmd b/docs/diagrams/c2-containers.mmd deleted file mode 100644 index 9ece2f3..0000000 --- a/docs/diagrams/c2-containers.mmd +++ /dev/null @@ -1,33 +0,0 @@ -%% C4 Level 2 — Containers -%% Inside QuickSwap SDK: packages and how they relate to consumers and libraries. -%% Edit this file; GitHub renders the diagram natively in markdown previews. - -graph TB - subgraph EXTERNAL["External"] - CONSUMER["dApp / Consumer
Imports the SDK"] - ETHERS["ethers v5
Peer dependency"] - JSBI_LIB["JSBI
BigInt polyfill"] - CHAIN["EVM Chain RPC
On-chain reads"] - end - - subgraph SYSTEM["QuickSwap SDK monorepo"] - subgraph PACKAGES["Packages"] - CORE["@quickswap-defi/protocol-core
Chains, fees, tokens, versions"] - SDK["@quickswap-defi/sdk
V2 entities, fetcher, router"] - end - end - - CONSUMER -->|"imports"| SDK - CONSUMER -->|"imports (metadata only)"| CORE - SDK -->|"depends on"| CORE - SDK -->|"peer dep"| ETHERS - SDK -->|"depends on"| JSBI_LIB - SDK -->|"reads via provider"| CHAIN - - classDef entity fill:#4a1f6e,stroke:#9b59b6,color:#f0e6ff,font-weight:bold - classDef infra fill:#1a3a5c,stroke:#2e86c1,color:#d6eaf8 - classDef external fill:#1e3a2f,stroke:#27ae60,color:#d5f5e3 - - class CORE,SDK entity - class ETHERS,JSBI_LIB infra - class CONSUMER,CHAIN external diff --git a/docs/diagrams/flow-trade.mmd b/docs/diagrams/flow-trade.mmd deleted file mode 100644 index 23a9c76..0000000 --- a/docs/diagrams/flow-trade.mmd +++ /dev/null @@ -1,30 +0,0 @@ -%% Sequence — Trade execution -%% From input amounts to a Trade ready to send on-chain. -%% Edit this file; GitHub renders the diagram natively in markdown previews. - -sequenceDiagram - autonumber - actor C as Consumer - participant F as Pair Fetcher - participant R as Route - participant T as Trade - - C->>C: build Token instances (in, out) - C->>F: fetchPairData(tokenA, tokenB, provider) - F->>F: derive pair address (factory + init code hash) - F-->>C: Pair (with reserves) - - C->>R: new Route([pair, ...], input, output) - R-->>C: Route - - alt EXACT_INPUT - C->>T: Trade.exactIn(route, inputAmount) - else EXACT_OUTPUT - C->>T: Trade.exactOut(route, outputAmount) - end - T-->>C: Trade (inputAmount, outputAmount, priceImpact) - - C->>T: minimumAmountOut(slippage) / maximumAmountIn(slippage) - T-->>C: bound CurrencyAmount - - Note over C: Format router calldata, sign, and submit diff --git a/docs/flows/chain-onboarding.md b/docs/flows/chain-onboarding.md index 294c310..ec4ea51 100644 --- a/docs/flows/chain-onboarding.md +++ b/docs/flows/chain-onboarding.md @@ -2,10 +2,10 @@ How to add a new EVM chain to the SDK so consumers can use it. -## Diagram +## Where artifacts live -No dedicated sequence diagram. The container view in -[../diagrams/c2-containers.mmd](../diagrams/c2-containers.mmd) shows where each artifact lives. +No dedicated sequence diagram for this flow. The architecture diagram in the root +[README](../../README.md#architecture) shows the container layout. ## Steps diff --git a/docs/flows/trade-execution.md b/docs/flows/trade-execution.md index 556a7fd..a8e802c 100644 --- a/docs/flows/trade-execution.md +++ b/docs/flows/trade-execution.md @@ -2,9 +2,36 @@ How a consumer turns input amounts into a `Trade` with the params needed to execute on-chain. -## Diagram +## Sequence -See [../diagrams/flow-trade.mmd](../diagrams/flow-trade.mmd). +```mermaid +sequenceDiagram + autonumber + actor C as Consumer + participant F as Pair Fetcher + participant R as Route + participant T as Trade + + C->>C: build Token instances (in, out) + C->>F: fetchPairData(tokenA, tokenB, provider) + F->>F: derive pair address (factory + init code hash) + F-->>C: Pair (with reserves) + + C->>R: new Route([pair, ...], input, output) + R-->>C: Route + + alt EXACT_INPUT + C->>T: Trade.exactIn(route, inputAmount) + else EXACT_OUTPUT + C->>T: Trade.exactOut(route, outputAmount) + end + T-->>C: Trade (inputAmount, outputAmount, priceImpact) + + C->>T: minimumAmountOut(slippage) / maximumAmountIn(slippage) + T-->>C: bound CurrencyAmount + + Note over C: Format router calldata, sign, and submit +``` ## Steps diff --git a/docs/overview.md b/docs/overview.md index 2a9c9cd..a45aede 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -7,6 +7,34 @@ QuickSwap's V2 (Uniswap V2-fork) deployments across multiple EVM chains. `protoc chain configuration, protocol versions, fees, and token primitives. `sdk` builds on top of it with the trading entities, fetcher, and router. +```mermaid +graph TB + subgraph PEOPLE["Consumers"] + ACTOR_1["dApp / Frontend
Swap UIs, aggregators"] + ACTOR_2["Backend / Indexer
Analytics, off-chain services"] + end + + SYSTEM[["QuickSwap SDK
V2 entities + multi-chain protocol metadata"]] + + subgraph EXT["External Systems"] + EXT_1["EVM Chains
Polygon, Base, zkEVM, others"] + EXT_2["ethers v5
RPC provider library"] + end + + ACTOR_1 -->|"imports entities, builds trades"| SYSTEM + ACTOR_2 -->|"imports chain registry"| SYSTEM + SYSTEM <-->|"reads pair reserves and token metadata"| EXT_1 + SYSTEM -->|"uses provider for on-chain reads"| EXT_2 + + classDef system fill:#4a1f6e,stroke:#9b59b6,color:#f0e6ff,font-weight:bold + classDef external fill:#1e3a2f,stroke:#27ae60,color:#d5f5e3 + classDef person fill:#3d2b1f,stroke:#e67e22,color:#fdebd0 + + class SYSTEM system + class EXT_1,EXT_2 external + class ACTOR_1,ACTOR_2 person +``` + ## Why Consumers have very different needs. A frontend that only renders chain names and stablecoin @@ -33,12 +61,12 @@ other way around. 1. **Look up the chain** — pick a chain from the registry, read its protocol versions and tokens. 2. **Build the trade** — use the SDK's `Token`, `Pair`, `Route`, and `Trade` to compute outputs. -Full sequence in [flows/trade-execution.md](./flows/trade-execution.md). Visual in -[diagrams/c2-containers.mmd](./diagrams/c2-containers.mmd). +Full sequence in [flows/trade-execution.md](./flows/trade-execution.md). Container view in the +root [README](../README.md#architecture). ## Multi-chain support The chain registry is the single source of truth for which networks the SDK supports and what -their on-chain configuration looks like. See [packages/protocol-core.md](./packages/protocol-core.md) +their on-chain configuration looks like. See [`packages/protocol-core/`](../packages/protocol-core/) for the export surface and [glossary.md](./glossary.md) for the underlying concepts (`ChainId`, `Factory`, `Init Code Hash`). From 31ff813aa17bc75fcd33035b10e92449647e528f Mon Sep 17 00:00:00 2001 From: Henry Palacios Date: Mon, 4 May 2026 15:00:05 -0300 Subject: [PATCH 2/2] docs: add a11y directives to inline mermaid and ADR 003 Add accTitle and accDescr directives to every inline mermaid block so screen readers announce a meaningful diagram title and description instead of the raw graph IDs. Add ADR 003 capturing the decision to use inline mermaid blocks over .mmd source plus CI-rendered SVG, including the wins, costs, and revisit triggers. --- README.md | 2 ++ docs/adr/003-inline-mermaid.md | 44 ++++++++++++++++++++++++++++++++++ docs/flows/trade-execution.md | 2 ++ docs/overview.md | 2 ++ 4 files changed, 50 insertions(+) create mode 100644 docs/adr/003-inline-mermaid.md diff --git a/README.md b/README.md index af07af7..293706b 100755 --- a/README.md +++ b/README.md @@ -30,6 +30,8 @@ Consumers pick metadata only, or the full trading toolkit on top of it. ```mermaid graph TB + accTitle: QuickSwap SDK container architecture + accDescr { Two packages — protocol-core (chain registry, fees, tokens) and sdk (V2 entities, fetcher, router) — sit inside the QuickSwap SDK monorepo. Consumers import sdk, sdk depends on protocol-core, ethers v5 is a peer dependency, JSBI provides BigInt math, and sdk reads pair reserves from EVM chains. } subgraph EXTERNAL["External"] CONSUMER["dApp / Consumer
Imports the SDK"] ETHERS["ethers v5
Peer dependency"] diff --git a/docs/adr/003-inline-mermaid.md b/docs/adr/003-inline-mermaid.md new file mode 100644 index 0000000..2dd9c5a --- /dev/null +++ b/docs/adr/003-inline-mermaid.md @@ -0,0 +1,44 @@ +# ADR 003 — Inline mermaid blocks over .mmd source files + +- **Status:** Accepted +- **Date:** 2026-05-04 + +## Context + +GitHub renders fenced ` ```mermaid ` blocks inline in markdown but does NOT +embed linked `.mmd` files — a `![](diagram.mmd)` reference shows up as a broken +image. Two real options for this repo's architecture diagrams: + +- **(A)** Inline mermaid in the markdown file where the diagram is consumed. +- **(B)** Keep `.mmd` source files and add CI that renders them to SVG, commit + the SVGs alongside, and embed via `![](path.svg)`. + +## Decision + +Choose **(A)**: inline mermaid blocks in the markdown that consumes them. + +## Consequences + +Wins: + +- Line-by-line reviewable diffs in PRs — diagram changes show up as text diffs. +- Single artifact per diagram — no source/render pair that can drift. +- Zero new CI infrastructure to maintain. +- Zero supply-chain footprint — avoids pulling in `mermaid-cli` and a headless + Chromium just to render a few boxes. + +Costs: + +- GitHub-only render surface — does not render on npm package READMEs, on + archive.org snapshots, on plain Docusaurus / MkDocs without a plugin, or in + basic VS Code without a mermaid extension. +- Accessibility burden falls on the `accTitle` / `accDescr` directives or on a + prose summary alongside each diagram. +- Mermaid version is whatever GitHub ships — out of repo control. +- Diagrams are not directly reusable as binary assets for slides or PDFs. + +## Revisit trigger + +Reconsider option (B) if QuickSwap adds a doc site, npmjs starts syndicating +the architecture page, or contributors report unrendered mermaid in their +tooling. diff --git a/docs/flows/trade-execution.md b/docs/flows/trade-execution.md index a8e802c..a5f763e 100644 --- a/docs/flows/trade-execution.md +++ b/docs/flows/trade-execution.md @@ -6,6 +6,8 @@ How a consumer turns input amounts into a `Trade` with the params needed to exec ```mermaid sequenceDiagram + accTitle: Trade execution sequence + accDescr { Consumer builds Token instances, fetches the Pair via the Pair Fetcher, constructs a Route, instantiates a Trade (exactIn or exactOut), reads slippage bounds, and submits router calldata. } autonumber actor C as Consumer participant F as Pair Fetcher diff --git a/docs/overview.md b/docs/overview.md index a45aede..faed300 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -9,6 +9,8 @@ with the trading entities, fetcher, and router. ```mermaid graph TB + accTitle: QuickSwap SDK system context + accDescr { The SDK is consumed by dApp frontends and backend indexers. It reads pair reserves and token metadata from EVM chains via ethers v5. } subgraph PEOPLE["Consumers"] ACTOR_1["dApp / Frontend
Swap UIs, aggregators"] ACTOR_2["Backend / Indexer
Analytics, off-chain services"]