update readme

README.md

@@ -1,9 +1,55 @@
 # The Leo Programming Language
+
+## Compiler Architecture
+
+<!-- generated by mermaid compile action - START -->
+![~mermaid diagram 1~](/.resources/README-md-1.png)
+<details>
+  <summary>Mermaid markup</summary>
+
+```mermaid
+graph LR
+    Pass1(Syntax Parser) -- ast --> Pass2(Type Resolver)
+    
+    Pass2 -- imports --> Pass3(Import Resolver)
+    Pass3 -- statements --> Pass4
+    
+    Pass2 -- statements --> Pass4(Synthesizer)
+    
+    Pass4 -- constraints --> Pass5(Circuit)
+```
+
+</details>
+<!-- generated by mermaid compile action - END -->
+
+## Language Specification
+
 * Programs should be formatted:
     1. Import definitions
     2. Circuit definitions
     3. Function definitions
 
+## Defining Variables
+Leo supports `let` and `const` keywords for variable definition.
+
+```let a = true;``` defines an **allocated** program variable `a` with boolean value `true`.
+
+```const a = true;``` defines a **constant** program variable `a` with boolean value `true`.
+
+**Allocated** variables define private variables in the constraint system. Their value is constrained in the circuit on initialization.
+
+**Constant** variables do not define a variable in the constraint system. Their value is constrained in the circuit on computation with an **allocated** variable. 
+**Constant** variables can be mutable. They do not have the same functionality as `const` variables in other languages.
+```rust
+function addOne() -> {
+    let a = 0u8;   // allocated, value enforced on this line
+    const b = 1u8; // constant, value not enforced yet
+
+    return a + b   // allocated, computed value is enforced to be the sum of both values
+}
+```
+Computations are expressed in terms of arithmetic circuits, in particular rank-1 quadratic constraint systems. Thus computing on an allocated variable always results in another allocated variable. 
+
 ## Mutability
 * All defined variables in Leo are immutable by default.
 * Variables can be made mutable with the `mut` keyword.
@@ -31,7 +77,7 @@ function main() -> bool {
 ```
 
 ## Numbers
-* The definition of a number must include an explict type.
+* The definition of a number must include an explicit type.
 * After assignment, you can choose to explicitly add the type or let the compiler interpret implicitly.
 * Type casting is not supported.
 * Comparators are not supported.
@@ -134,7 +180,14 @@ function main() -> u32[3][2] {
 
 ## Conditionals
 
+Branching in Leo is different than traditional programming languages. Leo developers should keep in mind that every program compiles to a circuit which represents
+all possible evaluations.
+
 ### If Else Ternary Expression
+Ternary `if [cond] ? [first] : [second];` expressions are the cheapest form of conditional. 
+Since `first` and `second` are expressions, we can resolve their values before proceeding execution.
+In the underlying circuit, this is a single bit multiplexer.
+
 ```rust
 function main() -> u32 {
   let y = if 3==3 ? 1 : 5;
@@ -143,14 +196,15 @@ function main() -> u32 {
 ```
 
 ### If Else Conditional Statement
-** **Experimental** **
-The current constraint system is not optimized for statement branching. Please use the ternary expression above until this feature is stable.
+Leo supports the traditional `if [cond] { [first] } else { [second] }` which can be chained using `else if`.
+Since `first` and `second` are one or more statements, they resolve to separate circuits which will all be evaluated.
+In the underlying circuit this can be thought of as a demultiplexer.
 ```rust
 function main(a: bool, b: bool) -> u32 {
   let mut res = 0u32;
-  if (a) {
+  if a {
     res = 1;
-  } else if (b) {
+  } else if b {
     res = 2;
   } else {
     res = 3;
@@ -217,7 +271,7 @@ function main() -> u32[3] {
 }
 ```
 
-### Main function inputs
+### Function inputs
 Main function inputs are allocated private variables in the program's constraint system.
 `a` is implicitly private.
 ```rust
@@ -225,7 +279,7 @@ function main(a: field) -> field {
   return a
 }
 ```
-Function inputs are passed by value.
+Normal function inputs are passed by value.
 ```rust
 function test(mut a: u32) {
     a = 0;
@@ -547,4 +601,5 @@ cargo install --path .
 
 - Change `target` directory to some other directory to avoid collision.
 - Figure out how `leo prove` should take in assignments.
-- Come up with a serialization format for `.leo.pk`, `.leo.vk`, and `.leo.proof`.
+- Come up with a serialization format for `.leo.pk`, `.leo.vk`, and `.leo.proof`.
+