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