docs: update readme, add examples, pointers to API docs and more

ipfs · Nov 1, 2016 · 6f6b1e7 · 6f6b1e7
1 parent 1b0b22d
commit 6f6b1e7
Show file tree

Hide file tree

Showing 4 changed files with 267 additions and 153 deletions.
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
@@ -0,0 +1,96 @@
+# Architecture
+
+```
+┌───┐    ┌───────────────┐    ┌──────────────┐
+│CLI│───▶│   HTTP API    ├───▶│IPFS Core Impl│
+└───┘    └───────────────┘    └──────────────┘
+  △              △                    △
+  └──────────────└──────────┬─────────┘
+                            │
+                         ┌─────┐
+                         │Tests│
+                         └─────┘
+```
+
+## IPFS Core implementation architecture
+
+IPFS Core is divided into separate subsystems, each of them exist in their own repo/module. The dependencies between each subsystem is assured by injection at the IPFS Core level. IPFS Core exposes an API, defined by the IPFS API spec. libp2p is the networking layer used by IPFS, but out of scope in IPFS core, follow that project [here](https://github.com/diasdavid/js-libp2p)
+
+
+```
+             ▶  ┌───────────────────────────────────────────────────────────────────────────────┐
+                │                                   IPFS Core                                   │
+             │  └───────────────────────────────────────────────────────────────────────────────┘
+                                                        │
+             │                                          │
+                                                        │
+             │            ┌──────────────┬──────────────┼────────────┬─────────────────┐
+                          │              │              │            │                 │
+             │            │              │              │            │                 │
+                          ▼              │              ▼            │                 ▼
+             │  ┌──────────────────┐     │    ┌──────────────────┐   │       ┌──────────────────┐
+                │                  │     │    │                  │   │       │                  │
+             │  │  Block Service   │     │    │   DAG Service    │   │       │    IPFS Repo     │
+                │                  │     │    │                  │   │       │                  │
+             │  └──────────────────┘     │    └──────────────────┘   │       └──────────────────┘
+                          │              │              │            │
+  IPFS Core  │            ▼              │         ┌────┴────┐       │
+                     ┌────────┐          │         ▼         ▼       │
+             │       │ Block  │          │    ┌────────┐┌────────┐   │
+                     └────────┘          │    │DAG Node││DAG Link│   │
+             │                           │    └────────┘└────────┘   │
+                ┌──────────────────┐     │                           │       ┌──────────────────┐
+             │  │                  │     │                           │       │                  │
+                │    Bitswap       │◀────┤                           ├──────▶│    Importer      │
+             │  │                  │     │                           │       │                  │
+                └──────────────────┘     │                           │       └──────────────────┘
+             │                           │                           │                 │
+                                         │                           │            ┌────┴────┐
+             │                           │                           │            ▼         ▼
+                                         │                           │       ┌────────┐┌────────┐
+             │  ┌──────────────────┐     │                           │       │ layout ││chunker │
+                │                  │     │              ┌────────────┘       └────────┘└────────┘
+             │  │    Files         │◀────┘              │
+                │                  │                    │
+             │  └──────────────────┘                    │
+             ▶                                          │
+                                                        ▼
+                ┌───────────────────────────────────────────────────────────────────────────────┐
+                │                                                                               │
+                │                                                                               │
+                │                                                                               │
+                │                                 libp2p                                        │
+                │                                                                               │
+                │                                                                               │
+                └───────────────────────────────────────────────────────────────────────────────┘
+```
+
+#### IPFS Core
+
+IPFS Core is the entry point module for IPFS. It exposes an interface defined on [IPFS Specs.](https://github.com/ipfs/specs/blob/ipfs/api/api/core/README.md)
+
+#### Block Service
+
+Block Service uses IPFS Repo (local storage) and Bitswap (network storage) to store and fetch blocks. A block is a serialized MerkleDAG node.
+
+#### DAG Service
+
+DAG Service offers some graph language semantics on top of the MerkleDAG, composed by DAG Nodes (which can have DAG Links). It uses the Block Service as its storage and discovery service.
+
+#### IPFS Repo
+
+IPFS Repo is storage driver of IPFS, follows the [IPFS Repo Spec](https://github.com/ipfs/specs/tree/master/repo) and supports the storage of different types of files.
+
+#### Bitswap
+
+Bitswap is the exchange protocol used by IPFS to 'trade' blocks with other IPFS nodes.
+
+#### Files
+
+Files is the API that lets us work with IPFS objects (DAG Nodes) as if they were Unix Files.
+
+#### Importer
+
+Importer are a set of layouts (e.g. UnixFS) and chunkers (e.g: fixed-size, rabin, etc) that convert data to a MerkleDAG representation inside IPFS.
+
+