QuickSwap · henrypalacios · May 4, 2026 · May 4, 2026 · May 4, 2026
diff --git a/README.md b/README.md
@@ -7,7 +7,6 @@
   <a href="docs/overview.md">Overview</a> &bull;
   <a href="#packages">Packages</a> &bull;
   <a href="docs/flows/">Flows</a> &bull;
-  <a href="docs/diagrams/">Diagrams</a> &bull;
   <a href="docs/glossary.md">Glossary</a> &bull;
   <a href="docs/adr/">ADRs</a>
 </p>
@@ -27,6 +26,42 @@ 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
+    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<br/><i>Imports the SDK</i>"]
+        ETHERS["ethers v5<br/><i>Peer dependency</i>"]
+        JSBI_LIB["JSBI<br/><i>BigInt polyfill</i>"]
+        CHAIN["EVM Chain RPC<br/><i>On-chain reads</i>"]
+    end
+
+    subgraph SYSTEM["QuickSwap SDK monorepo"]
+        subgraph PACKAGES["Packages"]
+            CORE["@quickswap-defi/protocol-core<br/><i>Chains, fees, tokens, versions</i>"]
+            SDK["@quickswap-defi/sdk<br/><i>V2 entities, fetcher, router</i>"]
+        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 +97,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/adr/003-inline-mermaid.md 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/diagrams/c1-context.mmd b/docs/diagrams/c1-context.mmd
diff --git a/docs/diagrams/c2-containers.mmd b/docs/diagrams/c2-containers.mmd
diff --git a/docs/diagrams/flow-trade.mmd b/docs/diagrams/flow-trade.mmd
diff --git 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
@@ -2,9 +2,38 @@
 
 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
+    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
+    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
@@ -7,6 +7,36 @@ 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
+    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<br/><i>Swap UIs, aggregators</i>"]
+        ACTOR_2["Backend / Indexer<br/><i>Analytics, off-chain services</i>"]
+    end
+
+    SYSTEM[["QuickSwap SDK<br/><b>V2 entities + multi-chain protocol metadata</b>"]]
+
+    subgraph EXT["External Systems"]
+        EXT_1["EVM Chains<br/><i>Polygon, Base, zkEVM, others</i>"]
+        EXT_2["ethers v5<br/><i>RPC provider library</i>"]
+    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 +63,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`).