Add interactive CodeCanvas diagram for activitywatch

[Abdulnaser97]

I was trying to understand how activitywatch works under the hood so I created a diagram for it using code-canvas.com. I think it will be pretty helpful for contributors to quickly onboard to the inner-works of activitywatch.

Here is the generated diagram for activitywatch grouped by the application's use-cases and their runtime data flows:
Open activitywatch's interactive diagram

I built code canvas to simulate a senior engineer who have been working on activitywatch's codebase for pretty long and can explain to you any functionality of the repository visually through diagrams.

Here is what users are saying about codecanvas

"I used to spend 4 hours asking GPT how a use case in a codebase works and I keep going back and forth until I am able to draw a diagram to summarize my understanding,
CodeCanvas gives me that diagram in 40 seconds"

---

Some Notes:

• The diagram is already generated for activitywatch, completely free, no monthly subscription. Consider it as my contribution to help fellow contributors lower their context onboarding friction before they can start contributing.
• Read the 1 pager guide to learn how to refine simulations to capture specific codebase logics you might want to cover.
• I am aware the mapping to the source code is shiften a couple lines off in some cases, I am working on fixing the bug asap.
• You can reach me out anytime on discord discord.gg/t3ezMyMPqr

---

Important

Adds a link to an interactive CodeCanvas diagram in README.md for better understanding of the activitywatch codebase.

• Documentation:
  • Adds a section in README.md linking to an interactive CodeCanvas diagram for activitywatch.
  • Diagram provides a visual walkthrough of the codebase, aiding in contributor onboarding.
  • Diagram is hosted externally and is free to use.

^{This description was created by for 7d1ac0f. You can customize this summary. It will automatically update as commits are pushed.}

[ellipsis-dev]

Important

Looks good to me! 👍

Reviewed everything up to 7d1ac0f in 6 minutes and 22 seconds. Click for details.

• Reviewed 18 lines of code in 1 files
• Skipped 1 files when reviewing.
• Skipped posting 2 draft comments. View those below.
• Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

1. README.md:223

• Draft comment:
  The CodeCanvas interactive walkthrough link uses URL parameters (owner=ActivityWatch and branch=master) that differ from those in the PR description. Please confirm that these values are intentional and correctly reference the desired diagram.
• Reason this comment was not posted:
  Comment did not seem useful. Confidence is useful = 40% <= threshold 50% The comment is asking the PR author to confirm their intention regarding the URL parameters. This violates the rule against asking for confirmation of intention. However, it does point out a potential discrepancy between the code and the PR description, which could be useful. The comment could be rephrased to suggest checking the URL parameters without asking for confirmation.

2. README.md:225

• Draft comment:
  Consider using a more descriptive alt attribute for the embedded diagram (e.g., 'Interactive CodeCanvas diagram of ActivityWatch architecture') and opting for responsive image dimensions rather than fixed width/height values for improved accessibility and mobile support.
• Reason this comment was not posted:
  Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 20% vs. threshold = 50% This comment is clearly about code that was changed/added in the diff (the new image tag on line 225). The suggestions are actionable and specific: better alt text for accessibility and responsive dimensions. However, I need to consider the rules: "Do NOT make comments that are obvious or unimportant" and "Do NOT comment on any pure frontend UI or styling changes, only logic." This is arguably a UI/styling change (image display), though the alt text is an accessibility concern. The rule says to assume if the author changed the UI, they did it correctly. The fixed dimensions might be intentional to match the actual image size. The alt text being just "image" is not great for accessibility, but this could be considered a minor/obvious improvement rather than a critical issue. The comment addresses accessibility (alt text) which could be considered important, not just pure styling. However, the rule explicitly states not to comment on UI/styling changes and to assume the author did it correctly. The suggestion about responsive dimensions is definitely a styling preference, not a logic issue. While accessibility is important, this is still fundamentally a UI change (adding an image to a README). The rules explicitly say not to comment on frontend UI or styling changes. The alt text improvement, while nice to have, is not a critical code logic issue. This falls under the category of "obvious or unimportant" improvements that don't require a code change comment. This comment should be deleted. It's about a UI/styling change (image display in a README), and the rules explicitly state not to comment on pure frontend UI or styling changes, only logic. While the accessibility suggestion is well-intentioned, it's not a critical code logic issue that requires a comment.

Workflow ID: wflow_4rvhjFoygRPuDMWk

^{You can customize by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}

[LarsArtmann]

I like the idea of offering Code Graphs, but how can we ensure this stays up-to-date?

[Abdulnaser97]

• I am working on a github action script that runs on each PR and updates the parts of the diagram that are linked to source code that was changed in that pull request, will probably need ~2 weeks to finish it, will reach out then.
  • Right now the version I have regenerates the entire diagram at each PR, but that is becoming costly especially if using expensive AI models.
• The current solution for now is this: When we notice that the diagram is becoming obsolete, just hit the "Refine Simulation" button then "Generate" then "Save". it will regenerate the simulation with the new source code.

From my experience however, it takes pretty long time before the diagram starts to become obsolete (obviously depends on each repo).

[ErikBjare]

Code Canvas looks cool!

We could link to it from the README or docs in some suitable section, but I am not going to merge a 10,000 line messy file into this clean bundle repo.

[Abdulnaser97]

Ok makes sense, I just don't want to host the diagram on some database you don't own, so that you guys have control over the diagram in the future.

Here's what I propose instead while you're not familiar with CodeCanvas:

• I gave you collaborator access to my forked version of acitivityWatch (called activityWatch-CodeCanvas) where the diagram is current stored
• I will transfer repo ownership to you once you are comfortable with using and maintaing the diagram (or right now if you prefer)
• I updated the README to point to the forked repo's master branch and removed the diagram file from this PR

Finally, I invite you to join the CodeCanvas discord server if you have any questions (and any feedback, for e.g. were you able to go through a full simulation on CodeCanvas?).
https://discord.gg/t3ezMyMPqr

[Abdulnaser97]

Ok makes sense, I just don't want to host the diagram on some database you don't own, so that you guys have control over the diagram in the future.

Here's what I propose instead while you're not familiar with CodeCanvas:

• I gave you collaborator access to my forked version of acitivityWatch (called activityWatch-CodeCanvas) where the diagram is current stored
• I will transfer repo ownership to you once you are comfortable with using and maintaing the diagram (or right now if you prefer)
• I updated the README to point to the forked repo's master branch and removed the diagram file from this PR

Finally, I invite you to join the CodeCanvas discord server if you have any questions (and any feedback, for e.g. were you able to go through a full simulation on CodeCanvas?). https://discord.gg/t3ezMyMPqr

Hi @ErikBjare and @LarsArtmann, floating this PR.

P.S. I am actually using activityWatch's codecanvas as an example for how it makes it easier to understand data flows across the different repos.