noteflow/docs/sprints/.archive/sprint-organization/lib.md

Client Lib Reorganization Plan

The client/src/lib directory is currently a flat list of 50+ files mixed with subdirectories, creating a "sloppy" and hard-to-navigate structure. This document outlines a plan to reorganize them into domain-specific subdirectories to improve maintainability and discoverability.

Analysis

1. Audio

Target Directory: client/src/lib/audio/

File	Proposed Name	Purpose	Dependencies
audio-device-ids.ts	device-ids.ts	Device ID resolution logic	None
audio-device-ids.test.ts	device-ids.test.ts	Tests for device ID resolution	device-ids
audio-device-persistence.integration.test.ts	device-persistence.integration.test.ts	Integration tests for persistence	storage-keys, device-ids
speaker-utils.ts	speaker.ts	Speaker stats aggregation	preferences, types
speaker-utils.test.ts	speaker.test.ts	Tests for speaker utils	preferences, speaker

2. Observability

Target Directory: client/src/lib/observability/

File	Proposed Name	Purpose	Dependencies
client-logs.ts	client.ts	Core client logging buffer	storage-keys, types
client-logs.test.ts	client.test.ts	Tests for client logging	client
client-log-events.ts	events.ts	Typed log event emitters	client, types
client-log-events.test.ts	events.test.ts	Tests for log events	client, events
client-log-events.integration.test.ts	events.integration.test.ts	Integration tests	client, events, log-messages
debug.ts	debug.ts	Dev-mode debug logger	client
error-reporting.ts	errors.ts	Error formatting & toasting	toast, api/helpers
log-converters.ts	converters.ts	API to UI log conversion	types
log-converters.test.ts	converters.test.ts	Tests for converters	converters
log-groups.ts	groups.ts	Log grouping logic	time, group-summarizer
log-groups.test.ts	groups.test.ts	Tests for grouping	groups
log-group-summarizer.ts	group-summarizer.ts	Summarization logic for groups	types
log-group-summarizer.test.ts	group-summarizer.test.ts	Tests for group summarizer	group-summarizer
log-messages.ts	messages.ts	Human-readable log formatting	None
log-messages.test.ts	messages.test.ts	Tests for log formatting	messages
log-sanitizer.ts	sanitizer.ts	Sensitive data redaction	None
log-summarizer.ts	summarizer.ts	Consecutive log summarization	timing-constants, types
log-summarizer.test.ts	summarizer.test.ts	Tests for summarizer	summarizer

3. Utils (General)

Target Directory: client/src/lib/utils/

File	Proposed Name	Purpose	Dependencies
utils.ts	index.ts	Tailwind cn helper	clsx, tailwind-merge
utils.test.ts	index.test.ts	Tests for cn	index
async-utils.ts	async.ts	Fire-and-forget, AsyncQueue	client-logs
download-utils.ts	download.ts	Blob creation & download	types
event-emitter.ts	event-emitter.ts	Typed event emitter	client-logs
format.ts	format.ts	Date/Time/Number formatting	time
format.test.ts	format.test.ts	Tests for formatting	format
id-utils.ts	id.ts	UUID generation	None
object-utils.ts	object.ts	Nested object access	None
object-utils.test.ts	object.test.ts	Tests for object utils	object
polling-utils.ts	polling.ts	Safe polling hooks	React
time.ts	time.ts	Time constants	None

4. Integrations

Target Directory: client/src/lib/integrations/

File	Proposed Name	Purpose	Dependencies
default-integrations.ts	defaults.ts	Default integration config	config, types
integration-utils.ts	utils.ts	Integration helpers & icons	types, lucide-react
integration-utils.test.ts	utils.test.ts	Tests for integration utils	utils
oauth-utils.ts	oauth.ts	OAuth state & deep links	tauri-adapter

5. Storage

Target Directory: client/src/lib/storage/

File	Proposed Name	Purpose	Dependencies
storage-keys.ts	keys.ts	Centralized storage keys	None
storage-utils.ts	utils.ts	Safe storage wrappers	client-logs
crypto.ts	crypto.ts	Encrypted storage	client-logs, config, storage-keys
crypto.test.ts	crypto.test.ts	Tests for crypto	crypto

6. Preferences

Target Directory: client/src/lib/preferences/

File	Proposed Name	Purpose	Dependencies
preferences-sync.ts	sync.ts	Sync logic (should move INTO existing dir)	tauri-api, client-logs, preferences
preferences-sync.test.ts	sync.test.ts	Tests for sync	sync
preferences-validation.test.ts	validation.test.ts	Tests for validation events	preferences

7. System

Target Directory: client/src/lib/system/

File	Proposed Name	Purpose	Dependencies
tauri-events.ts	events.ts	Global Tauri event bridge	tauri-adapter, client-logs
tauri-events.test.tsx	events.test.tsx	Tests for event bridge	events

8. State

Target Directory: client/src/lib/state/

File	Proposed Name	Purpose	Dependencies
entity-store.ts	entities.ts	Global entity store	api, id-utils
entity-store.test.ts	entities.test.ts	Tests for entity store	entities

9. UI

Target Directory: client/src/lib/ui/

File	Proposed Name	Purpose	Dependencies
styles.ts	styles.ts	Shared Tailwind classes	None
cva.ts	cva.ts	CVA re-export	class-variance-authority
cva.test.ts	cva.test.ts	Tests for CVA	cva

10. Constants

Target Directory: client/src/lib/constants/

File	Proposed Name	Purpose	Dependencies
status-constants.ts	status.ts	Status enums (Sync, Connection)	None
timing-constants.ts	timing.ts	Timing constants	None

Execution Plan

1. Create Directories:

   mkdir -p client/src/lib/{audio,observability,utils,integrations,storage,system,state,ui,constants}
   

2. Move & Rename Files: Execute git moves as per the tables above.
3. Cleanup:
   • Delete client/src/lib/ai-providers.ts (re-export file) and ensure imports point to client/src/lib/ai-providers/index.
   • Rename client/src/lib/ai-providers/ to client/src/lib/ai/.
4. Update Imports:
   • Perform search-and-replace for all moved modules.
   • Special care for client-logs, storage-keys, and utils (cn) as they are widely used.
5. Verification:
   • Run all tests in client/src/lib/**.
   • Run type check npm run type-check.

Impacted Areas

• Global: Almost every file in the client application imports from lib/utils (cn), lib/client-logs, or lib/storage-keys.
• Settings: heavily relies on preferences and integrations.
• Recording: relies on audio, observability, and system.

Recommendations

• Barrel Files: Add index.ts to each new subdirectory to simplify imports (e.g., import { cn } from '@/lib/utils').
• Strict Imports: Enforce imports from the new locations via ESLint if possible.