updated documentation to have mermaid diagrams; updated AGENTS.md to note that all future diagrams should be mermaid diagrams first with text-based diagrams as fallback where not applicable

2026-09-06 14:28:48 -06:00
parent 8c74efcedb
commit 3803787fe8
9 changed files with 133 additions and 41 deletions
@@ -59,11 +59,13 @@ get_catalog_objects :: proc(url: string, catalog_name: string)            // nil

 ## Data flow gap

-```
-[DESI catalog store]  --(future)-->  [Rust/axum API]  --(nothing today)-->  [Odin + raylib GUI]
-                                        ^                                        ^
-                                        | serde JSON models                    | hand-mirrored structs
-                                        |                                      | (stubs, never used)
+```mermaid
+flowchart LR
+    A["DESI catalog store"]
+    B["Rust / axum API<br/><i>serde JSON models</i>"]
+    C["Odin + raylib GUI<br/><i>hand-mirrored structs<br/>stubs, never used</i>"]
+    A -. "future ingestion" .-> B
+    B --x|"nothing today"| C
 ```

 There is **no live data flow**. The API currently returns JSON placeholders; the
@@ -116,17 +118,16 @@ response protocol with a cheap binary payload would fit this well.

 ## High-level target architecture

-```
-        catalog.fbs (single source of truth, checked into repo)
-              |
-     +--------+---------+
-     |                  |
-flatc --rust       flatcc --c (or hand-rolled Odin reader)
-     |                  |
-api/ (Rust)        gui/ (Odin + raylib)
-     |                  ^
-     |   HTTP / WebSocket (framed FlatBuffer binary stream)
-     +------------------+
+```mermaid
+flowchart TB
+    S["catalog.fbs<br/><i>single source of truth<br/>checked into repo</i>"]
+    R["flatc --rust"]
+    C["flatcc --c<br/><i>or hand-rolled Odin reader</i>"]
+    API["api/ · Rust"]
+    GUI["gui/ · Odin + raylib"]
+    S --> R --> API
+    S --> C --> GUI
+    API <-->|"HTTP / WebSocket<br/>framed FlatBuffer binary stream"| GUI
 ```

 - One schema file. Two generators. Byte-for-byte identical wire format.