docs: apply review to arch diagram

Author: daviddias

README.md

@@ -991,26 +991,28 @@ the metrics (in prometheus format) by making a GET request to the following endp
 http://localhost:5002/debug/metrics/prometheus
 ```
 
-### IPFS Core Architecture
+### IPFS Architecture
 
-![](/img/core.png)
+![](/img/architecture.png)
+
+[Annotated version](https://user-images.githubusercontent.com/1211152/47606420-b6265780-da13-11e8-923b-b365a8534e0e.png)j
 
 What does this image explain?
 
 - IPFS uses `ipfs-repo` which picks `fs` or `indexeddb` as its storage drivers, depending if it is running in Node.js or in the Browser.
 - The exchange protocol, `bitswap`, uses the Block Service which in turn uses the Repo, offering a get and put of blocks to the IPFS implementation.
 - The DAG API (previously Object) comes from the IPLD Resolver, it can support several IPLD Formats (i.e: dag-pb, dag-cbor, etc).
 - The Files API uses `ipfs-unixfs-engine` to import and export files to and from IPFS.
-- Swarm, the component that offers a network API, uses libp2p to dial and listen for connections, to use the DHT, for discovery mechanisms, and more. libp2p-ipfs-nodejs is used when running in Node.js and libp2p-ipfs-browser is used when running in the browser.
+- libp2p, the network stack of IPFS, uses libp2p to dial and listen for connections, to use the DHT, for discovery mechanisms, and more.
 
 ## Contribute
 
 IPFS implementation in JavaScript is a work in progress. As such, there's a few things you can do right now to help out:
 
-  * Go through the modules below and **check out existing issues**. This would be especially useful for modules in active development. Some knowledge of IPFS may be required, as well as the infrastructure behind it - for instance, you may need to read up on p2p and more complex operations like muxing to be able to help technically.
-  * **Perform code reviews**. More eyes will help (a) speed the project along, (b) ensure quality, and (c) reduce possible future bugs.
-  * Take a look at go-ipfs and some of the planning repositories or issues: for instance, the [libp2p spec](https://github.com/ipfs/specs/pull/19). Contributions here that would be most helpful are **top-level comments** about how it should look based on our understanding. Again, the more eyes the better.
-  * **Add tests**. There can never be enough tests.
+- Go through the modules below and **check out existing issues**. This would be especially useful for modules in active development. Some knowledge of IPFS may be required, as well as the infrastructure behind it - for instance, you may need to read up on p2p and more complex operations like muxing to be able to help technically.
+- **Perform code reviews**. More eyes will help (a) speed the project along, (b) ensure quality, and (c) reduce possible future bugs.
+- Take a look at go-ipfs and some of the planning repositories or issues: for instance, the [libp2p spec](https://github.com/ipfs/specs/pull/19). Contributions here that would be most helpful are **top-level comments** about how it should look based on our understanding. Again, the more eyes the better.
+- **Add tests**. There can never be enough tests.
 
 ### Want to hack on IPFS?
 

examples/README.md

@@ -31,7 +31,9 @@ Let us know if you find any issue or if you want to contribute and add a new tut
 
 In this section, you will find explanations to different pieces of IPFS Architecture and how `js-ipfs` implements them.
 
-![](../img/core.png)
+![](../img/architecture.png)
+
+[Annotated version](https://user-images.githubusercontent.com/1211152/47606420-b6265780-da13-11e8-923b-b365a8534e0e.png)
 
 > These explanations are still a work in progress
 

img/architecture.monopic

@@ -13,22 +13,22 @@
                 │    │ │ └──────┴──────┴──────┴──────┴──────┘       └───────┘
                 │    │ │     │      │      │      │      │              │     ┃
                 │    │ │     │      │ ┌────┘      │ ┌────┘         ┌────┘      ┃
-               ┃└────┘ │  ┌──┘      │ │    ┌──────┘ │              │          ┃┃
-               ┃       │  │┌────────┘ │    ▼        ▼              ▼
-                ┌────┐ │  ││          │┌───────┐┌──────┐┌────────────────────┐┃
-                │    │ │  ││          ││Pinning││Unixfs││ libp2p             │
-                │    │ │  ││          ││Service││Engine││┌──────────────────┐│┃┃
-               ┃│    │ │  ││          │└───────┘└──────┘││Connection Manager││ ┃
-               ┃│HTTP│ │  ││          │    │        │   │└──────────────────┘│┃
-                │RPC │ │  ││          ├────┴────────┘   │┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ │
-┌───┐┌────────┐ │API │◀┘  ││          │                 │  Peer Reputation  ││┃
-│CLI││ipfs-api│ │    │ ┃  ││          │                 │└ ─ ─ ─ ─ ─ ─ ─ ─ ─ │ ┃
-└───┘└────────┘┃│    │    ││          │                 └────────────────────┘┃┃
-               ┃│    │ ┃  ││       ┌──┘┌ ─ ─ ─ ─ ┐┌ ─ ─ ─ ─ ─
-                │    │    ││       │    Providers      GC    │                ┃
-                └────┘ ┃  ││       │   │ Service ││
-                          ││       ▼    ─ ─ ─ ─ ─  ─ ─ ─ ─ ─ ┘                ┃┃
-               ┃       ┃  ││┌─────────────┐                                    ┃
+               ┃└────┘ │  ┌──┘      │ │    ┌──────┘ │              ▼          ┃┃
+               ┃       │  │┌────────┘ │    ▼        ▼   ┌────────────────────┐
+                ┌────┐ │  ││          │┌───────┐┌──────┐│ libp2p             │┃
+                │    │ │  ││          ││Pinning││Unixfs││ (Network, PubSub,  │
+                │    │ │  ││          ││Service││Engine││ Swarm, Crypto)     │┃┃
+               ┃│    │ │  ││          │└───────┘└──────┘│┌──────────────────┐│ ┃
+               ┃│HTTP│ │  ││          │    │        │   ││Connection Manager││┃
+                │RPC │ │  ││          ├────┴────────┘   │└──────────────────┘│
+┌───┐┌────────┐ │API │◀┘  ││          │                 │┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ │┃
+│CLI││ipfs-api│ │    │ ┃  ││          │                 │  Peer Reputation  ││ ┃
+└───┘└────────┘┃│    │    ││          │                 │└ ─ ─ ─ ─ ─ ─ ─ ─ ─ │┃┃
+               ┃│    │ ┃  ││       ┌──┘                 └────────────────────┘
+                │    │    ││       │                   ┌ ─ ─ ─ ─ ┐┌ ─ ─ ─ ─ ─ ┃
+                └────┘ ┃  ││       │                    Providers      GC    │
+                          ││       ▼                   │ Service ││           ┃┃
+               ┃       ┃  ││┌─────────────┐             ─ ─ ─ ─ ─  ─ ─ ─ ─ ─ ┘ ┃
                ┃          │││Graph Service│─────┬───────────┬───────────┐     ┃
                        ┃  ││└─────────────┘     ▼           ▼           ▼
                           ││       │      ┌ ─ ─ ─ ─ ─ ┌ ─ ─ ─ ─ ─ ┌ ─ ─ ─ ─ ─ ┃
@@ -51,4 +51,14 @@
                ┃       ┃   └────┘└──────────┘└────────┘└────┘                  ┃
                ┃                                                              ┃
                        ┗ ━ ━ ━ ━ ━ ━ ━ ━ ━ ━ ━ ━ ━ ━ ━ ━ ━ ━ ━ ━ ━ ━ ━ ━ ━ ━ ━
-                 ━━   ━━   ━━   ━━   ━━   ━━   ━━   ━━   ━━   ━━   ━━   ━━   ━━
+                 ━━   ━━   ━━   ━━   ━━   ━━   ━━   ━━   ━━   ━━   ━━   ━━   ━━
+
+   ┌───────────────────────────────────────────────────────────────────────────┐
+   │ Legend                                                                    │
+   │ ┌ ─ ─ ┐                                                                   │
+   │         Planned, not yet implemented                                      │
+   │ └ ─ ─ ┘                                                                   │
+   │ ┌─────┐                                                                   │
+   │ │     │ Exist and shipped with IPFS                                       │
+   │ └─────┘                                                                   │
+   └───────────────────────────────────────────────────────────────────────────┘