feat: implement centralized structured logger utility (#24)

[rohansaini-02]

Summary

Implementation of a decoupled Centralized Structured Logger Utility Proof of Concept (PoC). This module provides a robust, standardized way to log events, warnings, and errors across the entire TAP Buddy app with context tagging, severity filtering, and a pluggable transport layer for future crash analytics integrations.

Related Issue

Resolves #24

Problem Statement

As the codebase grows with complex background synchronizations (Issue #13) and DIKSHA content interactions (Issue #14), debugging via standard console output becomes unmanageable. We need a standardized logger with filtering, metadata support, and clear context tagging to pinpoint exactly which module is generating a log.

Changes Made

• Isolated Module Creation: Developed the shared-utils/logger standalone TypeScript package.
• Logger Class Implementation: Built a highly configurable Logger supporting global and instance-level severity filtering.
• Severity Levels & Priorities: Defined DEBUG, INFO, WARN, and ERROR levels with cascading priority logic.
• Context Tagging & Metadata: Integrated strict format requirements ensuring every log entry carries a module tag ([Context]) and optional serialized metadata.
• Pluggable Transport Layer: Designed Logger.setGlobalTransport() to allow injecting custom log handlers (e.g., for sending logs to Sentry or Crashlytics in production) while falling back to natively formatted console methods.
• Automated Validation: Integrated a Jest test suite with 100% coverage across statements, branches, and functions.
• Housekeeping: Added a local .gitignore to keep the module structure clean and free of build artifacts.

Technical Decisions

• Pluggable Architecture: Allowing transport overrides ensures that when we add a production crash reporter in the future, we only change code in one place (where the app boots) rather than rewriting logger imports across 50+ files.
• Standalone Package: Maintained the practice of building in isolated sub-directories to avoid root-level pollution and force clean dependency trees, aligning with the existing architecture.
• Strict Typing: Exported the LogMessage and LogLevel interfaces to guarantee downstream modules feed the logger the correct, type-safe data shapes.

Testing Performed

• 100% Code Coverage: Verified all logic paths using Jest.
• Severity Filtering: Verified that lower-priority logs are correctly skipped when higher severity thresholds are set, and metadata serialization appends cleanly.
• Manual Verification: Wrote a custom Node script (manual_test.ts) to visually confirm output formats and ensure the console fallback mechanism gracefully handles all severity levels and metadata edge cases.

Results

A fully testable, type-safe logging utility that provides the foundation for deep observability during offline-first syncing.

Checklist

• Code follows project conventions
• Tests pass (100% coverage achieved)
• Documentation updated (README included in PoC)
• Changes are scoped to one problem