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

Client API Reorganization Plan

The client/src/api directory is currently a flat list of adapters, core logic, and helpers, mixing different abstraction layers. This document outlines a plan to reorganize them into logical layers to improve maintainability and separation of concerns.

Analysis

1. Adapters (Implementations)

Target Directory: client/src/api/adapters/

File	Exports	Call Sites	Dependencies	Tests
cached-adapter.ts	cachedAPI	index.ts, index.test.ts	interface, types, cached/*	cached-adapter.test.ts
cached/*	(Various API sections)	cached-adapter.ts	interface, types	N/A
mock-adapter.ts	mockAPI	index.ts, index.test.ts	interface, types, mock-data, mock-stream	mock-adapter.test.ts
mock-data.ts	generateId, generateMeeting, ...	mock-adapter.ts	types	mock-data.test.ts
mock-transcription-stream.ts	MockTranscriptionStream	mock-adapter.ts	interface, types	mock-transcription-stream.test.ts
tauri-adapter/	(Directory)	index.ts	interface, types, @tauri-apps/*	tauri-adapter/**/*.test.ts
tauri-constants.ts	TauriCommands, TauriEvents	tauri-adapter, constants.ts	N/A	tauri-constants.test.ts
offline-defaults.ts	offlineServerInfo, ...	cached-adapter, cached/base.ts	types	N/A

2. Core Logic & State

Target Directory: client/src/api/core/

File	Exports	Call Sites	Dependencies	Tests
connection-state.ts	getConnectionState, setConnectionMode	index.ts, reconnection.ts, hooks	N/A	connection-state.test.ts
reconnection.ts	startReconnection, onReconnected	index.ts, hooks	interface, connection-state	reconnection.test.ts
error-utils.ts	extractErrorMessage, classifyError	adapters/*, helpers.ts	types	N/A (Tested in helpers.test.ts)
helpers.ts	delay, paginate, stateToGrpcEnum	adapters/*	types, error-utils	helpers.test.ts
constants.ts	Timing, IdentityDefaults	adapters/*	tauri-constants	N/A
transcription-stream.ts	TranscriptionStream (interface)	interface.ts, adapters/*	types	N/A

3. Contracts (Root)

Target Directory: client/src/api/ (Keep in root)

File	Exports	Call Sites	Dependencies	Tests
index.ts	initializeAPI, getAPI	Application Entry	adapters/*, core/*, interface	index.test.ts
interface.ts	NoteFlowAPI	Everywhere	types, core/streams	N/A
types/	(Type definitions)	Everywhere	N/A	types/**/*.test.ts

Execution Plan

1. Create Directories: client/src/api/adapters/{cached,mock,tauri}, client/src/api/core.
2. Move Core Files:
   • connection-state.ts -> core/connection.ts
   • reconnection.ts -> core/reconnection.ts
   • constants.ts -> core/constants.ts
   • helpers.ts -> core/helpers.ts
   • error-utils.ts -> core/errors.ts
   • transcription-stream.ts -> core/streams.ts (Rename to avoid confusion with implementation)
3. Move Adapters:
   • cached-adapter.ts -> adapters/cached/index.ts
   • client/src/api/cached/ -> adapters/cached/implementations/ (or flatten into adapters/cached/)
   • offline-defaults.ts -> adapters/cached/defaults.ts
   • mock-adapter.ts -> adapters/mock/index.ts
   • mock-data.ts -> adapters/mock/data.ts
   • mock-transcription-stream.ts -> adapters/mock/stream.ts
   • tauri-adapter/ content -> adapters/tauri/
   • tauri-constants.ts -> adapters/tauri/constants.ts (Update root constants.ts to re-export if needed, or update imports)
4. Move Tests: Move all associated tests (.test.ts) alongside their source files.
   • Note: tauri-transcription-stream.test.ts is currently in root, move to adapters/tauri/stream.test.ts.
5. Update Imports:
   • Update relative imports within the moved files.
   • Update usages in index.ts and interface.ts.
   • Update usages across the codebase (using search & replace).
6. Cleanup:
   • Ensure client/src/api/constants.ts properly re-exports Tauri constants if they are still needed globally, or update call sites to import from adapters/tauri/constants.

Impacted Tests

• api/index.test.ts
• api/cached-adapter.test.ts
• api/mock-adapter.test.ts
• api/connection-state.test.ts
• api/reconnection.test.ts
• api/tauri-transcription-stream.test.ts
• api/helpers.test.ts
• hooks/use-*.test.ts (Indirectly via imports)

Recommendations

• Flatten Cached Adapter: The cached/ subdirectory currently contains one file per feature. This is good structure, keep it within adapters/cached/.
• Unified Stream Interface: Ensure TranscriptionStream is clearly defined in core and implemented consistently in adapters.
• Error Handling: Centralize error types in core/errors.ts and ensure all adapters use them.
• Constants: client/src/api/constants.ts re-exports from tauri-constants.ts. This dependency direction should be verified. If generic constants depend on adapter-specific constants, it might be better to decouple them.