Add architecture diagram workflow and documentation

[fizyk]

Chore that needs to be done:

• Add newsfragment pipenv run towncrier create [issue_number].[type].rst

Types are defined in the pyproject.toml, issue_number either from issue tracker or the Pull request number

Summary by CodeRabbit

• Documentation

  • Added architecture diagram to the documentation, illustrating the test environment lifecycle and interactions between key components.

• Chores

  • Implemented automated workflow to render and update architecture diagrams on documentation changes.
  • Enhanced pre-commit checks with automatic JSON formatting fixes.

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

[coderabbitai]

Walkthrough

Introduces automated GitHub Actions workflow to render Mermaid diagrams, adds Puppeteer configuration for diagram rendering, enables autofix in pre-commit hooks, and documents the test environment architecture with a new Mermaid sequence diagram.

Changes

Cohort / File(s)	Summary
CI/CD Automation .github/workflows/diagram.yml, docs/puppeteer-config.json	New GitHub Actions workflow that triggers on changes to Mermaid source files, renders diagrams to SVG using Mermaid CLI and Puppeteer, and auto-commits the output. Puppeteer config adds sandbox bypass arguments for containerised environments.
Pre-commit Configuration .pre-commit-config.yaml	Adds --autofix argument to the pretty-format-json hook to automatically fix formatting during pre-commit runs.
Documentation docs/architecture.mmd, newsfragments/1244.docs.rst	New Mermaid sequence diagram documenting the test environment lifecycle (PostgreSQL factory, seeded template database, per-test cloning, and teardown). Changelog fragment notes the addition of the plugins' architecture diagram.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 A curious rabbit hops with glee,
Diagrams now render automatically!
Pre-commit's fixed, the workflow's in place,
Architecture documented—what a trace!
Mermaid magic in SVG embrace ✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title accurately summarises the main changes: adding a GitHub Actions workflow for rendering Mermaid diagrams and related documentation files.

✨ 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: 1

🤖 Fix all issues with AI Agents

In @.github/workflows/diagram.yml:
- Around line 3-5: The push trigger currently watches 'docs/*.mmd' but the
render step only targets a single file; align them by either changing the
trigger to 'docs/architecture.mmd' (narrow push.paths) or update the render step
(the command that processes docs/architecture.mmd) to iterate over or glob all
docs/*.mmd so every triggered file is actually rendered; pick one approach and
update the workflow so push.paths and the render command use the same pattern.

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 5553970 and 2a5575f.

⛔ Files ignored due to path filters (1)

• docs/images/architecture.svg is excluded by !**/*.svg

📒 Files selected for processing (6)

• .github/workflows/diagram.yml
• .pre-commit-config.yaml
• docs/architecture.mmd
• docs/images/.keep
• docs/puppeteer-config.json
• newsfragments/1244.docs.rst

⏰ 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). (19)

• GitHub Check: postgresql_oldest / postgres (3.14)
• GitHub Check: postgresql_oldest / postgres (3.13)
• GitHub Check: postgresql_17 / postgres (pypy-3.11)
• GitHub Check: postgresql_17 / postgres (3.11)
• GitHub Check: docker_postgresql_18 / postgres (3.13)
• GitHub Check: postgresql_17 / postgres (3.13)
• GitHub Check: postgresql_oldest / postgres (pypy-3.11)
• GitHub Check: docker_postgresql_18 / postgres (3.10)
• GitHub Check: postgresql_oldest / postgres (3.12)
• GitHub Check: postgresql_oldest / postgres (3.11)
• GitHub Check: docker_postgresql_18 / postgres (3.14)
• GitHub Check: macos_postgres_18 / postgres (3.14)
• GitHub Check: postgresql_17 / postgres (3.12)
• GitHub Check: docker_postgresql_18 / postgres (3.12)
• GitHub Check: postgresql_17 / postgres (3.14)
• GitHub Check: docker_postgresql_18 / postgres (3.11)
• GitHub Check: postgresql_oldest / postgres (3.10)
• GitHub Check: macos_postgres_18 / postgres (3.13)
• GitHub Check: macos_postgres_18 / postgres (3.12)

🔇 Additional comments (6)

.pre-commit-config.yaml (1)

21-22: LGTM! Autofix improves consistency.

The --autofix argument enables automatic JSON formatting during pre-commit runs, which improves code consistency and reduces manual formatting effort.

newsfragments/1244.docs.rst (1)

1-1: LGTM! Clear and concise newsfragment.

The documentation fragment appropriately describes the addition of the architecture diagram.

docs/puppeteer-config.json (1)

1-6: LGTM! Standard CI configuration for Puppeteer.

The --no-sandbox and --disable-setuid-sandbox flags are standard for running Chrome/Puppeteer in containerised CI environments like GitHub Actions, where the sandbox cannot function properly.

docs/architecture.mmd (1)

1-19: LGTM! Well-structured architecture diagram.

The Mermaid sequence diagram clearly illustrates the pytest-postgresql test environment lifecycle, including the template database pattern, per-test cloning, and teardown procedures. The diagram provides excellent documentation for understanding the plugin's architecture.

.github/workflows/diagram.yml (2)

23-27: LGTM! Proper commit handling with skip-ci.

The auto-commit configuration correctly uses [skip ci] to prevent infinite workflow loops and specifies an appropriate file pattern for the rendered SVG outputs.

---

20-21: The docs/images/ directory is already tracked in the repository with a .keep file, ensuring it persists in version control. No additional setup step is needed.

Likely an incorrect or invalid review comment.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Check for .mmd files in docs/ directory
fd -e mmd . docs/

Repository: dbfixtures/pytest-postgresql

Length of output: 93

---

🏁 Script executed:

#!/bin/bash
# Read the diagram.yml workflow file
cat -n .github/workflows/diagram.yml

Repository: dbfixtures/pytest-postgresql

Length of output: 1044

---

Align trigger pattern with rendering logic to prevent future inconsistency.

The workflow triggers on any .mmd file in docs/ (line 5), but the render command (line 21) only processes docs/architecture.mmd. While currently only one .mmd file exists, the trigger pattern is broader than the rendering logic. If additional .mmd files are added to docs/ in the future, they will trigger the workflow but won't be rendered.

Consider either:

• Updating line 21 to render all .mmd files dynamically, or
• Restricting the trigger pattern to only docs/architecture.mmd

🤖 Prompt for AI Agents

In @.github/workflows/diagram.yml around lines 3 - 5, The push trigger currently
watches 'docs/*.mmd' but the render step only targets a single file; align them
by either changing the trigger to 'docs/architecture.mmd' (narrow push.paths) or
update the render step (the command that processes docs/architecture.mmd) to
iterate over or glob all docs/*.mmd so every triggered file is actually
rendered; pick one approach and update the workflow so push.paths and the render
command use the same pattern.