docs: record FOSS library evaluation decisions for current custom implementations
Summary
Several custom implementations in this project were written instead of adopting existing FOSS libraries. The rationale is undocumented, making future contributors unaware of the tradeoffs. This issue tracks adding decision records (inline comments or ADRs) for the following:
Files to Document
| File | Custom Solution | Known Alternative | Decision to Record |
|---|---|---|---|
src/contexts/ThemeContext.tsx |
Custom dark/light/system theme | next-themes | Sufficient for current needs; revisit if SSR is added |
src/utils/searchUtils.ts |
Custom Levenshtein search | Fuse.js | Acceptable for small datasets; see # |
src/lib/utils.ts (formatToIST) |
Custom IST formatter | date-fns-tz | Single use case; see # |
src/contexts/AuthContext.tsx |
Custom auth + multi-tab sync | — | Justified: interceptor coupling + multi-tab sync too project-specific |
Acceptance Criteria
-
Each file listed above has a comment referencing the tradeoff -
Or a lightweight ADR exists in docs/decisions/
Labels: documentation, tech-debt, dx
Edited by Ranjith Raj