Rewrite the Architecture section of the Overview page [skip ci]

Author: elenadimitrova

docs/_Docs_Overview.md

@@ -10,80 +10,103 @@ The Colony Network is a large set of contracts that together define how all colo
 
 Colony is designed to be modular, upgradable, and eternally backwards-compatible. This is achieved through a sophisticated contract architecture that requires a bit of exposition. It is recommended that any developer seeking to understand the Colony Network solidity implementation first read the [Colony White Paper](https://colony.io/whitepaper.pdf), or at the very least, the [White Paper TL;DR](/colonynetwork/whitepaper-tldr-colony/).
 
-## Overview of Contracts
-Broadly speaking, the Colony Network contracts can be divided into a few categories:
-
-* Core contracts that facilitate upgrades, versioning, and emergency functions
-  * `EtherRouter.sol`
-  * `Resolver.sol`
-  * `ContractRecovery.sol`
-  * `CommonStorage.sol`
-
-* Interface contracts that collate and register public functions on the network. These provide the integration points for interacting with the Colony Network. See [API documentation](/colonynetwork/interface-ietherrouter). 
-   * `IColony.sol`
-   * `IMetaColony.sol`
-   * `IColonyNetwork.sol`
-   * `IReputationMiningCycle.sol`
-   * `ITokenLocking.sol`
-   * `IRecovery.sol`
-   * `IEtherRouter.sol`
-
-* Authority contracts that define who can call which registered functions.
-   * `CommonAuthority.sol`
-   * `ColonyAuthority.sol`
-   * `ColonyNetworkAuthority.sol`
-   * `DomainRoles.sol`
-
-* Colony contracts that define the state of an individual colony, such as funding pots, tasks, domains, and skills.
-   * `Colony.sol`
-   * `ColonyFunding.sol`
-   * `ColonyPayment.sol`
-   * `ColonyTask.sol`
-
-   * `ColonyStorage.sol`
-   * `ColonyDataTypes.sol`
-
-* Network contracts that define a global state shared by all colonies, such as reputation, token auctions and ENS.
-    * `ColonyNetwork.sol`
-    * `ColonyNetworkAuction.sol`
-    * `ColonyNetworkENS.sol`
-    * `ColonyNetworkMining.sol`
-
-    * `ColonyNetworkStorage.sol`
-    * `ColonyNetworkDataTypes.sol`
-
-* Reputation Mining contracts that define a consensus protocol for validators of the global reputation state.
-    * `ReputationMiningCycle.sol`
-    * `ReputationMiningCycleRespond.sol`
-
-    * `ReputationMiningCycleStorage.sol`
-    * `ReputationMiningCycleDataTypes.sol`
-
-* Token locking contracts allowing witholding access to depostied tokens from all colonies in the network.
-    * `TokenLocking.sol`
-
-    * `TokenLockingStorage.sol`
-    * `TokenLockingDataTypes.sol`
-
-* Extension contracts that allow for custom, legacy, or modified extention contracts to be added to a colony
-    * `ExtensionFactory.sol`
-    * `OldRoles.sol`
-    * `OldRolesFactory.sol`
-    * `OneTxPayment.sol`
-    * `OneTxPaymentFactory.sol`
-
-* ENS contracts that define a custom ENS registry for use with colonies and the Colony Network
-    * `ENS.sol`
-    * `ENSRegistry.sol`
-
-## Inheritance Architecture
-The Colony Network contracts are separated out into functional layers, and named according to their context.
-
-![Interface, Logic, Data](img/colonyNetwork_diagram_r11.png)
-Starting from the lowest level, all data types are declared in a DataTypes contract.
-
-All storage variables are declared and stored in a storage contract, which inherits a DataTypes contract.
-
-The actual logic of functions is implemented in separate contracts, which inherit a storage contract. All functions which are implemented in this layer must only modify storage varibles declared in the appropriate storage contract.
-
-Finally, all public functions are composed from all logic contracts into a single interface contract, which is used to register functions with EtherRouter (see the next section).
+## Smart Contracts Architecture
+The Colony Network contracts are separated out into four functional layers, and four logical entities outined below. This design is to an extent mandated by the [contract upgrade mechanism](/colonynetwork/docs-the-delegate-proxy-pattern/) we use.
+
+![Interface, Logic, Data](img/colonyNetwork_diagram_r12.png)
+Starting from the layer closes to the user:
+
+**Interface layer**
+
+  * `IColony.sol`
+  * `IMetaColony.sol`
+  * `IColonyNetwork.sol`
+  * `IReputationMiningCycle.sol`
+  * `ITokenLocking.sol`
+  * `IRecovery.sol`
+  * `IEtherRouter.sol`
+
+Finally, all public and external functions from the logic contracts for an entity are composed into a single interface. For example the Colony interface - `IColony.sol` is a superset of the public and external functions from the logic contracts for a Colony entity, i.e. `Colony.sol`, `ColonyFunding.sol`, `ColonyPayment.sol` and `ColonyTask.sol`. 
+
+This layer represents the Colony Network API, documented in the [Interface section](https://docs.colony.io/colonynetwork/interface-ietherrouter) of the documentation.
+
+**Logic layer**
+
+All function declarations live here and therefore this layer constitutes the majority of the code we write. There are often more than one contracts representing a single logical entity. For example the logic for a Colony entity is distributed across `Colony.sol`, `ColonyFunding.sol`, `ColonyPayment.sol` and `ColonyTask.sol`. Same thing is valid for the ColonyNetwork and ReputationMiningCycle entities. The TokenLocking logic however is succinct enough to be held entirely in the `TokenLocking.sol` contract.
+
+Note that this logic distribution is possible due to the [contract upgrade mechanism](/colonynetwork/docs-the-delegate-proxy-pattern/) we use where essentially all logic contracts for an entity, work with the same underlying `EtherRouter` delegate proxy instance.
+
+**Access layer**
+
+Access management in the network is handled by a group of contracts that underpin all of the application layers. 
+
+  * `CommonAuthority.sol`
+  * `ColonyAuthority.sol`
+  * `ColonyNetworkAuthority.sol`
+  * `DomainRoles.sol`
+   
+These are based on the `DSRoles` and `DSAuth` implementations from the [dappsys library of contracts](https://github.com/dapphub/dappsys-monolithic).
+For a full list of these contracts, see the "Roles and Authority" point below. Also see [modular permissions section](/colonynetwork/docs-modular-permissions) for design details.
+
+**Data Layer**
+
+Data structures, enums, constants and events are declared in a dedicated `*DataTypes.sol` contract, e.g. `ColonyDataTypes.sol`.
+
+For clarity all storage variables are held separately in a `*Storage.sol` contract, e.g. `ColonyStorage.sol`. Storage variable declaration ordering is crucial to be maintained correctly as that ordering cannot change during contract upgrages, due to the [contract upgrade mechanism](/colonynetwork/docs-the-delegate-proxy-pattern/) we use.
+
+Additionally when using recovery mode, we write to storage slots directly so again it is essential to maintain as clear storage layout as possible. We even have code comments with slot numbers in the storage contracts to faciliate that process.
+
+**Integrations**
+
+* Extension contracts that allow for custom, legacy, or modified extention contracts to be added to a colony.
+  * `ExtensionFactory.sol`
+  * `OldRoles.sol`
+  * `OldRolesFactory.sol`
+  * `OneTxPayment.sol`
+  * `OneTxPaymentFactory.sol`
+
+* ENS contracts that define a custom ENS registry for use with colonies and the Colony Network.
+  * `ENS.sol`
+  * `ENSRegistry.sol`
+
+## Logic Entities
+Broadly speaking, the Colony Network can be divided into four logical entities:
+
+**Colony**
+
+Defines the state of an individual colony, such as funding pots, tasks, domains, and skills. 
+  * `Colony.sol`
+  * `ColonyFunding.sol`
+  * `ColonyPayment.sol`
+  * `ColonyTask.sol`
+
+  * `ColonyStorage.sol`
+  * `ColonyDataTypes.sol`
+
+**Colony Network **
+
+Defines a global state shared by all colonies, such as reputation, token auctions and ENS.
+  * `ColonyNetwork.sol`
+  * `ColonyNetworkAuction.sol`
+  * `ColonyNetworkENS.sol`
+  * `ColonyNetworkMining.sol`
+
+  * `ColonyNetworkStorage.sol`
+  * `ColonyNetworkDataTypes.sol`
+
+**Reputation Mining Cycle**
+
+Define a consensus protocol for validators of the global reputation state.
+  * `ReputationMiningCycle.sol`
+  * `ReputationMiningCycleRespond.sol`
+
+  * `ReputationMiningCycleStorage.sol`
+  * `ReputationMiningCycleDataTypes.sol`
+
+**Token locking**
+
+Allowing witholding access to deposited tokens from all colonies in the network.
+  * `TokenLocking.sol`
+
+  * `TokenLockingStorage.sol`
+  * `TokenLockingDataTypes.sol`