RustPython
diff --git a/‎architecture/architecture.md‎
Lines changed: 53 additions & 17 deletions b/‎architecture/architecture.md‎
Lines changed: 53 additions & 17 deletions
diff --git a/‎architecture/overview.png‎
-34.4 KB b/‎architecture/overview.png‎
-34.4 KB
@@ -20,7 +20,43 @@ If, after reading this, you want to contribute to RustPython, take a look at the
 
 A high-level overview of the workings of RustPython is visible in the figure below, showing how Python source files are interpreted.
 
-![overview.png](overview.png)
+```mermaid
+flowchart TB
+  SourceCode["🐍 Source code"]
+
+  subgraph Interpreter["RustPython Interpreter"]
+    direction TB
+
+    subgraph Parser["Parser"]
+        ParserBox["• Tokenize source code<br/>• Validate tokens<br/>• Create AST"]
+    end
+
+    AST[["AST"]]
+
+    subgraph Compiler["Compiler"]
+        CompilerBox["• Converts AST to bytecode"]
+    end
+
+    Bytecode[["Bytecode"]]
+
+    subgraph VM["VM"]
+        VMBox["• Executes bytecode given input"]
+    end
+
+    Parser --> AST
+    AST --> Compiler
+    Compiler --> Bytecode
+    Bytecode --> VM
+  end
+
+  SourceCode -------> Interpreter
+
+  Input[["Input"]]
+  Output["Code gets executed"]
+
+  Input --> VM
+  VM --> Output
+```
 
 Main architecture of RustPython.
 
@@ -36,17 +72,17 @@ The main entry point of RustPython is located in `src/main.rs` and simply forwar
 
 For each of the three components, the entry point is as follows:
 
-- Parser: The Parser is located in a separate project, [RustPython/Parser][10]. See the documentation there for more information.
-- Compiler: `compile`, located in [`vm/src/vm/compile.rs`][11], this eventually forwards a call to [`compiler::compile`][12].
-- VM: `run_code_obj`, located in [`vm/src/vm/mod.rs`][13]. This creates a new frame in which the bytecode is executed.
+- Parser: The Parser is located in a separate project, [ruff_python_parser][10]. See the documentation there for more information.
+- Compiler: `compile`, located in [`crates/vm/src/vm/compile.rs`][11], this eventually forwards a call to [`compiler::compile`][12].
+- VM: `run_code_obj`, located in [`crates/vm/src/vm/mod.rs`][13]. This creates a new frame in which the bytecode is executed.
 
 ## Components
 
 Here we give a brief overview of each component and its function. For more details for the separate crates please take a look at their respective READMEs.
 
 ### Compiler
 
-This component, implemented as the `rustpython-compiler/` package, is responsible for translating a Python source file into its equivalent bytecode representation. As an example, the following Python file:
+This component, implemented as the `rustpython-compiler` package, is responsible for translating a Python source file into its equivalent bytecode representation. As an example, the following Python file:
 
 ```python
 def f(x):
@@ -71,11 +107,11 @@ The Parser is the main sub-component of the compiler. All the functionality requ
 1. Lexical Analysis
 2. Parsing
 
-The functionality for parsing resides in the RustPython/Parser project. See the documentation there for more information.
+The functionality for parsing resides in the ruff_python_parser project in the astral-sh/ruff repository. See the documentation there for more information.
 
 ### VM
 
-The Virtual Machine (VM) is responsible for executing the bytecode generated by the compiler. It is implemented in the `rustpython-vm/` package. The VM is currently implemented as a stack machine, meaning that it uses a stack to store intermediate results. In the `rustpython-vm/` package, additional sub-components are present, for example:
+The Virtual Machine (VM) is responsible for executing the bytecode generated by the compiler. It is implemented in the `rustpython-vm` package. The VM is currently implemented as a stack machine, meaning that it uses a stack to store intermediate results. In the `rustpython-vm` package, additional sub-components are present, for example:
 
 - builtins: the built in objects of Python, such as `int` and `str`.
 - stdlib: parts of the standard library that contains built-in modules needed for the VM to function, such as `sys`.
@@ -122,7 +158,7 @@ The RustPython executable/REPL (Read-Eval-Print-Loop) is implemented here, which
 Some things to note:
 
 - The CLI is defined in the [`run` function of `src/lib.rs`][16].
-- The interface and helper for the REPL are defined in this package, but the actual REPL can be found in `vm/src/readline.rs`
+- The interface and helper for the REPL are defined in this package, but the actual REPL can be found in `crates/vm/src/readline.rs`
 
 ### WASM
 
@@ -133,18 +169,18 @@ Crate for WebAssembly build, which compiles the RustPython package to a format t
 Integration and snippets that test for additional edge-cases, implementation specific functionality and bug report snippets.
 
 [1]: https://github.com/RustPython/RustPython
-[2]: https://2021.desosa.nl/projects/rustpython/posts/vision/
+[2]: https://web.archive.org/web/20240723122357/https://2021.desosa.nl/projects/rustpython/posts/vision/
 [3]: https://www.youtube.com/watch?v=nJDY9ASuiLc&t=213s
 [4]: https://rustpython.github.io/2020/04/02/thing-explainer-parser.html
 [5]: https://rustpython.github.io/demo/
 [6]: https://rustpython.github.io/demo/notebook/
-[7]: https://github.com/RustPython/RustPython/blob/master/DEVELOPMENT.md
+[7]: https://github.com/RustPython/RustPython/blob/main/DEVELOPMENT.md
 [8]: https://rustpython.github.io/guideline/2020/04/04/how-to-contribute-by-cpython-unittest.html
-[9]: https://github.com/RustPython/RustPython/blob/0e24cf48c63ae4ca9f829e88142a987cab3a9966/src/lib.rs#L63
-[10]: https://github.com/RustPython/Parser
-[11]: https://github.com/RustPython/RustPython/blob/0e24cf48c63ae4ca9f829e88142a987cab3a9966/vm/src/vm/compile.rs#LL10C17-L10C17
-[12]: https://github.com/RustPython/RustPython/blob/0e24cf48c63ae4ca9f829e88142a987cab3a9966/vm/src/vm/compile.rs#L26
-[13]: https://github.com/RustPython/RustPython/blob/0e24cf48c63ae4ca9f829e88142a987cab3a9966/vm/src/vm/mod.rs#L356
-[14]: https://github.com/RustPython/RustPython/blob/0e24cf48c63ae4ca9f829e88142a987cab3a9966/common/src/float_ops.rs
+[9]: https://github.com/RustPython/RustPython/blob/d36a2cffdef2218f3264cef9145a1f781d474ea3/src/lib.rs#L72
+[10]: https://github.com/astral-sh/ruff/tree/2bffef59665ce7d2630dfd72ee99846663660db8/crates/ruff_python_parser
+[11]: https://github.com/RustPython/RustPython/blob/d36a2cffdef2218f3264cef9145a1f781d474ea3/crates/vm/src/vm/compile.rs#L10
+[12]: https://github.com/RustPython/RustPython/blob/d36a2cffdef2218f3264cef9145a1f781d474ea3/crates/vm/src/vm/compile.rs#L26
+[13]: https://github.com/RustPython/RustPython/blob/d36a2cffdef2218f3264cef9145a1f781d474ea3/crates/vm/src/vm/mod.rs#L433
+[14]: https://github.com/RustPython/RustPython/blob/d36a2cffdef2218f3264cef9145a1f781d474ea3/crates/common/src/float_ops.rs
 [15]: https://rustpython.github.io/guideline/2020/04/04/how-to-contribute-by-cpython-unittest.html
-[16]: https://github.com/RustPython/RustPython/blob/0e24cf48c63ae4ca9f829e88142a987cab3a9966/src/lib.rs#L63
+[16]: https://github.com/RustPython/RustPython/blob/d36a2cffdef2218f3264cef9145a1f781d474ea3/src/lib.rs#L72