diff options
Diffstat (limited to '')
| -rw-r--r-- | docs/overview.rst | 124 |
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. |