Strawman docs/architecture dir

docs/architecture/ABCI.md

@@ -0,0 +1,16 @@
+# ABCI
+
+ABCI is an interface between the consensus/blockchain engine known as tendermint, and the application-specific business logic, known as an ABCi app.
+
+The tendermint core should run unchanged for all apps.  Each app can customize it, the supported transactions, queries, even the validator sets and hwo to handle staking / slashing stake. This customization is achieved by implementing the ABCi app to send the proper information to the tendermint engine to perform as directed.
+
+To understand this decision better, think of the design of the tendermint engine.
+
+* A blockchain is simply consensus on a unique global ordering of events.
+* This consensus can efficiently be implemented using BFT and PoS
+* This code can be generalized to easily support a large number of blockchains
+* The block-chain specific code, the interpretation of the individual events, can be implemented by a 3rd party app without touching the consensus engine core
+* Use an efficient, language-agnostic layer to implement this (ABCi)
+
+
+Bucky, please make this doc real.

docs/architecture/README.md

@@ -0,0 +1,15 @@
+# Architecture Decision Records
+
+This is a location to record all high-level architecture decisions in the tendermin project.  Not the implementation details, but the reasoning that happened.  This should be refered to for guidance of the "right way" to extend the application.  And if we notice that the original decisions were lacking, we should have another open discussion, record the new decisions here, and then modify the code to match.
+
+This is like our guide and mentor when Jae and Bucky are offline.... The concept comes from a [blog post](https://product.reverb.com/documenting-architecture-decisions-the-reverb-way-a3563bb24bd0#.78xhdix6t) that resonated among the team when Anton shared it.
+
+Each section of the code can have it's own markdown file in this directory, and please add a link to the readme.
+
+## Sections
+
+* [ABCI](./ABCI.md)
+* [go-merkle / merkleeyes](./merkle.md)
+* basecoin
+* tendermint core (multiple sections)
+* ???

docs/architecture/merkle.md

@@ -0,0 +1,17 @@
+# Merkle data stores
+
+To allow the efficient creation of an ABCi app, tendermint wishes to provide a reference implemention of a key-value store that provides merkle proofs of the data.  These proofs then quickly allow the ABCi app to provide an apphash to the consensus engine, as well as a full proof to any client.
+
+This engine is currently implemented in `go-merkle` with `merkleeyes` providing a language-agnostic binding via ABCi.  It uses `go-db` bindings internally to persist data to leveldb.
+
+What are some of the requirements of this store:
+
+* It must support efficient key-value operations (get/set/delete)
+* It must support persistance.
+* We must only persist complete blocks, so when we come up after a crash we are at the state of block N or N+1, but not in-between these two states.
+* It must allow us to read/write from one uncommited state (working state), while serving other queries from the last commited state. And a way to determine which one to serve for each client.
+* It must allow us to hold references to old state, to allow providing proofs from 20 blocks ago.  We can define some limits as to the maximum time to hold this data.
+* We provide in process binding in the go-lanaguage
+* We provide language-agnostic bindings when running the data store as it's own process.
+
+