Document best practices for Clock/Time handling

[SaintPatrck]

🎟️ Tracking

Documentation updates

📔 Objective

Outline the architectural pattern for handling time-dependent code.

The primary objective is to enforce testability and determinism by using an injected Clock instead of static calls to Instant.now() or DateTime.now().

Specific changes include:

• A new section "Best Practices : Time and Clock Handling" in STYLE_AND_BEST_PRACTICES.md. This guide details the rationale, provides good/bad code examples for ViewModels and utility functions, and shows how to use a fixed clock in tests.
• A corresponding section "Clock/Time Handling" in architectural-patterns.md to serve as a quick reference for LLM assisted code reviews.
• An update to the pull request checklist in architectural-patterns.md to include a check for the use of injected Clock.

⏰ Reminders before review

• Contributor guidelines followed
• All formatters and local linters executed and passed
• Written new unit and / or integration tests where applicable
• Protected functional changes with optionality (feature flags)
• Used internationalization (i18n) for all UI strings
• CI builds passed
• Communicated to DevOps any deployment requirements
• Updated any necessary documentation (Confluence, contributing docs) or informed the documentation team

🦮 Reviewer guidelines

• 👍 (:+1:) or similar for great changes
• 📝 (:memo:) or ℹ️ (:information_source:) for notes or general info
• ❓ (:question:) for questions
• 🤔 (:thinking:) or 💭 (:thought_balloon:) for more open inquiry that's not quite a confirmed issue and could potentially benefit from discussion
• 🎨 (:art:) for suggestions / improvements
• ❌ (:x:) or ⚠️ (:warning:) for more significant problems or concerns needing attention
• 🌱 (:seedling:) or ♻️ (:recycle:) for future improvements or indications of technical debt
• ⛏ (:pick:) for minor or nitpick changes

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.49%. Comparing base (5d308aa) to head (a2a9312).
⚠️ Report is 5 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #6340   +/-   ##
=======================================
  Coverage   85.49%   85.49%           
=======================================
  Files         763      763           
  Lines       54640    54640           
  Branches     7865     7865           
=======================================
  Hits        46716    46716           
  Misses       5189     5189           
  Partials     2735     2735           

☔ 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.

[github-actions]

Checkmarx One – Scan Summary & Details – 5fe4172b-c338-4845-9bcc-98d8458c6c5d

Great job! No new security vulnerabilities introduced in this pull request

[claude]

Claude finished @SaintPatrck's task in 2m 11s —— View job

---

Overall Assessment: APPROVE

This PR adds comprehensive documentation for Clock/Time handling patterns to enforce testability and determinism. The documentation covers ViewModels, extension functions, testing approaches, and integrates seamlessly with existing architectural guidance.

Code Review Details

No findings - This is a well-structured documentation PR with:

• ✅ Technically accurate examples (verified Clock provider exists in CoreModule.kt:47)
• ✅ Consistent formatting matching existing documentation style
• ✅ Comprehensive coverage: ViewModels, extension functions, testing, and DI setup
• ✅ Proper cross-references between architectural-patterns.md and STYLE_AND_BEST_PRACTICES.md
• ✅ Added checklist item to catch violations during reviews

The guidance correctly emphasizes using injected Clock over static Instant.now() calls, following established Hilt DI patterns and enabling deterministic testing with Clock.fixed().

---

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 4.5 noreply@anthropic.com

[david-livefront]

It's beautiful! 🥹