whoa - so much - new features (UPC,etc) - Sentry for app logging! so much more !

docs/adr/0052-granular-debug-logging-strategy.md

@@ -0,0 +1,42 @@
+# ADR-052: Granular Debug Logging Strategy
+
+**Date**: 2026-01-11
+
+**Status**: Proposed
+
+## Context
+
+Global log levels (INFO vs DEBUG) are too coarse. Developers need to inspect detailed debug information for specific subsystems (e.g., `ai-service`, `db-pool`) without being flooded by logs from the entire application.
+
+## Decision
+
+We will adopt a namespace-based debug filter pattern, similar to the `debug` npm package, but integrated into our Pino logger.
+
+1. **Logger Namespaces**: Every service/module logger must be initialized with a `module` property (e.g., `logger.child({ module: 'ai-service' })`).
+2. **Environment Filter**: We will support a `DEBUG_MODULES` environment variable that overrides the log level for matching modules.
+
+## Implementation
+
+In `src/services/logger.server.ts`:
+
+```typescript
+const debugModules = (process.env.DEBUG_MODULES || '').split(',').map((s) => s.trim());
+
+export const createScopedLogger = (moduleName: string) => {
+  // If DEBUG_MODULES contains "ai-service" or "*", force level to 'debug'
+  const isDebugEnabled = debugModules.includes('*') || debugModules.includes(moduleName);
+
+  return logger.child({
+    module: moduleName,
+    level: isDebugEnabled ? 'debug' : logger.level,
+  });
+};
+```
+
+## Usage
+
+To debug only AI and Database interactions:
+
+```bash
+DEBUG_MODULES=ai-service,db-repo npm run dev
+```