From e8681d4bc58cbc9c492ed6398d6868bf249e42fe Mon Sep 17 00:00:00 2001
From: "Patrik J. Braun" <bpatrik@users.noreply.github.com>
Date: Sun, 9 May 2021 23:11:48 +0200
Subject: [PATCH] Update CONTRIBUTING.md

---
 CONTRIBUTING.md | 64 ++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 63 insertions(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e2a7362e..71903353 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -41,4 +41,66 @@ Source structure:
   |-- common -- shared files (mostly DTOs) between the frontend and the backend
   |-- frontend -- angular based frontend
 ```
-TODO...
+
+Backend structure:
+```
+|-- src -- contains the rource files <-------- This is what you need
+  |-- backend -- nodejs backend code
+    |-- middlewares -- contains the middlewares. These make minimal input validation and transforamtion
+    |-- model -- contains the business logic
+	  |-- database -- these return with the gallery related data
+	    |-- interfaces -- common, database independent inerfaces
+		|-- memory -- business logic for memory "database"
+		|-- sql  -- business logic for sql database
+	  |-- diagnostics -- contains the checks for the startup diagnostics (checks if all the settings are valid, all packeges are avaiale, image folder exists, etc.)
+      |-- fileprocessing -- photo and video converting code
+      |-- jobs -- code about job scheduling (crontab like feature)	  
+	  |-- threading -- code that runs on a separate threading
+	    |-- DiskManagerWorker.ts -- scans a direcory
+		|-- Metadataloader.ts -- parses a photo / video for metadata
+		|-- *Worker.ts -- queues and helper classes to convert video / photo, parse a directory
+	|-- routers -- contains the declarations of the HTTP Api endpoints
+	|-- index.ts -- here starts the Server up (callst server.ts)
+	|-- server.ts -- this is HTTP server startup code
+	|-- ProjectPath.ts -- singleton, contains the project related paths
+```
+## Case-study: Listing a directory
+
+Scenario: Web UI wants to show the `/demoDir` directory, usind SQL database with low reindexing severity.
+
+Client side:
+1. Navigating to `http://<domain>/demoDir` 
+2. URL changed: [gallery.component.ts]: `onRoute` triggered
+3. Calling: [gallery.component.ts]: `galleryService.loadDirectory('/demoDir')`
+4. Loding data from local_storage: [gallery.service.ts]: `galleryCacheService.getDirectory('/demoDir')`
+5. Make a call to backend if the content changed [gallery.service.ts]: `networkService.getJson<ContentWrapperWithError>('/gallery/content/' + '/testDir', params)`
+    * params contains last modification and last scanned date that is know from the local_storage cache
+
+Server side:
+
+6. Requests hits the server in [GalleryRouter.ts]: `protected static addDirectoryList(app: Express)`:
+https://github.com/bpatrik/pigallery2/blob/b79d62840c7496b5068d6af73f10d95b9ac48fdd/src/backend/routes/GalleryRouter.ts#L32-L46
+
+7. Authenticating user: [AuthenticationMWs.ts]: `AuthenticationMWs.authenticate`
+    * On fail return with error
+8. Normalizing `directory` path parameter (in this case `/testDir`): [AuthenticationMWs.ts]: `AuthenticationMWs.normalizePathParam('directory')`
+    * Makes sure that path does not go out of the allowed paths (gallery itself)
+9. Cheking if the path exists and the User has rights to access it: [AuthenticationMWs.ts]:`AuthenticationMWs.authorisePath('directory', true)`
+    * returns 403 if not accessable
+10. Injecting gallery version to the HTTP header: [VersionMWs.ts]:`VersionMWs.injectGalleryVersion`
+    * gallery version is a hash that represents the current gallery status (latest modified date, number of photos/videos, etc)
+11. Getting the content of `/testDir`   [GalleryMWs]: GalleryMWs.listDirectory
+    1. If the last modificatoin and scan date of `/testDir` equals with what the client have sent, returning empty result to the client (skipping the rest)
+    2. If last modification date is different from what the client knew, reindexing `/testDir`: `IndexingManager.indexDirectory(relativeDirectoryName)`
+        * Scans a directory, asyncronously saves it to DB, while directly retourns with raw results from `DiskManagerWorker.ts`
+    3. If Last scan heppened a while ago, reindex it asyncronously and return data from DB
+12. Attaching Thumbnails data to the photos/videos: [ThumbnailGeneratorMWs]: `ThumbnailGeneratorMWs.addThumbnailInformation`
+    * Checks if a photo already has a generated thumbnail image 
+13. Removes empty properties and circular dependencies: [GalleryMWs.ts]: `GalleryMWs.cleanUpGalleryResults`
+14. Rending http body and ending HTTP call: [RenderingMWs.ts]: `RenderingMWs.renderResult`
+
+Client side:
+
+15. Setting `content` BehaviorSubject (rxjs) with the `ContentWrapperWithError` from the server.
+16. Rendering gallery: UI is data binded to the `galleryService.content` [gallery.component.html]
+