docs(contributing): explanations about the project arhictecture and some cheat sheet about terminal terminology (#26)

* docs(contributing): codebase documentation for new contributors

* docs(architecture): fix line breaks

* docs(terminology): fix line breaks

2 files changed, 60 insertions, 0 deletions

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
new file mode 100644
index 000000000..d10a13a9c
--- /dev/null
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,41 @@
+This document details the different components of the code base in plain English. The intention is to provide a high level description rather than a more detailed drill-down of each internal mechanism.
+
+## Screen (src/screen.rs)
+The Screen is responsible for managing the relationship between the panes currently displayed on screen.
+It is in charge of actions such as: 
+  * Coordinating the resizing of panes
+  * Creating new panes
+  * Closing existing panes (and filling up their space by other panes)
+
+## Terminal Pane (src/terminal_pane/terminal_pane.rs)
+The TerminalPane represents a pane on screen that connects to a single pty (pseudo terminal) and (presumably) has one shell or other program running inside it.
+The TerminalPane has two main roles:
+  * Keeping track of the Scroll, which represents the buffer of lines in this terminal
+  * Interpreting the ANSI/VT instructions coming from the pty in order to adjust the styling of characters, change the cursor position, etc.
+
+### Scroll (src/terminal_pane/scroll.rs)
+The Scroll holds the terminal buffer and is in charge of:
+  * Keeping teack of the viewport (which part of it we see) this can change when we scroll up/down
+  * Keeping track of the cursor position
+  * Controlling line-wrapping
+
+### Terminal Character (src/terminal_pane/terminal_character.rs)
+The TerminalCharacter represents a single character in the pane. It holds the char itself on the one hand, and an internal `CharacterStyles` struct representing the styling of this character.
+This struct derives the `Copy` trait for performance reasons, because it is moved around quite a bit (eg. when line wrapping).
+
+### How a terminal emulator draws characters?
+The ANSI/VT instructions received from the pty include style instructions (eg. change foreground colour to red) as well as instructions to reposition the cursor (eg. go to line x/y) and to perform certain actions with the current buffer on-screen (eg. delete all lines after cursor).
+
+When an instruction is received to change the character style, we know that all characters printed from now on should use that style. This is true until we move to a new line (with a newline instruction or a go to instruction) or until we receive a style reset code for this specific style. There are several kinds of reset codes that apply to different styles.
+
+It's important to understand that these styles are ongoing relative to the current cursor position. It might be useful to imagine them as brushes: "pick up the red brush", "put down the bold brush", etc.
+
+This is important to note because the styles themselves are saved only on characters that have already been printed. If we receive an instruction to change the style to blue, then print a (blue) character, then receive another instruction to move to a new line, print another (plain) character and then come back, the style would be reset. We would have to receive a new instruction to change the style to blue in order for the next character to be blue.
+
+## Boundaries (src/boundaries.rs)
+The Boundaries refer to those lines that are drawn between terminal panes. A few things that happen here:
+  * The Rect trait is here so that different panes can implement it, giving boundaries a generic way to calculate the size of the pane and draw boundaries around it.
+  * Here we use the [unicode box drawing characters](https://en.wikipedia.org/wiki/Box-drawing_character) in order to draw the borders. There's some logic here about combining them together for all possible combinations of pane locations.
+
+## PTY Bus
+The PtyBus keeps track of several asynchronous streams that read from pty sockets (eg. /dev/pts/999), parse those bytes into ANSI/VT events and send them on to the Screen so that they can be received in the relevant TerminalPane.
diff --git a/docs/TERMINOLOGY.md b/docs/TERMINOLOGY.md
new file mode 100644
index 000000000..409e70d2a
--- /dev/null
+++ b/docs/TERMINOLOGY.md
@@ -0,0 +1,19 @@
+## ANSI/VT
+This refers to the stream of text one receives when listening to the primary side of the pty.
+For example `[31mHi [5mthere!` would print the word "Hi" in red and then the word "there!" in a blinking red. You can try this in your terminal with the echo command:
+
+`echo -e "\033[31mHi \033[5mthere!"` (`\033` is an escape character).
+
+## CSI (Control Sequence Identifier)
+Part of the ANSI/VT specification that includes instructions for the terminal emulator. These instructions can be a style change (eg. change color to red) or cursor position change (eg. go to line x/y).
+
+## OSC (Operating System Command)
+Part of the ANSI/VT specification that includes instructions for the underlying operating system (eg. change window title).
+
+## pty
+A pty (pseudoterminal) is a character device that emulates a traditional terminal. It is a pair of processes (traditionally given culturally incensitive names, here they will be refered to as primary/secondary).
+
+The primary part is the part connected to the terminal emulator. The emulator listens to this part of the channel, reads instructions from it that it uses in order to draw characters on the screen.
+The secondary part is used by the program running inside the terminal (eg. the shell) in order to send those instructions.
+
+In Mosaic, there is one pty pair  for each terminal pane.