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 `_ backend that exposes a `GraphQL `_ API and a `SvelteKit `_ frontend written in `TypeScript `_ that communicates with it. Data is stored in an `SQLite `_ database. Image processing is done using `Pillow `_. hircine uses the `BLAKE3 Python bindings `_ 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 `. .. _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 `_ 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.