Skip to content

Conversation

@yihao03
Copy link

@yihao03 yihao03 commented Jan 19, 2026

Replaces original .pptx source file and the generated .png

What is the purpose of this pull request?

  • Documentation update
  • Bug fix
  • Feature addition or enhancement
  • Code maintenance
  • DevOps
  • Improve developer experience
  • Others, please explain:

Overview of changes:
Change replaced architecture diagram form architecture.pptx and architecture.png to use mermaid
diagram integrated in architecture.md

Anything you'd like to highlight/discuss:

Testing instructions:

  1. Run markbind serve in /docs/devGuide/design/architecture.md
  2. Navigate to the corresponding section to see if the diagram is rendered correctly.

Proposed commit message: (wrap lines at 72 characters)
Update architecture diagram to use mermaid


Checklist: ☑️

  • Updated the documentation for feature additions and enhancements
  • Added tests for bug fixes or features
  • Linked all related issues
  • No unrelated changes

Reviewer checklist:

Indicate the SEMVER impact of the PR:

  • Major (when you make incompatible API changes)
  • Minor (when you add functionality in a backward compatible manner)
  • Patch (when you make backward compatible bug fixes)

At the end of the review, please label the PR with the appropriate label: r.Major, r.Minor, r.Patch.

Breaking change release note preparation (if applicable):

  • To be included in the release note for any feature that is made obsolete/breaking

Give a brief explanation note about:

  • what was the old feature that was made obsolete
  • any replacement feature (if any), and
  • how the author should modify his website to migrate from the old feature to the replacement feature (if possible).

yihao03 and others added 2 commits January 19, 2026 14:03
@codecov
Copy link

codecov bot commented Jan 19, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 71.67%. Comparing base (28b407f) to head (4d82a61).

Additional details and impacted files
@@           Coverage Diff           @@
##           master    #2788   +/-   ##
=======================================
  Coverage   71.67%   71.67%           
=======================================
  Files         134      134           
  Lines        7284     7284           
  Branches     1514     1516    +2     
=======================================
  Hits         5221     5221           
  Misses       1936     1936           
  Partials      127      127           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@gerteck
Copy link
Member

gerteck commented Jan 19, 2026

tbh, not too sure how I feel about this diagram layout compared to the previous layout, although it's probably more maintainable

image image

Maybe use a landscape diagram orientation? Since we usually read dev docs from monitors (I assume)? Need a second opinion on this

@damithc
Copy link
Contributor

damithc commented Jan 19, 2026

Normally, the PowerPoint option gives us a lot more control which we can use to make the diagram easier to understand using direction/colour/shape cues. On the other hand, the mermaid/puml version is easier to update incrementally. In some cases the cost is worth the convenience.
For architecture level diagrams, often PowerPoint is better.
In this specific case, if the mermaid/puml version loses too much of that intuitiveness, it's OK to keep the PowerPoint version. Just need to keep the pptx version as well, to make it easier to update in future.

@gerteck
Copy link
Member

gerteck commented Jan 27, 2026

I think we can go ahead with using mermaid, but the diagram still needs some refinement.

@yihao03

I played around with the mermaid diagram to make it look more compact, and I think we should make sure that the new diagram at least

  • Instead of TD (top down), use LR (left right) - this fits more with how developers would use the site (in a landscape browser)
  • For brevity, maybe remove the legend, and keep the meaning of the lines obvious (e.g. can inline the contains, uses etc like --- contains --->)
  • Since the pptx is in git history, it should be okay to remove it, but let's keep the png for now as reference (also to signal that there is a pptx in the git history), unless the new mermaid diagram looks even better than the png such that we can just remove it
  • It should be okay to remove some of the text descriptions even further, as see fit, as long as it remains understandable
  • You can also add stuff based on ur understanding of the codebase now, since this diagram is quite legacy

Example:
image

Copy link
Member

@gerteck gerteck left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for working on this! Requesting some changes to make the graph look more compact and understandable at a glance!


![MarkBind Architecture Diagram](<{{baseUrl}}/images/dev diagrams/architecture.png>)
<mermaid>
graph TD
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Instead of TD (top down), use LR (left right)

classDef title fill:#6fa8dc,stroke:none,color:white,font-weight:bold;

%% --- 1. Top Level Structure ---
CLI[index.js #40;cli#41;]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider grouping these together

E.g.

    subgraph Core [Core Site Structure]
        direction LR
        Site[Site Object]
        Page[Page]
    end

end

%% --- 4. The Legend (Optional Hack to display legend) ---
subgraph LegendBox [Legend]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no need legend if we can inline the meanings

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants