Document database schema in the manual.

3 files changed, 164 insertions, 0 deletions

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