Resequenced docs pages and used color coding and subgraphs to make architecture graphs look really nice

Author: chriscarrollsmith

_quarto.yml

@@ -10,10 +10,10 @@ website:
         text: Home
       - href: docs/architecture.qmd
         text: Architecture
-      - href: docs/installation.qmd
-        text: Installation
       - href: docs/authentication.qmd
         text: Authentication
+      - href: docs/installation.qmd
+        text: Installation
       - href: docs/customization.qmd
         text: Customization
       - href: docs/deployment.qmd

docs/architecture.qmd

@@ -12,18 +12,34 @@ This application uses a Post-Redirect-Get (PRG) pattern. The user submits a form
 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.attr(rankdir='TB')
+dot.attr('node', shape='box', style='rounded')
+
+# Create client subgraph at top
+with dot.subgraph(name='cluster_client') as client:
+    client.attr(label='Client')
+    client.attr(rank='topmost')
+    client.node('A', 'User submits form', fillcolor='lightblue', style='rounded,filled')
+    client.node('B', 'HTML/JS form validation', fillcolor='lightblue', style='rounded,filled')
+
+# Create server subgraph below
+with dot.subgraph(name='cluster_server') as server:
+    server.attr(label='Server')
+    server.node('C', 'Convert to Pydantic model', fillcolor='lightgreen', style='rounded,filled')
+    server.node('D', 'Optional custom validation', fillcolor='lightgreen', style='rounded,filled')
+    server.node('E', 'Update database', fillcolor='lightgreen', style='rounded,filled')
+    server.node('F', 'Middleware error handler', fillcolor='lightgreen', style='rounded,filled')
+    server.node('G', 'Render error template', fillcolor='lightgreen', style='rounded,filled')
+    server.node('H', 'Redirect to GET endpoint', fillcolor='lightgreen', style='rounded,filled')
+    server.node('I', 'Fetch updated data', fillcolor='lightgreen', style='rounded,filled')
+    server.node('K', 'Re-render Jinja2 page template', fillcolor='lightgreen', style='rounded,filled')
+
+with dot.subgraph(name='cluster_client_post') as client_post:
+    client_post.attr(label='Client')
+    client_post.attr(rank='bottommost')
+    client_post.node('J', 'Display rendered page', fillcolor='lightblue', style='rounded,filled')
+
+# Add visible edges
 dot.edge('A', 'B')
 dot.edge('B', 'A')
 dot.edge('B', 'C', label='POST Request to FastAPI endpoint')
@@ -33,12 +49,14 @@ 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('I', 'K')
+dot.edge('K', 'J', label='Return HTML')
 dot.edge('F', 'G')
+dot.edge('G', 'J', label='Return HTML')
 
-dot.render('static/webapp_flow', format='png', cleanup=True)
+dot.render('static/data_flow', format='png', cleanup=True)
 ```
 
-![Data flow diagram](static/webapp_flow.png)
+![Data flow diagram](static/data_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.

docs/authentication.qmd

@@ -47,25 +47,25 @@ auth.attr('node', shape='box', style='rounded')
 # Client-side nodes
 with auth.subgraph(name='cluster_client') as client:
     client.attr(label='Client')
-    client.node('register_form', 'Submit registration')
-    client.node('login_form', 'Submit login')
-    client.node('store_cookies', 'Store secure cookies')
+    client.node('register_form', 'Submit registration', fillcolor='lightblue', style='rounded,filled')
+    client.node('login_form', 'Submit login', fillcolor='lightblue', style='rounded,filled')
+    client.node('store_cookies', 'Store secure cookies', fillcolor='lightblue', style='rounded,filled')
 
 # Server-side nodes
 with auth.subgraph(name='cluster_server') as server:
     server.attr(label='Server')
     # Registration path
-    server.node('validate_register', 'Validate registration data')
-    server.node('hash_new', 'Hash new password')
-    server.node('store_user', 'Store user in database')
+    server.node('validate_register', 'Validate registration data', fillcolor='lightgreen', style='rounded,filled')
+    server.node('hash_new', 'Hash new password', fillcolor='lightgreen', style='rounded,filled')
+    server.node('store_user', 'Store user in database', fillcolor='lightgreen', style='rounded,filled')
     
     # Login path
-    server.node('validate_login', 'Validate login data')
-    server.node('verify_password', 'Verify password hash')
-    server.node('fetch_user', 'Fetch user from database')
+    server.node('validate_login', 'Validate login data', fillcolor='lightgreen', style='rounded,filled')
+    server.node('verify_password', 'Verify password hash', fillcolor='lightgreen', style='rounded,filled')
+    server.node('fetch_user', 'Fetch user from database', fillcolor='lightgreen', style='rounded,filled')
     
     # Common path
-    server.node('generate_tokens', 'Generate JWT tokens')
+    server.node('generate_tokens', 'Generate JWT tokens', fillcolor='lightgreen', style='rounded,filled')
 
 # Registration path
 auth.edge('register_form', 'validate_register', 'POST /register')
@@ -99,17 +99,17 @@ reset = Digraph(name='reset_flow')
 reset.attr(rankdir='TB')
 reset.attr('node', shape='box', style='rounded')
 
-# Client-side nodes
-reset.node('forgot', 'User submits forgot password form')
-reset.node('reset', 'User submits reset password form')
-reset.node('email_client', 'User clicks reset link')
-
-# Server-side nodes
-reset.node('validate', 'Validation')
-reset.node('token_gen', 'Generate reset token')
-reset.node('hash', 'Hash password')
-reset.node('email_server', 'Send email with Resend')
-reset.node('db', 'Database', shape='cylinder')
+# Client-side nodes - using light blue fill
+reset.node('forgot', 'User submits forgot password form', fillcolor='lightblue', style='rounded,filled')
+reset.node('reset', 'User submits reset password form', fillcolor='lightblue', style='rounded,filled')
+reset.node('email_client', 'User clicks reset link', fillcolor='lightblue', style='rounded,filled')
+
+# Server-side nodes - using light green fill
+reset.node('validate', 'Validation', fillcolor='lightgreen', style='rounded,filled')
+reset.node('token_gen', 'Generate reset token', fillcolor='lightgreen', style='rounded,filled')
+reset.node('hash', 'Hash password', fillcolor='lightgreen', style='rounded,filled')
+reset.node('email_server', 'Send email with Resend', fillcolor='lightgreen', style='rounded,filled')
+reset.node('db', 'Database', shape='cylinder', fillcolor='lightgreen', style='filled')
 
 # Add edges with labels
 reset.edge('forgot', 'token_gen', 'POST')