docs: add architecture diagram

ARCHITECTURE.md

@@ -1,68 +1,3 @@
 # Architecture
 
-This document describes the high-level architecture of PostgREST.
-
-## Bird's Eye View
-
-```haskell
-postgrest :: Request -> Either Error SQLStatement -> Response
-```
-
-On the highest level, PostgREST processes an HTTP request, if it's accepted it builds a SQL statement for it, executes it, and produces a response.
-
-## Code Map
-
-This section talks briefly about various important modules.
-
-The starting point of the program is `main/Main.hs`, which calls `src/PostgREST/CLI.hs` which then calls `src/PostgREST/App.hs`.
-
-`App.hs` is then in charge of composing the different modules.
-
-### ApiRequest.hs
-
-PostgREST operates over two types of resources: database relations(tables or views) and database functions; providing different representations(depending on the media type)
-for them.
-
-This module is in charge of representing the operation over an `ApiRequest` type. It parses the URL querystring following PostgREST syntax, the request headers, and the request body
-(if possible it avoids parsing the body and sends it directly to the db).
-
-A request might be rejected at this level if it's invalid, e.g. providing an unknown media type to PostgREST or using an unknown HTTP method.
-
-### Plan.hs
-
-Using the Schema Cache, this module enables more complex functionality(like resource embedding) by enriching the ApiRequest. It generates Plan types(`ReadPlan`, `MutatePlan`)
-that then will be used to generate a SQL statement.
-
-A request might be rejected at this level if it's invalid, e.g. by doing resource embedding on a nonexistent resource.
-
-An OPTIONS request doesn't require a plan to be generated.
-
-### Query.hs
-
-This module constructs single SQL statements that can be parametrized and prepared. Only at this stage a PostgreSQL connection from the pool is used.
-
-A query might fail(and be rollbacked) at this level if it doesn't comply to certain conditions, e.g. by not returning a single row when a ``Accept: application/vnd.pgrst.object`` header is specified.
-
-An OPTIONS request doesn't require a query to be executed.
-
-### Response.hs
-
-This module constructs the HTTP response body with the right headers.
-
-It builds the OpenAPI response using the schema cache.
-
-### Auth.hs
-
-This module provides functions to deal with JWT authorization.
-
-### SchemaCache.hs
-
-This queries the PostgreSQL system catalogs and caches the metadata into a SchemaCache type,
-
-### AppState.hs
-
-The state of the App which is kept across requests.
-
-This spawns threads which are used to execute concurrent jobs.
-
-Jobs include connection recover and a listener for the PostgreSQL LISTEN command.
+![PostgREST Architecture](docs/_static/arch.png)

docs/_diagrams/arch.uml

@@ -0,0 +1,56 @@
+@startuml
+
+:user:
+
+package "PostgREST" {
+  () HTTP as HTTPAPI
+  HTTPAPI  - [Auth]
+  [Auth] -r.> [ApiRequest]
+  [ApiRequest] -r.> [Plan]
+  [Plan] -r.> [Query]
+  [Query] - () "Connection Pool" : "\t"
+  [Plan] -u-> [Schema Cache]:uses
+  [Query] -u-> [Schema Cache]:uses
+  [Schema Cache] <- () Listener : reloads "\t"
+  () HTTP as HTTPADMIN
+  [Admin] - () HTTPADMIN
+
+  /'HTTPADMIN <-r[hidden]- [Schema Cache] : "\t\t\t"'/
+}
+
+
+database "PostgreSQL" {
+  node Authorization {
+    rectangle "Roles, GRANT, RLS"
+  }
+  node API {
+    rectangle "Functions, Views"
+  }
+  rectangle "Tables, extensions" as texts
+  API -d- texts
+}
+
+HTTPAPI <.l- user : "\t"
+operator .d-> HTTPADMIN
+
+Listener -r.> "PostgreSQL"
+"Connection Pool" -r.> "PostgreSQL" : "\t\t"
+
+
+note bottom of Auth
+  Authenticates the user request
+end note
+
+note bottom of ApiRequest
+  Parses the URL syntax
+end note
+
+note bottom of Query
+  Generates the SQL
+end note
+
+note top of Listener
+  LISTEN session
+end note
+
+@enduml

nix/tools/docs.nix

@@ -7,6 +7,7 @@
 , python3Packages
 , texlive
 , writers
+, plantuml
 }:
 let
   selectPythonPackages = ps: [
@@ -87,6 +88,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
       '';
 
   server =