doc/architecture.rst

   1 Architecture overview
   2 =====================
   3
   4 Catalogue of books
   5 ------------------
   6
   7 Books are kept in the :py:class:`catalogue.models.Book` model.
   8
   9 Books have fragments, annotated  with themes. Those are kept in the
  10 :py:class:`catalogue.models.Fragment` model.
  11
  12 Both ``Books`` and ``Fragments`` can have ``Tags``, which are
  13 :py:class:`catalogue.models.Tag` objects.
  14
  15 What are ``Tags`` used for?
  16 ---------------------------
  17
  18 Each ``Tag`` objects has a ``category`` field specyfying its meaning.
  19 The categories are enumerated in :py:const:`catalogue.models.tag.TAG_CATEGORIES`.
  20
  21 Tags are used for:
  22
  23 * Keeping browsable metadata. Each ``Book`` can have any number of tags
  24   of categories: ``author``, ``epoch``, ``kind``, ``genre``.
  25   Each ``Fragment`` of a book has all of those,
  26   and also a number of ``theme`` tags.
  27 * User shelves. A User can put a ``Book`` on a shelf and add some labels
  28   by adding a number of ``set`` tags to it. A book put on a shelf without
  29   any labels has a Tag with an empty name.
  30
  31
  32 .. _ancestor-descendant-relations:
  33
  34 Relations between ``Books``, ``Fragments`` and other ``Books``
  35 --------------------------------------------------------------
  36
  37 Obviously, every ``Fragment`` comes from a particular ``Book``. This
  38 relation is expressed with the Fragment's ``book`` field.
  39
  40 The source of parent-child relations between ``Books`` is
  41 the ``dc:relation.hasPart`` metadata field, exposed by
  42 :py:class:`librarian.dcparser.BookInfo` as ``parts``. This relation
  43 and the order of children of one parent is expressed with the child
  44 book's ``parent`` and ``parent_number`` fields.
  45
  46 Additionally, every ``Book`` has a many-to-many relationship `ancestor`,
  47 onnecting it to all its ancestors, with reverse relationship called
  48 `descendant`.  This relationship is rebuilt after a `Book` is published.