docs: improve architecture diagram

- SVG format instead of PNG
- The components now have links to their reference in the Docs
- Supports dark mode

docs/_diagrams/README.md

@@ -37,3 +37,16 @@ zathura db.pdf &
 # live reload with entr
 echo db.tex | entr pdflatex --shell-escape -halt-on-error db.tex
 ```
+
+## UML
+
+The UML diagrams are created with https://plantuml.com/.
+
+PlantUML only creates one diagram per file.
+That's why we need to create another one for dark mode.
+For example, for the file [arch.uml](./arch.uml) there's [arch-dark](./arch-dark.uml) which includes the first one:
+
+```bash
+plantuml -tsvg arch.uml -o ../_static
+plantuml -tsvg -darkmode arch-dark.uml -o ../_static
+```

docs/_diagrams/arch-dark.uml

@@ -0,0 +1,3 @@
+@startuml
+!include arch.uml
+@enduml

docs/_diagrams/arch.uml

@@ -1,5 +1,7 @@
 @startuml
 
+skinparam backgroundColor transparent
+
 package "PostgREST" {
   () HTTP as HTTPAPI
   HTTPAPI  - [Auth]
@@ -14,11 +16,9 @@ package "PostgREST" {
   [Admin]  -r- () HTTPADMIN
   [Config] -l- () CLI
 
-  [Config] <-l~ Listener
+  [Config] <-r~ Listener
 
   HTTPADMIN -[hidden]r- CLI
-  Listener -[hidden]r- [Schema Cache]
-  Listener -[hidden]r- [Config]
   [Schema Cache] -l[hidden]- [Config]
   [Schema Cache] -l[hidden]- [Admin]
   [Schema Cache] -l[hidden]- CLI
@@ -26,16 +26,16 @@ package "PostgREST" {
 
 
 database "PostgreSQL" {
-  node "API schema" as API {
-    rectangle "Functions, Views"
-  }
   node Authorization {
     rectangle "Roles, GRANT, RLS"
   }
+  node "API schema" as API {
+    rectangle "Functions, Views"
+  }
   rectangle "Tables, extensions" as tbs
   API -d- tbs
 
- API -[hidden]l- Authorization
+  API -l[hidden]- Authorization
 }
 
 :user:
@@ -67,4 +67,18 @@ end note
 note top of Listener
   LISTEN session
 end note
+
+url of Admin is [[../references/admin_server.html#admin-server]]
+url of API is [[../explanations/schema_isolation.html]]
+url of Auth is [[../references/auth.html#authn]]
+url of Authorization is [[../explanations/db_authz.html]]
+url of CLI is [[../references/cli.html#cli]]
+url of "Connection Pool" is [[../references/connection_pool.html]]
+url of Config is [[../references/configuration.html#configuration]]
+url of HTTPADMIN is [[https://aosabook.org/en/posa/warp.html]]
+url of HTTPAPI is [[https://aosabook.org/en/posa/warp.html]]
+url of Listener is [[../references/listener.html#listener]]
+url of Proxy is [[../explanations/nginx.html]]
+url of "Schema Cache" is [[../references/schema_cache.html#schema-cache]]
+
 @enduml

docs/explanations/architecture.rst

@@ -6,7 +6,22 @@ This page describes the architecture of PostgREST.
 Bird's Eye View
 ===============
 
-.. image:: ../_static/arch.png
+You can click on the components to navigate to their respective documentation.
+
+  .. container:: img-dark
+
+    .. See https://github.com/sphinx-doc/sphinx/issues/2240#issuecomment-187366626
+
+    .. raw:: html
+
+      <object width="100%" data="../_static/arch-dark.svg" type="image/svg+xml"></object>
+
+  .. container:: img-light
+
+    .. raw:: html
+
+      <object width="100%" data="../_static/arch.svg" type="image/svg+xml"></object>
+
 
 Code Map
 ========

docs/explanations/schema_isolation.rst

@@ -1,7 +1,3 @@
-.. note::
-
-  This page is a work in progress.
-
 .. _schema_isolation:
 
 Schema Isolation

nix/tools/docs.nix

@@ -90,7 +90,8 @@ let
         ${pdflatex}/bin/pdflatex -halt-on-error -output-directory="$tmpdir" db.tex
         ${imagemagick}/bin/convert -density 300 "$tmpdir/db.pdf" ../_static/db.png
 
-        ${plantuml}/bin/plantuml arch.uml -o ../_static
+        ${plantuml}/bin/plantuml -tsvg arch.uml -o ../_static
+        ${plantuml}/bin/plantuml -tsvg -darkmode arch-dark.uml -o ../_static
       '';
 
   server =