Initial commit0.1.0

1 files changed, 124 insertions, 0 deletions

diff --git a/docs/overview.rst b/docs/overview.rst
new file mode 100644
index 0000000..8eb327f
--- /dev/null
+++ b/docs/overview.rst
@@ -0,0 +1,124 @@
+Overview
+========
+
+Before setting up **hircine** it is important to understand its choice of
+technologies as well as its design goals and core concepts. This will allow you
+to make an informed decision on whether or not it is the right solution for
+you.
+
+.. _overview-technologies:
+
+Technologies
+------------
+
+**hircine** consists of two core parts: a `Python <https://www.python.org>`_
+backend that exposes a `GraphQL <https://graphql.org>`_ API and a `SvelteKit
+<https://kit.svelte.dev>`_ frontend written in `TypeScript
+<https://www.typescriptlang.org>`_ that communicates with it. Data is stored in
+an `SQLite <https://www.sqlite.org/index.html>`_ database.
+
+Image processing is done using `Pillow
+<https://pillow.readthedocs.io/en/stable>`_. hircine uses the `BLAKE3 Python
+bindings <https://pypi.org/project/blake3>`_ to build hashes used for file
+identification and deduplication.
+
+The web application is designed to be the canonical user interface, but any
+program may freely use the :doc:`provided API </advanced/api>`.
+
+.. _overview-goals:
+
+Design goals
+------------
+
+**hircine** is designed to organize a large personal collection of comics and
+make it easily queryable. It provides a set of concepts and tools that allows
+categorization and classification of comics and comes with a powerful filtering
+system.
+
+Whilst **hircine** does have basic support for categories of metadata such as
+artists or characters, it is mostly concerned with classifying the *content* of
+a comic through user-defined namespaces and tags. The primary goal is to find
+something you are in the mood to read, and not to provide a full archival
+system where you keep track of the minute details of a comic's publication or
+creation.
+
+As such, it is designed to tackle large and diverse collections of comics,
+manga, or doujin where the story, art, and characters are the primary appeal.
+
+.. _overview-concepts:
+
+Core concepts
+-------------
+
+Archives
+^^^^^^^^
+
+**hircine** reads image files from *ZIP* archives. Loose image files are
+**not** supported. Usually an archive contains a single comic (or chapter), but
+it may also contain a whole volume - once imported, an archive can be split
+into multiple comics in the web application.
+
+Comics
+^^^^^^
+
+A comic is a logical grouping of pages (image files) that can be annotated with
+metadata. Most of the functionality in the web application pertains to
+organizing, querying, and reading comics.
+
+Comics are created by collating a sequence of pages from a single archive. This
+sequence is exclusive, meaning that a page may only ever be allocated to a
+single comic. Not all pages of an archive have to be used.
+
+Metadata
+^^^^^^^^
+
+A fair chunk of comic metadata is self-explanatory. For example, a comic may be
+annotated with the date of its publication, the language it is written in, or
+what kind of censorship is in use. There also exist a number of well-defined
+categories of metadata that are managed by the user:
+
++------------+-------------------------------------------------------------------------+
+| Category   | Description                                                             |
++============+=========================================================================+
+| Artists    | A person involved in the creating of a comic.                           |
++------------+-------------------------------------------------------------------------+
+| Circles    | A group of people involved in the publishing or translation of a comic. |
++------------+-------------------------------------------------------------------------+
+| Characters | A fictional character portrayed in a comic.                             |
++------------+-------------------------------------------------------------------------+
+| Worlds     | A fictional world portrayed in a comic.                                 |
++------------+-------------------------------------------------------------------------+
+
+.. _overview-tags:
+
+Namespaces & Tags
+^^^^^^^^^^^^^^^^^
+
+Alongside those well-defined categories, **hircine** supports user-defined
+namespaces and tags. The latter is a familiar concept: a tag is a simple piece
+of information that is attached to an object of interest.
+
+Namespaces enhance that concept by introducing a context in which the tag is
+placed. Let's say we want to keep track of the gender of a story's love
+interest. We may solve this using tags alone, like ``male love interest`` or
+``female love interest``, but this is quite unwieldy. Namespaces instead allow
+us to create a ``male`` and ``female`` namespace and a single tag ``love
+interest`` which can then be combined with either namespace.
+
+**hircine** requires the use of namespaces when tagging comics. A tag cannot be
+applied to a comic unless it is paired with a namespace. Such a pairing is
+called a *qualified tag*. When filtering, either the namespace or tag is
+optional: you may decide to exclude comics with any ``love interest``, or
+filter for comics that only have tags in the ``female`` namespace.
+
+.. _overview-object-store:
+
+Object store
+^^^^^^^^^^^^
+
+**hircine** keeps all processed images files in a a `content-addressable
+filesystem <https://en.wikipedia.org/wiki/Content-addressable_storage>`_ called
+the object store. The purpose of the store is twofold: Firstly, if multiple
+archives contain the same image, it only needs to be stored once in the object
+store. Secondly, the object store allows the application to used without having
+to serve potentially large image files.