1 files changed, 27 insertions, 19 deletions

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index a6b1bf873..d920ce2ab 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -58,27 +58,25 @@ all `//test test_name` comments into files inside `tests/data` directory.
 See [#93](https://github.com/rust-analyzer/rust-analyzer/pull/93) for an example PR which
 fixes a bug in the grammar.
 
-### `crates/ra_hir`
-
-HIR (previsouly known as descriptors) provides a high-level OO acess to Rust
-code.
+### `crates/ra_db`
 
-The principal difference between HIR and syntax trees is that HIR is bound
-to a particular crate instance. That is, it has cfg flags and features
-applied. So, there relation between syntax and HIR is many-to-one.
+We use [salsa][https://github.com/salsa-rs/salsa] crate for incremental and
+on-demand computation. Roughly, you can think of salsa as a key-value store, but
+it also can compute derived values using specified functions. The `ra_db` crate
+provides a basic infrastructure for interracting with salsa. Crucially, it
+defines most of the "input" queries: facts supplied by the client of the analyzer.
 
-### `crates/ra_editor`
+### `crates/ra_hir`
 
-All IDE features which can be implemented if you only have access to a
-single file. `ra_editor` could be used to enhance editing of Rust code
-without the need to fiddle with build-systems, file
-synchronization and such.
+HIR provides a high-level "object oriented" acess to Rust code.
 
-In a sense, `ra_editor` is just a bunch of pure functions which take a
-syntax tree as an input.
+The principal difference between HIR and syntax trees is that HIR is bound to a
+particular crate instance. That is, it has cfg flags and features applied (in
+theory, in practice this is to be implemented). So, there relation between
+syntax and HIR is many-to-one. The `source_binder` modules is responsible for
+guessing a hir for a particular source position.
 
-The tests for `ra_editor` are `#[cfg(test)] mod tests` unit-tests spread
-throughout its modules.
+Underneath, hir works on top of salsa, using a `HirDatabase` trait.
 
 ### `crates/ra_analysis`
 
@@ -88,9 +86,6 @@ current state, incorporates changes and handles out `Analysis` --- an
 immutable consistent snapshot of world state at a point in time, which
 actually powers analysis.
 
-### `crates/ra_db`
-This defines basic database traits. Concrete DB is defined by ra_analysis.
-
 ### `crates/ra_lsp_server`
 
 An LSP implementation which uses `ra_analysis` for managing state and
@@ -100,6 +95,19 @@ See [#79](https://github.com/rust-analyzer/rust-analyzer/pull/79/) as an
 example of PR which adds a new feature to `ra_editor` and exposes it
 to `ra_lsp_server`.
 
+### `crates/ra_editor`
+
+All IDE features which can be implemented if you only have access to a
+single file. `ra_editor` could be used to enhance editing of Rust code
+without the need to fiddle with build-systems, file
+synchronization and such.
+
+In a sense, `ra_editor` is just a bunch of pure functions which take a
+syntax tree as an input.
+
+The tests for `ra_editor` are `#[cfg(test)] mod tests` unit-tests spread
+throughout its modules.
+
 ### `crates/gen_lsp_server`
 
 A language server scaffold, exposing a synchronous crossbeam-channel based API.