From ecd207bf263c329736c4b83e0a3968d89d3e6f09 Mon Sep 17 00:00:00 2001
From: Damien Elmes <gpg@ankiweb.net>
Date: Tue, 20 Jul 2021 11:59:39 +1000
Subject: [PATCH] add a brief architecture file

---
 docs/architecture.md | 35 +++++++++++++++++++++++++++++++++++
 docs/development.md  |  8 --------
 2 files changed, 35 insertions(+), 8 deletions(-)
 create mode 100644 docs/architecture.md

diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 000000000..d0f56c53c
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,35 @@
+# Anki Architecture
+
+Very brief notes for now.
+
+## Backend/GUI
+
+At the highest level, Anki is logically separated into two parts.
+
+### Library
+
+The Python library (pylib) exports "backend" methods - opening collections,
+fetching and answering cards, and so on. It is used by Anki’s GUI, and can also
+be included in command line programs to access Anki decks without the GUI.
+
+The library is accessible in Python with "import anki". Its code lives in
+the `pylib/anki/` folder.
+
+These days, the majority of backend logic lives in a Rust library (rslib, located in `rslib/`). Calls to pylib proxy requests to rslib, and return the results.
+
+pylib contains a private Python module called rsbridge (`pylib/rsbridge/`) that wraps the Rust code, making it accessible in Python.
+
+### GUI
+
+Anki's *GUI* is a mix of Qt (via the PyQt Python bindings for Qt), and
+TypeScript/HTML/CSS. The Qt code lives in `qt/aqt/`, and is importable in Python
+with "import aqt". The web code is split between `qt/aqt/data/web/` and `ts/`,
+with the majority of new code being placed in the latter, and copied into the
+former at build time.
+
+## Protobuf
+
+Anki uses Protocol Buffers to define backend methods, and the storage format of
+some items in a collection file. The definitions live in `proto/anki/`.
+
+The Python/Rust bridge uses them to pass data back and forth, and some of the TypeScript code also makes use of them, allowing data to be communicated in a type-safe manner between the different languages.
\ No newline at end of file
diff --git a/docs/development.md b/docs/development.md
index 1a9671e84..e23ff82cc 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -215,14 +215,6 @@ will fail with a "no such file or directory node_modules/anki" message.
 
 You can run bazel with '-s' to print the commands that are being executed.
 
-## Subcomponents
-
-- pylib contains a Python module (anki) with the non-GUI Python code,
-  and a bridge to the Rust code.
-- qt contains the Qt GUI implementation (aqt).
-- rslib contains the parts of the code implemented in Rust.
-- ts and qt/aqt/data/web contain Anki's typescript and sass files.
-
 ## Environmental Variables
 
 If ANKIDEV is set before starting Anki, some extra log messages will be printed on stdout,