diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 000000000..8fd7d51ec
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,46 @@
+# High-Level Architecture
+
+## Path Building
+
+
+ 
+
+
+Starting from the top, here's a high-level overview of how the lokinet client builds a path to a terminating node
+
+1. Client semi-randomly selects SN's for hops 2 and 3 using Introset Hash Ring (IHR)
+ - First hop is sticky: upon initialization of lokinet, 4-5 first hops are selected
+
+2. Message sent to hop 1
+ - Message consists of eight records in a linked list. Four hops are typically used, leaving the last 4 links as dummy records
+ - Each record contains a TX (upstream) path ID and RX (downstream) path ID
+ - Each record has a pointer to the next record, except for the final hops' record; the pointer here is recursive, signalling the end of the path-build
+
+3. Hop 2 pops top record, appends metadata, and pushes record to the back of linked list
+ - Hop adds metadata to the record, such as optional lifetime, pubkey to derive shared secret, etc
+
+4. Steps 2-3 are repeated for the remaining hops until destination is reached
+ - Final hop reads the recursive pointer signalling the end of the path-build process
+
+5. Upon completion, plain-text reply is propagated backwards, where the client can then decrypt all records
+
+6. Client measures latency
+ - A) Routing message is sequentially encrypted using hop 4's key through hop 1's key
+ - At each iteration, the nonce is permuted by XOR'ing the previous nonce with the hash of the secret key of each hop
+ - B) Routing message is sent s.t. each hop can decrypt, with final hop receiving plain-text
+ - Each hop appends latency and expiration time data, with the final hop interpreting the plain-text as a routing message and sending it back to the client
+
+7. Introset is published to IHR upon successful completion; introset contains:
+ - Path ID's of routers
+ - Latency and expiration time for each hop
+ - DNS SRV records
+ - etc
+
+### Failure Cases
+
+1. Next hop is an invalid SN
+2. Cannot connect to SN
+
+In either case, the path-build status is sent backwards with an error flag. Once received by the client, metadata related to the prospective path is wiped and the path forgotten
+
+
diff --git a/docs/high-level-overview.md b/docs/high-level-overview.md
deleted file mode 100644
index 1d2baea84..000000000
--- a/docs/high-level-overview.md
+++ /dev/null
@@ -1,19 +0,0 @@
-## onion routing overview
-
-
-
-
-
-
-
-## endpoint zmq api
-
-
-
-## DNS
-
-
-
-
-
-
diff --git a/docs/ideal-ux.md b/docs/ideal-ux.md
index 7cda8e29a..9b78c763a 100644
--- a/docs/ideal-ux.md
+++ b/docs/ideal-ux.md
@@ -8,7 +8,7 @@ The `.snode` gtld refers to a router on the network by its public ed25519 key.
The `.loki` gtld refers to clients that publish the existence anonymously to the network by their ed25519 public key. (`.loki` also has the ability to use short names resolved via external consensus method, like a blockchain).
-# How Do I use Lokinet?
+# How do I use Lokinet?
set system dns resolver to use the dns resolver provided by lokinet, make sure the upstream dns provider that lokinet uses for non lokinet gtlds is set as desired (see lokinet.ini `[dns]` section)
@@ -16,7 +16,7 @@ configure exit traffic provider if you want to tunnel ip traffic via lokinet, by
note: per flow (ip+proto/port) isolation is trivial on a technical level but currently not implemented at this time.
-# Can I run lokinet on a soho router
+# Can I run lokinet on a soho router?
Yes and that is the best way to run it in practice.
diff --git a/docs/install.md b/docs/install.md
index 17cf9da08..21d69dd5b 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -30,7 +30,7 @@ You can get the latest stable release for lokinet on windows or macos from https
You do not have to build from source if you do not wish to, we provide [apt](#deb-install) and [rpm](#rpm-install) repos.
-#### APT repository
+#### APT Repository
You can install debian packages from `deb.oxen.io` by adding the apt repo to your system.
diff --git a/docs/lokinet_pathbuild_no_steps.png b/docs/lokinet_pathbuild_no_steps.png
new file mode 100644
index 000000000..7967150e3
Binary files /dev/null and b/docs/lokinet_pathbuild_no_steps.png differ
diff --git a/docs/net-comparisons.md b/docs/net-comparisons.md
index 65264cd37..4dc1ffc0e 100644
--- a/docs/net-comparisons.md
+++ b/docs/net-comparisons.md
@@ -1,6 +1,5 @@
# How is lokinet different than ...
-
## Tor Browser
Tor browser is a hardened Firefox Web Browser meant exclusively to surf http(s) sites via Tor. It is meant to be a complete self contained browser you open and run to surf the Web (not the internet) anonymously.
diff --git a/docs/project-structure.md b/docs/project-structure.md
index 7c06c70f8..61c63c291 100644
--- a/docs/project-structure.md
+++ b/docs/project-structure.md
@@ -1,8 +1,8 @@
-# Lokinet project structure
+# Lokinet Project Structure
this codebase is a bit large. this is a high level map of the current code structure.
-## lokinet executable main functions `(/daemon)`
+## Lokinet executable main functions `(/daemon)`
* `lokinet.cpp`: lokinet daemon executable
* `lokinet.swift`: macos sysex/appex executable
@@ -10,14 +10,14 @@ this codebase is a bit large. this is a high level map of the current code struc
* `lokinet-bootstrap.cpp`: legacy util for windows, downloads a bootstrap file via https
-## lokinet public headers `(/include)`
+## Lokinet public headers `(/include)`
`lokinet.h and lokinet/*.h`: C headers for embedded lokinet
`llarp.hpp`: semi-internal C++ header for lokinet executables
-## lokinet core library `(/llarp)`
+## Lokinet core library `(/llarp)`
* `/llarp`: contains a few straggling compilation units
* `/llarp/android`: android platform compat shims
@@ -49,7 +49,7 @@ this codebase is a bit large. this is a high level map of the current code struc
* `/llarp/win32`: windows specific code
-## component relations
+## Component relations
### `/llarp/service` / `/llarp/handlers` / `/llarp/exit`
@@ -82,7 +82,7 @@ node to node traffic logic and wire protocol dialects
* `//TODO: separte implementation details from interfaces`
-## platform contrib code `(/contrib)`
+## Platform contrib code `(/contrib)`
grab bag directory for non core related platform specific non source code
diff --git a/docs/readme.md b/docs/readme.md
index 534a19497..25e4b21ad 100644
--- a/docs/readme.md
+++ b/docs/readme.md
@@ -2,33 +2,25 @@
This is where Lokinet documentation lives.
-[How Do I install Lokinet?](install.md)
+## Contents:
-[How Do I use Lokinet?](ideal-ux.md)
+### Local Environment Set-Up
+ - [Installing Lokinet](install.md)
+ - [Using Lokinet](ideal-ux.md)
-## High level
-[How is Lokinet different to \[insert network technology name here\] ?](net-comparisons.md)
+### High Level Overview
+ - [Lokinet versus \[insert network technology name here\]](net-comparisons.md)
+ - [Lokinet architecture](architecture.md)
+ - [Lokinet and DNS](dns-overview.md)
+ - [Limitations of Lokinet](we-cannot-make-sandwiches.md)
-
-
-[Lokinet and DNS](dns-overview.md)
-
-[What Lokinet can't do](we-cannot-make-sandwiches.md)
-
-## Lokinet Internals
-
-[High level layout of the git repo](project-structure.md)
-
-
-[Build Doxygen Docs for internals](doxygen.md)
-
-## Lokinet (SN)Application Developer Portal
-
-
-[What are "SNApps" and how to develop them.](snapps-dev-guide.md)
-
-[How do I embed lokinet into my application?](liblokinet-dev-guide.md)
+### Lokinet Internals
+ - [Git repo layout and project structure](project-structure.md)
+ - [Building Doxygen Docs for internals](doxygen.md)
+### Lokinet (SN)Application Developer Portal
+ - [SNapps development overview](snapps-dev-guide.md)
+ - [Embedded Lokinet](liblokinet-dev-guide.md)