From 3d25eeb1b0e91a0a3e2ba25634b1b69f87a1c031 Mon Sep 17 00:00:00 2001
From: Yashu-svg <dashingyash07@gmail.com>
Date: Mon, 17 Aug 2026 20:23:55 +0530
Subject: [PATCH 1/3] docs: add backend API architecture diagram

---
 docs/backend/backend_python/api.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/docs/backend/backend_python/api.md b/docs/backend/backend_python/api.md
index 517945412..d32a0d0eb 100644
--- a/docs/backend/backend_python/api.md
+++ b/docs/backend/backend_python/api.md
@@ -1,7 +1,21 @@
 <!-- This page is a Swagger UI embed, not prose. The mkdocs swagger-ui-tag plugin requires the <swagger-ui> HTML element; the wrapper div and script scope page-specific CSS. The page title comes from the MkDocs nav config, so no top-level heading is needed here. -->
 <!-- markdownlint-disable MD033 MD041 MD010 -->
 <!-- # API Reference -->
+## Backend API Architecture
 
+PictoPy's Python backend exposes its HTTP API through FastAPI. Requests are routed from the application entry point to the corresponding route module, which interacts with the database and utility layers before returning a Pydantic response model.
+
+```mermaid
+flowchart TD
+    A[Client] -->|HTTP Request| B[FastAPI Application]
+    B --> C[API Router]
+    C --> D[Route Handler]
+    D --> E[Database Layer]
+    D --> F[Utility Layer]
+    E --> G[(SQLite Database)]
+    D --> H[Pydantic Response Model]
+    H -->|JSON Response| A
+```
 <div class="api-500-wrapper">
 	<swagger-ui src="openapi.json"/>
 </div>

From 963fa95244b4f8eaa60d37445261d75d01c78f46 Mon Sep 17 00:00:00 2001
From: Yashu-svg <dashingyash07@gmail.com>
Date: Wed, 19 Aug 2026 00:29:38 +0530
Subject: [PATCH 2/3] docs: document image retrieval API flow

---
 docs/backend/backend_python/api.md | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/docs/backend/backend_python/api.md b/docs/backend/backend_python/api.md
index d32a0d0eb..d4e828924 100644
--- a/docs/backend/backend_python/api.md
+++ b/docs/backend/backend_python/api.md
@@ -16,6 +16,25 @@ flowchart TD
     D --> H[Pydantic Response Model]
     H -->|JSON Response| A
 ```
+## Image Retrieval API Flow
+
+The `GET /images/` endpoint provides a concrete example of the backend request/response flow. The request is routed to `get_all_images()`, which retrieves image records through `db_get_all_images()`. The database layer retrieves image and tag data from SQLite, while image metadata is parsed before the results are converted into the response model.
+
+```mermaid
+flowchart TD
+    A[Client] -->|GET /images/| B[FastAPI Application]
+    B --> C[Images Router]
+    C --> D[get_all_images]
+    D -->|tagged filter| E[db_get_all_images]
+    E --> F[(SQLite Database)]
+    F -->|Images + Tags| E
+    E --> D
+    D --> G[image_util_parse_metadata]
+    G --> D
+    D --> H[ImageData]
+    H --> I[GetAllImagesResponse]
+    I -->|JSON Response| A
+```
 <div class="api-500-wrapper">
 	<swagger-ui src="openapi.json"/>
 </div>

From e405e413d2f4b405c8ed85cdf23165d908c1b7b9 Mon Sep 17 00:00:00 2001
From: Yashu-svg <dashingyash07@gmail.com>
Date: Wed, 19 Aug 2026 01:39:17 +0530
Subject: [PATCH 3/3] docs: clarify image retrieval API flow

---
 docs/backend/backend_python/api.md | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/docs/backend/backend_python/api.md b/docs/backend/backend_python/api.md
index d4e828924..7fd8b2776 100644
--- a/docs/backend/backend_python/api.md
+++ b/docs/backend/backend_python/api.md
@@ -18,7 +18,7 @@ flowchart TD
 ```
 ## Image Retrieval API Flow
 
-The `GET /images/` endpoint provides a concrete example of the backend request/response flow. The request is routed to `get_all_images()`, which retrieves image records through `db_get_all_images()`. The database layer retrieves image and tag data from SQLite, while image metadata is parsed before the results are converted into the response model.
+The `GET /images/` endpoint provides a concrete example of the backend request/response flow. The request is routed to `get_all_images()`, which retrieves image records through `db_get_all_images()`. The database layer retrieves image and tag data from SQLite and parses stored metadata. `get_all_images()` invokes `image_util_parse_metadata()` again while constructing each `ImageData` item before returning the response model.
 
 ```mermaid
 flowchart TD
@@ -28,10 +28,11 @@ flowchart TD
     D -->|tagged filter| E[db_get_all_images]
     E --> F[(SQLite Database)]
     F -->|Images + Tags| E
+    E --> G1[image_util_parse_metadata]
+    G1 --> E
     E --> D
-    D --> G[image_util_parse_metadata]
-    G --> D
-    D --> H[ImageData]
+    D --> G2[image_util_parse_metadata]
+    G2 --> H[ImageData]
     H --> I[GetAllImagesResponse]
     I -->|JSON Response| A
 ```