Document database schema in the manual.

4 files changed, 196 insertions, 2 deletions

diff --git a/.guix/domagi-website.scm b/.guix/domagi-website.scm
index 83c785d..c924cab 100644
--- a/.guix/domagi-website.scm
+++ b/.guix/domagi-website.scm
@@ -17,6 +17,7 @@
 ;;; domagi. If not, see <https://www.gnu.org/licenses/>.
 
 (define-module (domagi-website)
+  #:use-module ((gnu packages diagram) #:select (pikchr))
   #:use-module ((gnu packages docbook) #:select (docbook-xsltng))
   #:use-module ((gnu packages fonts) #:select (font-charter font-fira-code))
   #:use-module ((gnu packages haskell-xyz) #:select (pandoc))
@@ -48,7 +49,30 @@
 (define domagi-web-manual-en-gexp
   (with-imported-modules '((guix build utils))
     #~(begin
-        (use-modules (guix build utils))
+        (use-modules (guix build utils)
+                     (ice-9 popen)
+                     (srfi srfi-26)
+                     (rnrs io ports))
+
+        (define (call-with-input-pipe command proc)
+          (let ((port #f))
+            (dynamic-wind
+              (lambda ()
+                (set! port (apply open-pipe* OPEN_READ command)))
+              (cut proc port)
+              (lambda ()
+                (unless (zero? (close-pipe port))
+                  (error "Command invocation failed" command))))))
+
+        (define (pikchr source svg)
+          (mkdir-p (dirname svg))
+          (call-with-output-file svg
+            (cut display
+                 (call-with-input-pipe (list #$(file-append pikchr "/bin/pikchr")
+                                             "--svg-only"
+                                             source)
+                   get-string-all)
+                 <>)))
 
         (setenv "HOME" "/tmp")
         (set-path-environment-variable
@@ -65,11 +89,17 @@
                           (string-append (getcwd) "/doc"))
         (invoke #$(file-append python "/bin/python3")
                 (string-append #$(package-source domagi) "/extractdoc.py"))
+        (chdir "doc")
+        (pikchr "er.pic"
+                (string-append #$output "/media/er.svg"))
+        (pikchr "schema.pic"
+                (string-append #$output "/media/schema.svg"))
         (invoke #$(file-append docbook-xsltng "/bin/docbook")
                 (string-append "--resources:" #$output)
                 "-xi:on"
                 "resource-base-uri=/domagi/manual/"
-                "-s:doc/domagi.dbk"
+                "mediaobject-output-base-uri=/domagi/manual/media/"
+                "-s:domagi.dbk"
                 (string-append "-o:" #$output "/dev/en/index.html")))))
 
 (define-public domagi-website
diff --git a/doc/domagi.dbk b/doc/domagi.dbk
index 0888ac1..f2ef70d 100644
--- a/doc/domagi.dbk
+++ b/doc/domagi.dbk
@@ -5,6 +5,45 @@
   <title>domagi manual</title>
   <copyright><year>2026</year><holder>Arun Isaac</holder></copyright>
 </info>
+<chapter>
+  <title>Database Schema</title>
+  <para>domagi uses a SQL schema with the following four tables to represent a pangenome.</para>
+  <variablelist>
+    <varlistentry>
+      <term>segment</term>
+      <listitem><para>entity representing pangenome segments</para></listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>link</term>
+      <listitem><para>many-to-many relation between segments representing pangenome links</para></listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>path</term>
+      <listitem><para>entity representing pangenome paths</para></listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>path_segment</term>
+      <listitem><para>many-to-many relation mapping paths to segments associating them with the path at a certain coordinate</para></listitem>
+    </varlistentry>
+  </variablelist>
+  <para>The schema and the entity relationship diagram are visualized in <xref linkend="schema" /> and <xref linkend="er" /> respectively.</para>
+  <figure xml:id="schema">
+    <title>domagi database schema</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="schema.svg" scale="80" />
+      </imageobject>
+    </mediaobject>
+  </figure>
+  <figure xml:id="er">
+    <title>domagi entity relationship diagram in Chen's notation</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="er.svg" scale="90" />
+      </imageobject>
+    </mediaobject>
+  </figure>
+</chapter>
 <reference>
   <title>Reference</title>
   <xi:include href="domagi-build.dbk" />
diff --git a/doc/er.pic b/doc/er.pic
new file mode 100644
index 0000000..211126a
--- /dev/null
+++ b/doc/er.pic
@@ -0,0 +1,80 @@
+### domagi --- DuckDB-powered pangenome Swiss Army knife
+### Copyright © 2026 Arun Isaac <arunisaac@systemreboot.net>
+###
+### This file is part of domagi.
+###
+### domagi is free software: you can redistribute it and/or modify it under the
+### terms of the GNU General Public License as published by the Free Software
+### Foundation, either version 3 of the License, or (at your option) any later
+### version.
+###
+### domagi is distributed in the hope that it will be useful, but WITHOUT ANY
+### WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+### FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
+### details.
+###
+### You should have received a copy of the GNU General Public License along with
+### domagi. If not, see <https://www.gnu.org/licenses/>.
+
+down
+SegmentId: ellipse "id" italic fill lightgrey
+move 0.5cm
+SegmentName: ellipse "name" fill lightgrey
+move 0.5cm
+SegmentSequence: ellipse "sequence" fill lightgrey
+
+line from SegmentId.e \
+     right 1cm \
+     then down until even with SegmentSequence \
+     then to SegmentSequence.e
+line from SegmentName.e right 2cm
+
+Segment: box "segment" fill mediumslateblue
+line "n" above
+IsIn: diamond "is in" fill coral
+line "n" above thick
+Path: box "path" fill mediumslateblue
+down
+
+line; line right 1cm
+ellipse "id" italic fill lightgrey
+down
+move 0.5cm
+PathName: ellipse "name" fill lightgrey
+line from Path.s \
+     down until even with PathName \
+     then to PathName.w
+
+line from IsIn.s \
+     down \
+     then left
+ellipse "orientation" fill lightgrey width 125%
+down
+move 0.5cm
+IsInStart: ellipse "start" fill lightgrey
+move 0.5cm
+IsInEnd: ellipse "end" fill lightgrey
+line from IsIn.s \
+down until even with IsInStart \
+then to IsInStart.e
+line from IsIn.s \
+down until even with IsInEnd \
+then to IsInEnd.e
+
+move from Segment.n up
+Links: diamond "links" fill coral
+right
+move; move
+ToOrientation: ellipse "to-orientation" fill lightgrey width 175%
+up
+move 0.5cm
+FromOrientation: ellipse "from-orientation" fill lightgrey width 175%
+line from Links.e to ToOrientation.w
+line from FromOrientation.w \
+left 1cm \
+then down until even with ToOrientation
+
+# The space in "n " and " n" is a slight trick to nudge the labels a
+# little.
+line from Links.sw down until even with Segment.n "n " rjust
+line from Links.se down until even with Segment.n " n" ljust
\ No newline at end of file
diff --git a/doc/schema.pic b/doc/schema.pic
new file mode 100644
index 0000000..cdf816c
--- /dev/null
+++ b/doc/schema.pic
@@ -0,0 +1,45 @@
+### domagi --- DuckDB-powered pangenome Swiss Army knife
+### Copyright © 2026 Arun Isaac <arunisaac@systemreboot.net>
+###
+### This file is part of domagi.
+###
+### domagi is free software: you can redistribute it and/or modify it under the
+### terms of the GNU General Public License as published by the Free Software
+### Foundation, either version 3 of the License, or (at your option) any later
+### version.
+###
+### domagi is distributed in the hope that it will be useful, but WITHOUT ANY
+### WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+### FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
+### details.
+###
+### You should have received a copy of the GNU General Public License along with
+### domagi. If not, see <https://www.gnu.org/licenses/>.
+
+down
+Segment: box "segment" fill lightgrey
+SegmentId: box "id"
+box "name"
+box "sequence"
+
+Link: box "link" at 8cm right of Segment width 175% fill lightgrey
+LinkFromSegment: box "from_segment" width 175%
+box "from_orientation" width 175%
+LinkToSegment: box "to_segment" width 175%
+box "to_orientation" width 175%
+
+Path: box "path" at 8cm below Segment fill lightgrey
+PathId: box "id"
+box "name"
+
+box "path_segment" at 8cm right of Path width 200% fill lightgrey
+PathSegmentPathId: box "path_id" width 200%
+PathSegmentSegmentId: box "segment_id" width 200%
+box "segment_orientation" width 200%
+box "start" width 200%
+box "end" width 200%
+
+arrow from SegmentId.e to LinkFromSegment.w
+arrow from SegmentId.e to LinkToSegment.w
+arrow from SegmentId.e to PathSegmentSegmentId.w
+arrow from PathId.e to PathSegmentPathId.w
\ No newline at end of file