Merge pull request #15 from Promptly-Technologies-LLC/13-document-design-patterns

Added graph to illustrate PRG request-response flow

Author: chriscarrollsmith

README.md

@@ -7,7 +7,45 @@
 
 This project is still under development.
 
-### Install development dependencies
+### Architecture
+
+This application uses a Post-Redirect-Get (PRG) pattern. The user
+submits a form, which sends a POST request to a FastAPI endpoint on the
+server. The database is updated, and the user is redirected to a GET
+endpoint, which fetches the updated data and re-renders the Jinja2 page
+template with the new data.
+
+![Webapp Flow](static/webapp_flow.png)
+
+The advantage of the PRG pattern is that it is very straightforward to
+implement and keeps most of the rendering logic on the server side. The
+disadvantage is that it requires an extra round trip to the database to
+fetch the updated data, and re-rendering the entire page template may be
+less efficient than a partial page update on the client side.
+
+### Install development dependencies in a VSCode Dev Container
+
+If you use VSCode with Docker, the following VSCode Dev Container
+configuration will install all dependencies and automatically open the
+project in a container:
+
+``` json
+{
+    "name": "Python 3",
+    "image": "mcr.microsoft.com/devcontainers/python:1-3.12-bullseye",
+    "postCreateCommand": "sudo apt update && sudo apt install -y python3-dev libpq-dev graphviz && pipx install poetry && poetry install && poetry shell",
+    "features": {
+        "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {},
+        "ghcr.io/rocker-org/devcontainer-features/quarto-cli:1": {}
+    }
+}
+```
+
+Simply create a .devcontainer folder in the root of the project and add
+a devcontainer.json file with this content, and then “Reopen in
+Container” from View \> Command Palette.
+
+### Install development dependencies manually
 
 #### Python and Docker
 
@@ -30,8 +68,28 @@ brew install postgresql
 
 For Windows:
 
-- No additional system dependencies required
-- Install Python from the official Python website
+- No installation required
+
+#### Quarto CLI and Graphviz
+
+- [Quarto CLI](https://quarto.org/docs/get-started/)
+
+For macOS:
+
+``` bash
+brew install graphviz
+```
+
+For Ubuntu/Debian:
+
+``` bash
+sudo apt update && sudo apt install -y graphviz
+```
+
+For Windows:
+
+- Download and install from
+  [Graphviz.org](https://graphviz.org/download/#windows)
 
 #### Python dependencies
 
@@ -87,6 +145,10 @@ permissions/roles are created first.
 
 Navigate to http://localhost:8000/
 
+### Render the README
+
+`quarto render README.qmd`
+
 ### Contributing
 
 Fork the repository, create a new branch, make your changes, and submit

README.qmd

@@ -9,50 +9,128 @@ format: gfm
 
 This project is still under development.
 
-### Install development dependencies
+### Architecture
+
+This application uses a Post-Redirect-Get (PRG) pattern. The user submits a form, which sends a POST request to a FastAPI endpoint on the server. The database is updated, and the user is redirected to a GET endpoint, which fetches the updated data and re-renders the Jinja2 page template with the new data.
+
+``` {python}
+#| echo: false
+#| include: false
+from graphviz import Digraph
+
+dot = Digraph()
+
+dot.node('A', 'User submits form')
+dot.node('B', 'HTML/JS form validation')
+dot.node('C', 'Convert to Pydantic model')
+dot.node('D', 'Optional custom validation')
+dot.node('E', 'Update database')
+dot.node('F', 'Middleware error handler')
+dot.node('G', 'Render error template')
+dot.node('H', 'Redirect to GET endpoint')
+dot.node('I', 'Fetch updated data')
+dot.node('J', 'Re-render Jinja2 page template')
+
+dot.edge('A', 'B')
+dot.edge('B', 'A')
+dot.edge('B', 'C', label='POST Request to FastAPI endpoint')
+dot.edge('C', 'D')
+dot.edge('C', 'F', label='RequestValidationError')
+dot.edge('D', 'E', label='Valid data')
+dot.edge('D', 'F', label='Custom Validation Error')
+dot.edge('E', 'H', label='Data updated')
+dot.edge('H', 'I')
+dot.edge('I', 'J')
+dot.edge('F', 'G')
+
+dot.render('static/webapp_flow', format='png', cleanup=True)
+```
+
+![Webapp Flow](static/webapp_flow.png)
+
+The advantage of the PRG pattern is that it is very straightforward to implement and keeps most of the rendering logic on the server side. The disadvantage is that it requires an extra round trip to the database to fetch the updated data, and re-rendering the entire page template may be less efficient than a partial page update on the client side.
+
+### Install development dependencies in a VSCode Dev Container
+
+If you use VSCode with Docker to develop in a container, the following VSCode Dev Container configuration will install all dependencies:
+
+``` json
+{
+	"name": "Python 3",
+	"image": "mcr.microsoft.com/devcontainers/python:1-3.12-bullseye",
+	"postCreateCommand": "sudo apt update && sudo apt install -y python3-dev libpq-dev graphviz && pipx install poetry && poetry install && poetry shell",
+	"features": {
+		"ghcr.io/devcontainers/features/docker-outside-of-docker:1": {},
+		"ghcr.io/rocker-org/devcontainer-features/quarto-cli:1": {}
+	}
+}
+```
 
-#### Python, Docker, and Quarto CLI
+Simply create a `.devcontainer` folder in the root of the project and add a `devcontainer.json` file in the folder with the above content. VSCode may prompt you to install the Dev Container extension if you haven't already, and/or to open the project in a container. If not, you can manually select "Dev Containers: Reopen in Container" from View > Command Palette.
+
+### Install development dependencies manually
+
+#### Python and Docker
 
 - [Python 3.12 or higher](https://www.python.org/downloads/)
 - [Docker and Docker Compose](https://docs.docker.com/get-docker/)
-- [Quarto CLI](https://quarto.org/docs/get-started/)
 
 #### PostgreSQL headers
 
 For Ubuntu/Debian:
 
-```bash
+``` bash
 sudo apt update && sudo apt install -y python3-dev libpq-dev
 ```
 
 For macOS:
 
-```bash
+``` bash
 brew install postgresql
 ```
 
 For Windows:
 
-- No additional system dependencies required
-- Install Python from the official Python website
+- No installation required
+
+#### Quarto CLI and Graphviz
+
+- [Quarto CLI](https://quarto.org/docs/get-started/)
+
+
+For macOS:
+
+``` bash
+brew install graphviz
+```
+
+For Ubuntu/Debian:
+
+``` bash
+sudo apt update && sudo apt install -y graphviz
+```
+
+For Windows:
+
+- Download and install from [Graphviz.org](https://graphviz.org/download/#windows)
 
 #### Python dependencies
 
-1. Install Poetry
+1.  Install Poetry
 
-```bash
+``` bash
 pipx install poetry
 ```
 
-2. Install project dependencies
+2.  Install project dependencies
 
-```bash
+``` bash
 poetry install
 ```
 
-3. Activate shell
+3.  Activate shell
 
-```bash
+``` bash
 poetry shell
 ```
 
@@ -86,7 +164,11 @@ Navigate to http://localhost:8000/
 
 ### Render the README
 
-`quarto render README.qmd`
+When updating the documentation, remember to make changes in the README.qmd file, not the README.md file. Then run the following command to render the README.md file:
+
+``` bash
+quarto render README.qmd
+```
 
 ### Contributing