doc update - infographics and overview.md

docs/graphics/README.md

@@ -0,0 +1,13 @@
+# Usage
+
+Graphics can be imported and edited with the draw.io tool:
+https://www.draw.io/?mode=github
+
+Images can be exported from the draw.io directly to this github repo.
+All diagrams are saved to the single .xml file. To export each infographic
+select the relevant elements and then export to .png using the following settings:
+
+- Selection Only
+- Crop
+- Zoom: 200% 
+- Borderwidth: 20 

docs/graphics/infographic.xml

@@ -0,0 +1 @@
+<mxfile userAgent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36" version="6.9.6" editor="www.draw.io" type="github"><diagram name="Page-1" id="0cb6309d-e12f-bf67-55cb-3441fc3b6c51">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</diagram></mxfile>

docs/quark/README.md

@@ -45,6 +45,7 @@ into various applications.
 
 ## Further reading
 
+* [Quark overview](overview.md)
 * [Glossary of the terms](glossary.md)
 * [Standard modules](stdlib.md)
 * Guide to building a module

docs/quark/glossary.md

@@ -156,7 +156,7 @@ self-sufficient. Common elements of a module are:
 To enable a module, you must add the appropriate middleware (if any) to the
 stack in `main.go` for the client application (Quark default:
 `basecli/main.go`), as well as adding the handler (if any) to the dispatcher
-(Quark default: `app/app.go).  Once the stack is compiled into a `Handler`,
+(Quark default: `app/app.go`).  Once the stack is compiled into a `Handler`,
 then each tx is handled by the appropriate module.
 
 ## Dispatcher

docs/quark/overview.md

@@ -0,0 +1,105 @@
+# Quark Overview
+
+The quark middleware design optimizes flexibility and security. The framework
+is designed around a modular execution stack which allows applications to mix
+and match modular elements as desired. Along side, all modules are permissioned
+and sandboxed to reduce 
+
+For more explanation please see the [standard
+library](https://github.com/tendermint/basecoin/blob/infographic/docs/quark/stdlib.md)
+and
+[glossary](https://github.com/tendermint/basecoin/blob/infographic/docs/quark/glossary.md)
+documentation.
+
+For a more interconnected schematics see these
+[framework](https://github.com/tendermint/basecoin/blob/infographic/docs/graphics/overview-framework.png)
+and
+[security](https://github.com/tendermint/basecoin/blob/infographic/docs/graphics/overview-security.png)
+overviews.
+
+## Framework Overview
+
+### Transaction (tx) 
+
+Each tx passes through the middleware stack which can be defined uniquely by
+each application.  From the multiple layers of tx, each middleware may strip
+off one level, like an onion.  As so, the transaction must be constructed to
+mirror the execution stack, and each middleware should allow embedding an
+arbitrary tx for the next layer in the stack.
+
+<img src="https://github.com/tendermint/basecoin/blob/infographic/docs/graphics/tx.png" width=250>
+
+### Execution Stack
+
+Middleware components allow for code reusability and integrability. A standard
+set of middleware are provided and can be mix-and-matched with custom
+middleware. Some of the [standard
+library](https://github.com/tendermint/basecoin/blob/infographic/docs/quark/stdlib.md)
+middlewares provided in this package include:
+ - Logging
+ - Recovery
+ - Signatures
+ - Chain
+ - Nonce
+ - Fees
+ - Roles
+ - Inter-Blockchain-Communication (IBC)
+
+ As a part of stack execution the state space provided to each middleware is
+isolated (see [Data Store](overview.md#data-store)). When executing the stack,
+state-recovery points (checkpoints) can be assigned for stack execution of
+`CheckTx` or `DeliverTx`. This means, that all state changes will be reverted
+to the checkpoint state on failure when either being run as a part of `CheckTx`
+or `DeliverTx`. Example usage of the checkpoints is when we may want to deduct
+a fee even if the end business logic fails, under this situation we would add
+the DeliverTx Checkpoint to after the fee middleware but before the business
+logic. This diagram displays a typical process flow through an execution stack.
+
+<img src="https://github.com/tendermint/basecoin/blob/infographic/docs/graphics/middleware.png" width=500>
+
+### Dispatcher
+
+The dispatcher handler aims to allow for reusable business logic.  As a
+transaction is passed to the end handler, the dispatcher routes the logic to
+the correct module.  To use the dispatcher tool all transaction types must
+first be registered with the dispatcher. Once registered the middleware stack
+or any other handler can call the dispatcher to execute a transaction.
+Similarity to the execution stack, when executing a transaction the dispatcher
+isolates the state space available to the designated module (see [Data
+Store](overview.md#data-store)).
+
+<img src="https://github.com/tendermint/basecoin/blob/infographic/docs/graphics/dispatcher.png" width=600>
+
+## Security Overview
+
+### Permission
+
+Each application is run in a sandbox to isolate security risks. When
+interfacing between applications, if a one of those application is compromised
+the entire network should still be secure. This is achieved through actor
+permissioning whereby each chain, account, or application can provided a
+designated permission for the transaction context to perform a specific action.
+
+Context is passed through the middleware and dispatcher, allowing one to add
+permissions on this app-space, and check current permissions.
+
+<img src="https://github.com/tendermint/basecoin/blob/infographic/docs/graphics/permission.png" width=500>
+
+### Data Store
+
+The entire merkle tree can access all data. When we call a module (or
+middleware), we give them access to a subtree corresponding to their app. This
+is achieved through the use of unique prefix assigned to each module. From the
+module's perspective it is no different, the module need-not have regard for
+the prefix as it is assigned outside of the modules scope. For example, if a
+module named `foo` wanted to write to the store it could save records under the
+key `bar` however the dispatcher would register that record in the persistent
+state under `foo/bar`. Next time the `foo` app was called that record would be
+accessible to it under the assigned key `bar`. This effectively makes app
+prefixing invisible to each module while preventing each module from affecting
+each other module. Under this model no two registered modules are permitted to
+have the same namespace.
+
+<img src="https://github.com/tendermint/basecoin/blob/infographic/docs/graphics/datastore.png" width=500>
+
+