001-ADR-Implement-Footnote-Caching-for-Improved-Performance

[kenny-lfx]

Implement Footnote Caching for Improved Performance

Context and Problem Statement

BigFoot.js dynamically generates and manages footnotes in real-time whenever a user interacts with a page. While this approach ensures that footnotes are always up-to-date, it can lead to unnecessary recomputation and performance overhead, especially for pages with a large number of footnotes or complex content. To improve performance, we need a way to reduce redundant footnote processing by caching footnote data.

Decision Drivers

• Improve page load times, especially on content-heavy pages with multiple footnotes.
• Minimize performance overhead related to dynamic footnote generation.
• Maintain compatibility with the existing dynamic footnote generation and updating system.
• Ensure the solution is simple and doesn’t introduce significant complexity.

Considered Options

• Implement local caching of footnote data
• Use browser-based caching (e.g., localStorage or sessionStorage)
• Keep the current implementation without caching

Decision Outcome

Chosen option: "Implement local caching of footnote data," because it offers a balanced approach to improving performance without relying heavily on browser storage or disrupting the current dynamic footnote generation. This method can store footnote data in memory for the duration of the page session, reducing the need for repeated calculations.

Consequences

• Good, because it reduces redundant footnote recomputation, improving page performance, especially on content-heavy pages.
• Good, because it doesn’t rely on persistent storage like localStorage, which might introduce complexity around data consistency and expiration.
• Bad, because caching adds a small amount of complexity to the footnote management logic.
• Neutral, because the performance gains will be most noticeable on pages with many footnotes but less significant for simple pages.

Confirmation

This decision will be confirmed through performance benchmarking before and after the implementation. Testing will focus on pages with varying footnote quantities to ensure caching improves both the perceived and actual performance. Memory profiling will ensure there are no memory leaks or excessive memory usage from the cache.

Pros and Cons of Other Options

Use browser-based caching (localStorage or sessionStorage)

• Good, because it persists across page reloads, potentially improving user experience on return visits.
• Bad, because it introduces complexity related to cache invalidation and data expiration.
• Bad, because using localStorage introduces additional considerations for large-scale footnote data.

Keep the current implementation without caching

• Good, because no changes are needed to the existing system.
• Bad, because performance issues will remain, especially on content-heavy pages.
• Bad, because users on slower connections or devices may experience longer load times.

[Shyam-Sundar-Bharathi]

Hi guys, I reviewed your ADR and did some research on cacheing the footnotes myself. Here are my thoughts:

Good

1. Good focus on performance: The local caching solution does a great job of improving page load times without making things too complicated. It avoids the hassle of persistent storage and still speeds things up.

2. Works well with the current system: This approach fits smoothly into the existing setup, so we don’t have to make big changes to how footnotes work. It's a smart upgrade without much disruption.

Bad

1. Adds some complexity: While caching helps with speed, it could make the footnote logic a bit harder to manage. It might be helpful to flag any issues early if debugging becomes tricky. Clear documentation of the caching steps would definitely help later on. More technical detail could help your ADR.

[rashi-bhansali]

I like this idea because it addresses a concern that we noticed while finding the tool pain points. However, like you mentioned, it will be super effective for docs with large no. of footnotes, not very noticeable in the regular usecase. Given the time limit of 2 days, I'm not sure if we can achieve this, Browser based caching seems simpler to implement, not ideal though

[rashi-bhansali]

Lazy loading and Virtual DOM could be another approach for improving performance.

[shouhardik]

The idea of improving footnote caching seems good! Implementing caching, we can have separate client side and server side cachcing in CoffeeScript

[Shyam-Sundar-Bharathi]

Closing this issue - unable to implement within given time frame / unclear implementation procedure.