2 files changed, 472 insertions, 0 deletions

diff --git a/devdoc/design-notes.md b/devdoc/design-notes.md
new file mode 100644
index 0000000..b6ea37a
--- /dev/null
+++ b/devdoc/design-notes.md
@@ -0,0 +1,305 @@
+---
+title: ldgallery design notes
+author: pacien
+date: 2020-02-25
+---
+
+__Warning: this document is severely outdated.__
+
+---
+
+# ldgallery design notes
+
+_ldgallery_ consists of two main components that are packaged and distributed
+together, but are otherwise functionally independent:
+
+* a __compiler__ which turns a collection of pictures and sidecar metadata
+  files into their compressed/normalised and aggregated versions respectively,
+  and
+* a web __viewer__ in the form of a single-page application, rendering the
+  output of the compiler as a searchable picture gallery.
+
+
+## Gallery compiler
+
+### Input
+
+#### Directory structure
+
+The compiler takes a source directory as input which shall contain item
+resource files and associated metadata sidecar files.  Those items may be
+recursively grouped into multiple levels of sub-directories.
+
+Example source directory structure:
+
+```
+example-gallery-source
+├── _DSC8808-1.jpg           -- a picture
+├── _DSC8808-1.jpg.yaml      -- its associated sidecar metadata file
+└── Glacier 3000             -- a directory grouping gallery items
+    ├── thumbnail.jpg        -- optional directory thumbnail
+    ├── _DSC5475.jpg
+    ├── _DSC5475.jpg.yaml
+    ├── _DSC5542.jpg
+    └── _DSC5542.jpg.yaml
+```
+
+
+#### Metadata sidecar file
+
+Metadata associated to items are stored in YAML sidecar files of the same name,
+with the `.yaml` extension appended.  The use of plain text sidecar files allow
+for easier editing without any special tool in a unified manner for multiple
+types of files (pictures, videos, ebooks, ...).  The metadata contained within
+item files are simply ignored.
+
+Tags are given with a group hierarchy separated by `.`, which allows generic
+searches as well as implicit disambiguation.
+
+Example metadata sidecar file:
+
+```yaml
+title: Some title
+
+date: 2019-12-20T16:51:52+00:00
+
+description: >
+  Some multiline description
+  that may contain some markdown later.
+
+tags:
+  - photographer.someone
+  - location.france.paris
+  - monochromatic
+```
+
+Possible evolutions:
+
+* Fallback values may later be defined for each field, making them optional.
+* The description field could be allowed to contain markdown-formatted content,
+  which would be rendered by the __viewer__ app.
+* Other keys could be added to allow the definition of specific
+  transform/compilation/displaying parameters on a particular file.
+* Metadata sidecar files could be added for directories as well in some
+  `index.yaml` file.
+
+
+#### Gallery configuration file
+
+The gallery YAML configuration file contains the __compiler__'s and the
+__viewer__'s settings in two different sections.
+
+Proposed configuration file, named `gallery.yaml` at the root of the source
+directory:
+
+```yaml
+compiler:
+  galleryName: My Little Gallery
+  ignoreFiles: .*\.txt # to ignore text files
+  implicitDirectoryTag: false # default
+
+  thumbnailMaxResolution:
+    width: 400  # default
+    height: 400 # default
+
+  pictureMaxResolution: # or unspecified to copy files as is
+    width: 1024
+    height: 768
+
+  # format normalisation?
+  # item compression?
+
+
+viewer:
+  # TODO: configuration options to be defined
+  # separately shown tags and their colours
+  # use hash in URL (useful for use without webserver url rewrite)?
+```
+
+
+### Output
+
+#### Directory structure
+
+```
+data
+├── items                  -- original/normalised item directory
+│   ├── _DSC8808-1.jpg
+│   └── Glacier 3000
+│       ├── _DSC5475.jpg
+│       └── _DSC5542.jpg
+├── thumbnails             -- item thumbnails directory
+│   ├── _DSC8808-1.jpg
+│   └── Glacier 3000
+│       ├── thumbnail.jpg
+│       ├── _DSC5475.jpg
+│       └── _DSC5542.jpg
+├── index.json             -- content index file
+└── viewer.json            -- viewer configuration file
+```
+
+
+#### Viewer configuration file
+
+The content of the `viewer` section of the gallery configuration file is used,
+without any transformation by the __compiler__, to generate the `viewer.json`
+file located at the root of the output directory.
+
+
+#### Gallery items index
+
+The __compiler__ generates a global index file `index.json` aggregating the
+metadata of all the source sidecar files as a tree of items as described below.
+Its root node is a directory item.  The type of each property node is marked by
+its `type` field.
+
+Directory items aggregate their tags from the items below it in order to be
+displayed in search results.
+
+Resource paths are rooted with respect to the data output directory which
+serves as the base path.
+
+Serialised item structure:
+
+```json
+{
+  "_comment": "common fields",
+
+  "title": "Some title",
+  "date": "2019-12-20T16:51:52+00:00",
+  "description": "Some multiline description\nthat may contain some markdown later.",
+
+  "tags": [
+    "photographer.someone",
+    "location.france.paris",
+    "monochromatic"
+  ],
+
+  "path": "[resource path]",
+
+  "thumbnail": null | {
+    "resource": "[resource path]",
+    "resolution": {
+      "width": 400,
+      "height": 200
+    }
+  },
+
+
+  "_comment": "type-dependent",
+
+  "properties": {
+    "type": "picture",
+    "resource": "[resource url]"
+  },
+
+  "properties": {
+    "type": "other",
+    "resource": "[resource url]"
+  },
+
+  "properties": {
+    "type": "directory",
+    "items": [ { "_comment": "item objects..." } ]
+  }
+}
+```
+
+
+#### Normalised items and thumbnails
+
+Gallery items are normalised and made available in the `items` sub-directory of
+the data output directory.  Normalisation consists of optional transcoding and
+other transforms as configured by the user in the compiler part of the
+`gallery.yaml` configuration file.
+
+Thumbnails are also generated for those items and are placed in the
+`thumbnails` sub-directory.  Thumbnails of pictures in particular are resized
+using ~~Lanczos~~ (not available) bilinear resampling.  Directory thumbnails
+may later be generated by picking or assembling one or multiple of its items,
+or defined explicitely by the user.
+
+The structure of the input directory is kept in both those output
+sub-directories.  Input item files and directories also keep their original
+names.
+
+
+## Gallery viewer
+
+The __viewer__ is a single-page web application which displays the gallery's
+content.
+
+It runs fully on the client's side and remains usable without any back-end.  It
+renders the compiled resources from the `data` directory, placed at its root,
+generated by the __compiler__.
+
+
+### URL anchor
+
+The page anchor is updated and used by the application to reflect the state of
+its current state in such a way that any view can be shared and loaded back by
+copying the URL and its anchor.  It should in particular contain the current
+directory or item, as well as the filtering query.
+
+
+### Directory/collection/grid view
+
+The application starts by showing a grid view of the root directory of the
+gallery.
+
+This combined view offers the possiblity to the user to navigate to other items
+and to search recursively through the current directory.
+
+