docs

README.md

@@ -238,7 +238,7 @@ You development/testing flow should look like this:
 * You trigger your test command. 1..n test runners/processes start in parallel
 * **Once** per test runner/process:
   * Get migrations/fixtures files `hash` over all related database files
-  * `InitializeTemplate: POST /templates`: attempt to create a new PostgreSQL template database identifying though the above hash `payload: {"hash": "string"}`
+  * `InitializeTemplate: POST /api/v1/templates`: attempt to create a new PostgreSQL template database identified by the above hash `payload: {"hash": "string"}`
     * `StatusOK: 200` 
       * Truncate
       * Apply all migrations
@@ -417,7 +417,7 @@ This is actually the (simplified) strategy, that we have used in [allaboutapps-b
 
 Here's a quick benchmark of how this strategy typically performed back then:
 
-```
+```bash
 --- ----------------<storageHelper strategy report>---------------- ---
     replicas switched:          50     avg=11ms min=1ms max=445ms
     replicas awaited:           1      prebuffer=8 avg=436ms max=436ms
@@ -449,7 +449,7 @@ The cool thing about having a warm pool of replicas setup in the background, is
 
 Let's look at a sightly bigger testsuite and see how this approach may possibly scale:
 
-```
+```bash
 --- -----------------<storageHelper strategy report>------------------ ---
     replicas switched:             280    avg=26ms min=11ms max=447ms
     replicas awaited:              1      prebuffer=8 avg=417ms max=417ms

docs/arch.md

@@ -0,0 +1,27 @@
+<!-- 
+This file contains [mermaid](https://mermaid.js.org) diagrams.
+
+In VSCode:
+* install `bierner.markdown-mermaid` to have easy preview.
+* install `bpruitt-goddard.mermaid-markdown-syntax-highlighting` for syntax highlighting.
+
+To Export:
+* npm install -g @mermaid-js/mermaid-cli
+* mmdc -i arch.template.md -o arch.md
+
+Syntax, see https://mermaid.js.org/syntax/entityRelationshipDiagram.html
+-->
+
+# IntegreSQL Architecture
+
+## Pool structure
+
+The following describes the relationship between the components of IntegreSQL.
+
+![diagram](./arch-1.svg)
+
+## TestDatabase states
+
+The following describes the state and transitions of a TestDatabase.
+
+![diagram](./arch-2.svg)

docs/arch.template.md

@@ -0,0 +1,70 @@
+<!-- 
+This file contains [mermaid](https://mermaid.js.org) diagrams.
+
+In VSCode:
+* install `bierner.markdown-mermaid` to have easy preview.
+* install `bpruitt-goddard.mermaid-markdown-syntax-highlighting` for syntax highlighting.
+
+To Export:
+* npm install -g @mermaid-js/mermaid-cli
+* mmdc -i arch.template.md -o arch.md
+
+Syntax, see https://mermaid.js.org/syntax/entityRelationshipDiagram.html
+-->
+
+# IntegreSQL Architecture
+
+## Pool structure
+
+The following describes the relationship between the components of IntegreSQL.
+
+```mermaid
+erDiagram
+    Server ||--o| Manager : owns
+    Manager {
+        Template[] templateCollection
+        HashPool[] poolCollection
+    }
+    Manager ||--o{ HashPool : has
+    Manager ||--o{ Template : has
+    Template {
+        TemplateDatabase database
+    }
+    HashPool {
+        TestDatabase database
+    }
+    HashPool ||--o{ TestDatabase : "manages"
+    Template ||--|| TemplateDatabase : "sets"
+    TestDatabase {
+        int ID
+        Database database
+    }
+    TemplateDatabase {
+        Database database
+    }
+    Database {
+        string TemplateHash
+        Config DatabaseConfig
+    }
+    TestDatabase o|--|| Database : "is"
+    TemplateDatabase o|--|| Database : "is"
+```
+
+## TestDatabase states
+
+The following describes the state and transitions of a TestDatabase.
+
+```mermaid
+stateDiagram-v2
+
+    HashPool --> TestDatabase: Task EXTEND
+
+    state TestDatabase {
+        [*] --> ready: init
+        ready --> dirty: GetTestDatabase()
+        dirty --> ready: ReturnTestDatabase()
+        dirty --> recreating: RecreateTestDatabase()\nTask CLEAN_DIRTY
+        recreating --> ready: generation++
+        recreating --> recreating: retry (still in use)
+    }
+```

docs/integration.md

@@ -0,0 +1,19 @@
+<!-- 
+This file contains [mermaid](https://mermaid.js.org) diagrams.
+
+In VSCode:
+* install `bierner.markdown-mermaid` to have easy preview.
+* install `bpruitt-goddard.mermaid-markdown-syntax-highlighting` for syntax highlighting.
+
+To Export:
+* npm install -g @mermaid-js/mermaid-cli
+* mmdc -i integration.template.md -o integration.md
+
+Syntax, see https://mermaid.js.org/syntax/entityRelationshipDiagram.html
+-->
+
+# Integrate via REST API
+
+## Once per test runner/process:
+
+![diagram](./integration-1.svg)

docs/integration.template.md

@@ -0,0 +1,57 @@
+<!-- 
+This file contains [mermaid](https://mermaid.js.org) diagrams.
+
+In VSCode:
+* install `bierner.markdown-mermaid` to have easy preview.
+* install `bpruitt-goddard.mermaid-markdown-syntax-highlighting` for syntax highlighting.
+
+To Export:
+* npm install -g @mermaid-js/mermaid-cli
+* mmdc -i integration.template.md -o integration.md
+
+Syntax, see https://mermaid.js.org/syntax/entityRelationshipDiagram.html
+-->
+
+# Integrate via REST API
+
+## Once per test runner/process:
+
+```mermaid
+sequenceDiagram
+    You->>Testrunner: make test
+
+    Note right of Testrunner: Compute a migrations/fixtures files hash over all related database files
+
+
+    Testrunner->>IntegreSQL: InitializeTemplate: POST /api/v1/templates
+
+    Note over Testrunner,IntegreSQL: Create a new PostgreSQL template database<br/> identified a the same unique hash <br/>payload: {"hash": "string"} 
+
+    IntegreSQL->>PostgreSQL: CREATE DATABASE <br/>template_<hash>
+    PostgreSQL-->>IntegreSQL: 
+
+    IntegreSQL-->>Testrunner: StatusOK: 200
+
+    Note over Testrunner,PostgreSQL: Parse the received database connection payload and connect to the template database.
+
+    Testrunner->>PostgreSQL: Truncate, apply all migrations, seed all fixtures, ..., disconnect.
+    PostgreSQL-->>Testrunner: 
+
+    Note over Testrunner,IntegreSQL: Finalize the template so it can be used!
+
+    Testrunner->>IntegreSQL: FinalizeTemplate: PUT /api/v1/templates/:hash
+    IntegreSQL-->>Testrunner: StatusOK: 200
+
+    Note over Testrunner,IntegreSQL: You can now get isolated test databases from the pool!
+
+    Note over Testrunner,IntegreSQL: In case you have multiple testrunners/processes <br/>and call with the same template hash again
+
+    Testrunner->>IntegreSQL: InitializeTemplate: POST /api/v1/templates
+    IntegreSQL-->>Testrunner: StatusLocked: 423
+
+    Note over Testrunner,IntegreSQL: Some other process has already recreated <br/> a PostgreSQL template database for this hash<br/> (or is currently doing it), you can just consider<br/> the template ready at this point.
+
+    IntegreSQL-->>Testrunner: StatusServiceUnavailable: 503
+
+    Note over Testrunner,IntegreSQL: Typically happens if IntegreSQL cannot communicate with<br/>PostgreSQL, fail the test runner process
+```