From 03c4f6f6ef2c255d21ba6aa8e1b24dc980dad48b Mon Sep 17 00:00:00 2001
From: Kacper Madej <kacperoza@gmail.com>
Date: Thu, 12 Dec 2024 17:06:29 +0100
Subject: [PATCH 1/3] Document typical flow

---
 docs/internals/typical_query.md | 37 +++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)
 create mode 100644 docs/internals/typical_query.md

diff --git a/docs/internals/typical_query.md b/docs/internals/typical_query.md
new file mode 100644
index 000000000..55220d4aa
--- /dev/null
+++ b/docs/internals/typical_query.md
@@ -0,0 +1,37 @@
+The following sequence diagram shows the typical flow of a query from the CLI to the VDBE.
+
+```mermaid
+sequenceDiagram
+
+participant main as cli/main
+participant Database as core/lib/Database
+participant Connection as core/lib/Connection
+participant Statement as core/lib/Statement
+participant Parser as sql/mod/Parser
+participant Scanner as sql/mod/Scanner
+participant translate as translate/mod
+participant Program as vdbe/mod/Program
+
+main->>Database: open_file
+Database->>main: Connection
+main->>Connection: query(sql)
+Note right of Parser: Uses vendored sqlite3-parser
+Connection->>Parser: next()
+Note left of Parser: Passes the SQL query to Parser
+
+Parser->>Scanner: scan()
+Scanner->>Parser: returns tokens
+
+
+Parser->>Connection: Cmd::Stmt
+Connection->>translate:translate() 
+
+Note left of translate: Translates SQL statement into bytecode
+
+Connection->>main: Ok(Some(Rows { Statement }))
+main->>Statement: step()
+Statement->>Program: step()
+Note left of Program: Executes bytecode instructions<br />See https://www.sqlite.org/opcode.html
+Program->>Statement: StepResult
+Statement->>main: StepResult
+```

From ffede0053187a0d61f8fe3bfd863666014059cd3 Mon Sep 17 00:00:00 2001
From: Kacper Madej <kacperoza@gmail.com>
Date: Thu, 12 Dec 2024 17:11:51 +0100
Subject: [PATCH 2/3] Add link to sqlite docs

---
 docs/internals/typical_query.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/internals/typical_query.md b/docs/internals/typical_query.md
index 55220d4aa..5b8e1d061 100644
--- a/docs/internals/typical_query.md
+++ b/docs/internals/typical_query.md
@@ -1,4 +1,4 @@
-The following sequence diagram shows the typical flow of a query from the CLI to the VDBE.
+The following sequence diagram shows the typical flow of a query from the CLI to the [VDBE](https://www.sqlite.org/opcode.html).
 
 ```mermaid
 sequenceDiagram

From 52b94f7181bf811eccb724a0b2458b1b03fef43c Mon Sep 17 00:00:00 2001
From: Kacper Madej <kacperoza@gmail.com>
Date: Thu, 12 Dec 2024 17:22:03 +0100
Subject: [PATCH 3/3] Update diagram

---
 docs/internals/typical_query.md | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/docs/internals/typical_query.md b/docs/internals/typical_query.md
index 5b8e1d061..d4d1c841f 100644
--- a/docs/internals/typical_query.md
+++ b/docs/internals/typical_query.md
@@ -6,32 +6,32 @@ sequenceDiagram
 participant main as cli/main
 participant Database as core/lib/Database
 participant Connection as core/lib/Connection
-participant Statement as core/lib/Statement
 participant Parser as sql/mod/Parser
-participant Scanner as sql/mod/Scanner
 participant translate as translate/mod
+participant Statement as core/lib/Statement
 participant Program as vdbe/mod/Program
 
 main->>Database: open_file
 Database->>main: Connection
 main->>Connection: query(sql)
-Note right of Parser: Uses vendored sqlite3-parser
+Note left of Parser: Parser uses vendored sqlite3-parser
 Connection->>Parser: next()
 Note left of Parser: Passes the SQL query to Parser
 
-Parser->>Scanner: scan()
-Scanner->>Parser: returns tokens
+Parser->>Connection: Cmd::Stmt (ast/mod.rs)
 
+Note right of translate: Translates SQL statement into bytecode
+Connection->>translate:translate(stmt)
 
-Parser->>Connection: Cmd::Stmt
-Connection->>translate:translate() 
-
-Note left of translate: Translates SQL statement into bytecode
+translate->>Connection: Program 
 
 Connection->>main: Ok(Some(Rows { Statement }))
+
+note right of main: a Statement with <br />a reference to Program is returned
+
 main->>Statement: step()
 Statement->>Program: step()
-Note left of Program: Executes bytecode instructions<br />See https://www.sqlite.org/opcode.html
+Note left of Program: Program executes bytecode instructions<br />See https://www.sqlite.org/opcode.html
 Program->>Statement: StepResult
 Statement->>main: StepResult
 ```