docs: sequence diagram for execution flow and ERD for schema

[ParticularlyPythonicBS]

Adds a sequence diagram documenting temoa execution flow and an entity relationship diagram for temoa v4 schema.

Adds sphinx contrib mermaid plugin as an optional docs dependency.

ERD was generated using: uvx "eralchemy[graphviz]" -i sqlite:///data_files/example_dbs/utopia.sqlite -o erd.md -m mermaid_er

Summary by CodeRabbit

Release Notes

• Documentation

  • Added execution flow diagram and pipeline details to documentation.
  • Enhanced database documentation with visual entity-relationship diagram.
  • Expanded quick start guide with database schema examples and SQL snippets.

• Chores

  • Added Mermaid visualization support for improved documentation graphics.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

This pull request adds Mermaid diagram support to the Temoa documentation infrastructure. Changes include configuring the Sphinx build system with the sphinxcontrib.mermaid extension, adding database schema and execution flow diagrams, and updating project dependencies. All modifications are documentation and configuration focused with no runtime code changes.

Changes

Cohort / File(s)	Summary
Sphinx Configuration docs/source/conf.py	Added sphinxcontrib.mermaid extension and configured Mermaid rendering options (myst_enable_extensions, mermaid_d3_zoom, mermaid_fullscreen, mermaid_include_elk, mermaid_include_mindmap)
Dependency Updates pyproject.toml, requirements-dev.txt	Added sphinxcontrib-mermaid (v1.2.3+) to docs extras and development requirements
Documentation Content docs/source/computational_implementation.rst	Added "Execution Flow" section with Mermaid sequence diagram detailing the Temoa pipeline (CLI entry, environment setup, sequencing, data loading, model construction, solving, result processing)
Database Documentation docs/source/database_schema.mmd	Added comprehensive Mermaid entity-relationship diagram defining database tables, fields, primary keys, and relationships across capacity, cost, demand, emissions, and operational constructs
Quick Start Guide docs/source/quick_start.rst	Updated Database Construction section with ER diagram reference, clarified foreign key relationships, and added SQL snippet example for time\_period table

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• Update preface and quick start guide #241: Overlaps with documentation edits to quick_start.rst and other documentation files.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: sequence diagram for execution flow and ERD for schema' directly and accurately summarizes the main changes: adding a sequence diagram for execution flow and an entity-relationship diagram for the schema.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In @docs/source/conf.py:
- Around line 150-153: Remove the two unnecessary Mermaid feature flags from the
config: delete mermaid_include_mindmap (redundant in modern Mermaid ≥9.4) and,
unless you actually need ELK layouts elsewhere, remove mermaid_include_elk to
avoid pulling the ~1MB ELK dependency; keep mermaid_d3_zoom and
mermaid_fullscreen as-is to preserve UX improvements. Ensure only
mermaid_d3_zoom and mermaid_fullscreen remain in the conf.py configuration block
and run a quick docs build to confirm no references to ELK or mindmap options
remain.

In @docs/source/database_schema.mmd:
- Around line 1-875: The ER diagram is very large (84 entities/197
relationships) and should be split into smaller, focused diagrams to improve
maintainability; create multiple mermaid diagrams (e.g., "core structure"
covering core tables like technology, time_period, region, capacity_credit;
"costs" covering cost_fixed, cost_variable, cost_invest, cost_emission;
"emissions" covering emission_activity, emission_embodied, emission_end_of_life;
"outputs" covering output_flow_in, output_flow_out, output_storage_level,
output_cost) by moving subsets of entity blocks and their relationships into
separate diagram sections or files, preserve the existing mermaid settings
(mermaid_include_elk, mermaid_d3_zoom, mermaid_fullscreen) for each diagram, and
update any documentation index or navigation so readers can open the focused
views instead of one monolithic diagram.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 39c85fe and ca0cc4f.

⛔ Files ignored due to path filters (1)

• uv.lock is excluded by !**/*.lock

📒 Files selected for processing (6)

• docs/source/computational_implementation.rst
• docs/source/conf.py
• docs/source/database_schema.mmd
• docs/source/quick_start.rst
• pyproject.toml
• requirements-dev.txt

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)

• GitHub Check: setup and test (windows-latest, 3.12)
• GitHub Check: setup and test (windows-latest, 3.13)
• GitHub Check: setup and test (macos-latest, 3.12)
• GitHub Check: setup and test (macos-latest, 3.13)

🔇 Additional comments (6)

requirements-dev.txt (1)

144-144: LGTM! Auto-generated dependency entries are correct.

The sphinxcontrib-mermaid entries in this auto-generated requirements file correctly reflect the dependency added to pyproject.toml, with appropriate pinning for reproducibility.

Also applies to: 175-175, 192-193

docs/source/quick_start.rst (1)

124-141: LGTM! Clean integration of the ER diagram into the Quick Start guide.

The addition of the ER diagram reference is well-placed in the Database Construction section and includes appropriate alt text for accessibility. The diagram provides valuable context for understanding the database structure.

Note: The effectiveness of this addition depends on the ER diagram (database_schema.mmd) rendering correctly. Please ensure the diagram is tested as part of the documentation build process.

docs/source/computational_implementation.rst (1)

334-413: Well-structured execution flow documentation with proper Mermaid support.

The new Execution Flow section effectively documents the Temoa execution pipeline. The Mermaid sequence diagram is well-organized with clear color-coded phases, includes appropriate alt text for accessibility, and is followed by a clear narrative explanation of the seven execution stages.

The docs/source/conf.py file already includes the sphinxcontrib.mermaid extension in the extensions list and is properly configured with additional Mermaid settings (zoom, fullscreen, ELK, and mindmap support enabled), ensuring the diagrams will render correctly when the documentation is built.

pyproject.toml (1)

60-60: No action needed. Version 1.2.3 is the current latest release of sphinxcontrib-mermaid (as of 2025) and is compatible with Sphinx 7.4.7+.

docs/source/conf.py (2)

147-148: LGTM! MyST parser correctly configured for Mermaid.

The MyST parser configuration correctly enables Mermaid diagrams in markdown files. The myst_fence_as_directive setting allows ```mermaid code blocks to be processed as Mermaid directives, and the enabled extensions support math rendering and other markdown features.

---

63-63: Dependency correctly declared.

The sphinxcontrib-mermaid>=1.2.3 dependency is already declared in pyproject.toml (line 60), so the extension addition at line 63 is properly supported.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Description: Find all mermaid diagram types used in documentation

# Search for mermaid code blocks and extract diagram types
rg -A 1 '```mermaid' docs/ -t md -t rst | rg -oP '^\s*(sequenceDiagram|erDiagram|flowchart|graph|classDiagram|stateDiagram|gantt|pie|journey|gitGraph|mindmap|timeline|quadrantChart|requirementDiagram|C4Context)' | sort | uniq -c

Repository: TemoaProject/temoa

Length of output: 180

---

🌐 Web query:

Mermaid ELK layout engine diagram types requirements

💡 Result:

Summary — what ELK provides for Mermaid, which diagrams it helps, and requirements to use it:

• What it is / diagram types helped:

  • ELK is an alternative layout engine (Eclipse Layout Kernel) that produces better layouts for complex/denser graphs (layered, hierarchical, multi-root trees, force/stress layouts) used by Mermaid flowcharts/graph-style diagrams. [1][2]

• Available ELK layout variants:

  • elk (alias of elk.layered), elk.layered, elk.stress, elk.force, elk.mrtree, elk.sporeOverlap (availability depends on the layout loader version). [3][4]

• How to enable ELK per-diagram:

  • Add YAML frontmatter to the diagram:

    config:
    layout: elk

  • Or set config.layout (or graph attr) to one of the elk.* values. (This only selects the algorithm; the ELK loader must be provided to Mermaid runtime.) [1][3]

• Runtime requirements (important):

  • The ELK engine is not bundled in all Mermaid distributions (Mermaid removed ELK from the main minified build in recent major releases). Consumers must register the ELK layout loader with Mermaid by importing/registering the package or loading the CDN ESM module. Examples:
    • npm: npm install @mermaid-js/layout-elk; import and mermaid.registerLayoutLoaders(elkLayouts).
    • CDN (module): import mermaid and the layout-elk ESM file from jsdelivr and call mermaid.registerLayoutLoaders(...).
    • If the host (app/site) does not include the layout loader, specifying layout: elk will fall back to the default layout engine. [4][5][6]

• Version / compatibility notes:

  • Many docs and providers note that ELK must be explicitly added for modern Mermaid builds (post the change that removed ELK from core). Check the Mermaid version and whether your environment/vendor bundles @mermaid-js/layout-elk; if not, add/register the package or use the CDN module. [4][5]

Key references:

• Mermaid docs — ELK/layout config & YAML frontmatter. [1]
• @mermaid-js/layout-elk package (usage, supported elk.* algorithms, CDN+npm examples). [4][6]
• Guide/examples showing layoutLoaders / provider note about needing to enable the loader (Hugo/other integrations). [5]

If you want, tell me where you run Mermaid (browser page, Node bundler, Obsidian/Typora/Docs site) and I’ll give exact code/snippet for that environment.

---

🌐 Web query:

Mermaid mindmap diagram type configuration sphinx

💡 Result:

Short answer: use the Sphinx mermaid extension (sphinxcontrib-mermaid or similar) to embed a mermaid mindmap block and supply Mermaid configuration (either globally in conf.py or inline via a front-matter config block). Mermaid’s mindmap is an explicit diagram type with its own config object (padding, maxNodeWidth, layoutAlgorithm) and may require mermaid >= 9.4.0 (or registering the external mindmap plugin for older versions). [1][2][3][4]

Examples

1. conf.py — enable extension and set a global mermaid initialize / config (example using sphinxcontrib-mermaid):

• extensions = ['sphinxcontrib.mermaid']
• mermaid_version = "11.0.0" # pick a version that includes mindmap
• mermaid_init_js = """mermaid.initialize({
  startOnLoad: true,
  theme: 'default',
  mindmap: { padding: 10, maxNodeWidth: 200, layoutAlgorithm: 'cose-bilkent' }
  });"""

(Adjust version / options as needed.) [3][4][8]

2. Inline in an RST file using the mermaid directive and an inline config block (Mermaid front-matter):
   .. mermaid::

   ---

   config:
   mindmap:
   padding: 12
   maxNodeWidth: 240
   layoutAlgorithm: tidy-tree

   mindmap
   Root
   A
   B
   C
   D

This renders a mindmap using the supplied mindmap config. [1][5][8]

Notes and links

• Mermaid mindmap syntax and examples: official Mermaid docs. [1][5]
• Mermaid config schema (mindmap options: padding, maxNodeWidth, layoutAlgorithm): config schema docs. [4][8]
• Sphinx integration: sphinxcontrib-mermaid docs (shows how to enable extension and pass mermaid version/init JS). [3]

If you want, tell me which Sphinx extension you’re using (sphinxcontrib-mermaid, myst-mermaid, or another) and I’ll give a tailored conf.py + directive example.

---

🌐 Web query:

Sphinx mermaid_include_elk mermaid_include_mindmap when needed

💡 Result:

Short answer:

• Set mermaid_include_elk (or mermaid_include_elk=True / mermaid_elk_version) when you need Mermaid's ELK layout/renderer (tidy-tree, complex automatic graph layouts used by some diagrams such as ELK-based layouts or improved mindmap layout). Source: sphinxcontrib-mermaid config docs. [1][2]

• You generally do NOT need a special "mermaid_include_mindmap" flag in Sphinx: modern Mermaid releases include mindmap support (and use lazy/async loading since ~v9.4), so mindmaps render with the standard Mermaid bundle; only on old Mermaid versions would you need to register the separate @mermaid-js/mermaid-mindmap package. See Mermaid mindmap docs. [3][4]

When to enable each (practical rules)

• Enable mermaid_include_elk when your diagrams need ELK layout (tidy-tree / automatic layout improvements, large hierarchical graphs, or when you explicitly use an ELK layout setting). If you disable it, those layouts will not be available. [1][2]
• Do nothing special for mindmaps if you use a recent mermaid version (>=~9.4 / current 11.x series used by the extension). If you are pinned to an older mermaid that doesn’t include mindmap, register/load the external mermaid-mindmap package. [3][4]

Where to configure

• In conf.py for sphinxcontrib-mermaid (examples):
  • mermaid_include_elk = True (or set mermaid_elk_version / mermaid_elk_use_local to control version/local path). [1][2]
  • mermaid_version / mermaid_use_local controls which Mermaid features (including mindmap) are available. [1][5]

References

1. sphinxcontrib-mermaid docs (config options, mermaid_include_elk).
2. mgaitan/sphinxcontrib-mermaid (GitHub / README / config notes).
3. Mermaid mindmap docs (history, lazy-loading since v9.4 and usage).
4. Mermaid config / layout-elk package info (ELK renderer package).

---

Remove unnecessary Mermaid feature flags.

The mermaid_include_mindmap flag is redundant for modern Mermaid versions (≥9.4 / current 11.x series), which include mindmap support by default with lazy loading. This flag provides no benefit and should be removed.

Additionally, mermaid_include_elk adds an optional layout engine (~1MB JS dependency) that is only needed for complex hierarchical graph layouts. Since the PR mentions sequence and ER diagrams, which don't require ELK, consider removing this flag unless ELK layouts are explicitly used elsewhere in the documentation.

Keep mermaid_d3_zoom and mermaid_fullscreen for the UX improvements they provide.

🤖 Prompt for AI Agents

In @docs/source/conf.py around lines 150 - 153, Remove the two unnecessary
Mermaid feature flags from the config: delete mermaid_include_mindmap (redundant
in modern Mermaid ≥9.4) and, unless you actually need ELK layouts elsewhere,
remove mermaid_include_elk to avoid pulling the ~1MB ELK dependency; keep
mermaid_d3_zoom and mermaid_fullscreen as-is to preserve UX improvements. Ensure
only mermaid_d3_zoom and mermaid_fullscreen remain in the conf.py configuration
block and run a quick docs build to confirm no references to ELK or mindmap
options remain.

[coderabbitai]

🧹 Nitpick | 🔵 Trivial

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash

# Check if file exists and get basic statistics
if [ ! -f "docs/source/database_schema.mmd" ]; then
  echo "File not found!"
  exit 1
fi

echo "=== File Statistics ==="
echo "Total lines: $(wc -l < docs/source/database_schema.mmd)"
echo ""

echo "=== Entity Count (lines containing entity definitions) ==="
entity_count=$(grep -c '^ *[a-z_]* {$' docs/source/database_schema.mmd)
echo "Entities found: $entity_count"
echo ""

echo "=== Relationship Count ==="
relationship_count=$(grep -c ' -- ' docs/source/database_schema.mmd)
echo "Relationships found: $relationship_count"
echo ""

echo "=== Breakdown of relationship types ==="
echo "One-or-zero to 0+ relationships: $(grep -c 'one or zero--0+' docs/source/database_schema.mmd)"
echo "1 to 0+ relationships: $(grep -c '^[^}]*1--0+' docs/source/database_schema.mmd)"
echo ""

echo "=== Checking diagram structure ==="
echo "First line (should be 'erDiagram'): $(head -1 docs/source/database_schema.mmd)"
echo "Last 10 lines:"
tail -10 docs/source/database_schema.mmd

Repository: TemoaProject/temoa

Length of output: 986

---

🏁 Script executed:

#!/bin/bash

# Check if this is used in documentation build
echo "=== Checking documentation setup ==="
if [ -f "docs/source/conf.py" ]; then
  echo "Found docs/source/conf.py"
  # Check for mermaid configuration
  grep -i "mermaid\|diagram" docs/source/conf.py | head -20 || echo "No mermaid config found"
fi

echo ""
echo "=== Checking for any index or related documentation ==="
find docs -name "*.rst" -o -name "*.md" | xargs grep -l "database_schema" 2>/dev/null | head -10

echo ""
echo "=== Looking for any build or rendering issues mentioned in issues/PR ==="
if [ -d ".git" ]; then
  git log --oneline --all -- docs/source/database_schema.mmd 2>/dev/null | head -10
fi

Repository: TemoaProject/temoa

Length of output: 572

---

🏁 Script executed:

#!/bin/bash

# Check if there are any build scripts or makefile
echo "=== Checking build setup ==="
if [ -f "Makefile" ]; then
  echo "Makefile found. HTML build target:"
  grep -A5 "html:" Makefile | head -10 || echo "No html target"
fi

if [ -f "docs/Makefile" ]; then
  echo "docs/Makefile found"
  head -30 docs/Makefile
fi

echo ""
echo "=== Checking for pytest or similar test configs ==="
ls -la pytest.ini setup.cfg pyproject.toml tox.ini 2>/dev/null | grep -v "cannot access"

echo ""
echo "=== README or contribution guidelines ==="
[ -f "README.md" ] && echo "README.md exists" || echo "No README.md"
[ -f "CONTRIBUTING.md" ] && echo "CONTRIBUTING.md exists" || echo "No CONTRIBUTING.md"

Repository: TemoaProject/temoa

Length of output: 1521

---

🏁 Script executed:

#!/bin/bash

# Check git history for this file for any related issues
echo "=== Git history for database_schema.mmd ==="
git log --all --oneline -- docs/source/database_schema.mmd 2>/dev/null | head -20

echo ""
echo "=== Check for any issues/discussion about rendering ==="
# Look for any comments or TODOs in the file
grep -n "TODO\|FIXME\|NOTE\|performance\|slow\|render" docs/source/database_schema.mmd 2>/dev/null || echo "No performance-related comments found"

echo ""
echo "=== Check if diagram is mentioned in any issue/PR discussions ==="
if [ -d ".git" ]; then
  # Look for commits that touched related files around same time
  echo "Recent commits touching database or schema docs:"
  git log --all --oneline --since="2024-06-01" -- docs/source/ 2>/dev/null | grep -i "schema\|database\|diagram" | head -10
fi

echo ""
echo "=== Check mermaid configuration details ==="
grep -A2 -B2 "mermaid" docs/source/conf.py

Repository: TemoaProject/temoa

Length of output: 839

---

🏁 Script executed:

#!/bin/bash

# Check if there are any specific tests or build commands documented
echo "=== Checking CONTRIBUTING.md for build instructions ==="
grep -i "build\|mermaid\|diagram\|docs" CONTRIBUTING.md | head -15

echo ""
echo "=== Check if there are build scripts ==="
ls -la scripts/ 2>/dev/null || echo "No scripts directory"
ls -la build* 2>/dev/null | grep -v ".py" || echo "No build files found"

echo ""
echo "=== Check pyproject.toml for any mermaid or doc-related config ==="
cat pyproject.toml | grep -A5 -B5 "mermaid\|doc" || echo "No mermaid config in pyproject.toml"

Repository: TemoaProject/temoa

Length of output: 1030

---

Consider breaking this large ER diagram into multiple focused views if maintainability becomes a concern.

This comprehensive 84-entity, 197-relationship diagram is well-configured for rendering: the documentation setup includes ELK layout engine (mermaid_include_elk), D3 zoom (mermaid_d3_zoom), and fullscreen support (mermaid_fullscreen), which directly address readability and rendering complexity for large diagrams.

That said, if this diagram becomes difficult to maintain or update as the schema evolves, consider splitting it into focused diagrams organized by logical domains (e.g., core structure, constraints, costs, emissions, outputs). This is an optional architectural improvement rather than a blocker—no rendering or performance issues have been observed with the current configuration.

🤖 Prompt for AI Agents

In @docs/source/database_schema.mmd around lines 1 - 875, The ER diagram is very
large (84 entities/197 relationships) and should be split into smaller, focused
diagrams to improve maintainability; create multiple mermaid diagrams (e.g.,
"core structure" covering core tables like technology, time_period, region,
capacity_credit; "costs" covering cost_fixed, cost_variable, cost_invest,
cost_emission; "emissions" covering emission_activity, emission_embodied,
emission_end_of_life; "outputs" covering output_flow_in, output_flow_out,
output_storage_level, output_cost) by moving subsets of entity blocks and their
relationships into separate diagram sections or files, preserve the existing
mermaid settings (mermaid_include_elk, mermaid_d3_zoom, mermaid_fullscreen) for
each diagram, and update any documentation index or navigation so readers can
open the focused views instead of one monolithic diagram.