Server-Side Settings Implementation Summary

This document summarizes the changes made to enable strongly-typed server-side settings configuration.

Changes Made

1. New Shared Package (`packages/shared/`)

Created a new workspace package for types shared between client and server:

Files Created:

settings-types.ts - Shared TypeScript interfaces and types
package.json - Package definition
tsconfig.json - TypeScript configuration

Key Types:

Settings - Complete settings structure (client + server)
ServerConfig - Server-specific subset of settings
ModelConfiguration - AI model configuration
Category - Note category definitions
DEFAULT_SETTINGS - Default values
Helper functions: extractServerConfig(), validateServerConfig()

2. Server-Side Implementation (`packages/server/`)

New Files:

src/settings-manager.ts - Singleton settings manager
src/adapters/FileSystemSettingsAdapter.ts - File system persistence
README.md - Documentation for server-side usage

Modified Files:

src/index.ts - Added settings loading and API endpoints
package.json - Added dependencies (@open-notes/shared, @types/node)

API Endpoints Added:

GET /api/settings - Get current server configuration
POST /api/settings/reload - Reload settings from file system

Settings File Location: Default: ~/.open-notes/settings.json (customizable)

3. Client Updates (`packages/client/`)

Files Created:

src/adapters/HybridSettingsAdapter.ts - Local + server sync adapter

Files Modified:

package.json - Added @open-notes/shared dependency

4. Root Configuration

Files Modified:

package.json - Added packages/shared to workspaces

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     @open-notes/shared                      │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐  │
│  │           settings-types.ts                         │  │
│  │  - Settings (full client+server)                    │  │
│  │  - ServerConfig (server subset)                     │  │
│  │  - ModelConfiguration, Category, etc.               │  │
│  │  - DEFAULT_SETTINGS, validation helpers             │  │
│  └─────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                     ▲                    ▲
                     │                    │
        ┌────────────┴────────┐  ┌────────┴──────────┐
        │                     │  │                    │
┌───────▼────────────────┐   │  │  ┌─────────────────▼────────┐
│  @open-notes/client    │   │  │  │  @open-notes/server      │
│                        │   │  │  │                          │
│  LocalStorageSettings  │   │  │  │  FileSystemSettings      │
│  Adapter               │   │  │  │  Adapter                 │
│         ▼              │   │  │  │         ▼                │
│  HybridSettings        │───┘  └──│  SettingsManager         │
│  Adapter (sync)        │         │  (singleton)             │
│                        │         │         │                │
│  localStorage +        │         │  File: ~/.open-notes/    │
│  server sync           │         │        settings.json     │
└────────────────────────┘         └──────────────────────────┘

Usage Examples

Server-Side Usage

import { getSettingsManager } from './settings-manager.js';

// Initialize server
const settingsManager = getSettingsManager();
await settingsManager.load();

// Access typed configuration
const config = await settingsManager.getConfig();
console.log('Language Model:', config.languageModel?.modelName);
console.log('Categories:', config.categories.length);

// Type-safe access
if (config.languageModel) {
  const { provider, modelName, apiKey } = config.languageModel;
  // Full IntelliSense support
}

Client-Side Usage

import { HybridSettingsAdapter } from './adapters/HybridSettingsAdapter';

// Use hybrid adapter for local + server sync
const adapter = new HybridSettingsAdapter('http://localhost:3001');
const settings = await adapter.load();

Type Safety Benefits

Compile-Time Validation: TypeScript catches type errors during development
IntelliSense Support: Full autocompletion in IDEs
Refactoring Safety: Renaming/changing types updates all usages
Documentation: Types serve as inline documentation
Validation Helpers: Runtime validation with validateServerConfig()

Settings Structure

ServerConfig (Server-Only Fields)

{
  languageModel?: ModelConfiguration;
  embeddingModel?: ModelConfiguration;
  categories: Category[];
  genericEnrichmentPrompt: string;
  categoryRecognitionPrompt: string;
}

Full Settings (Client + Server)

{
  // Server fields (above) +
  theme: 'light' | 'dark' | 'system';
  fontSize: 'sm' | 'md' | 'lg' | 'xl';
  editorSettings: {
    autoSave: boolean;
    autoSaveInterval: number;
  };
  lastSavedAt?: number;
}

Next Steps

To use the new server-side settings:

Install dependencies:
```
npm install
```

Create settings file:

mkdir -p ~/.open-notes
echo '{}' > ~/.open-notes/settings.json

Start server:
```
npm run dev -w packages/server
```

Test API endpoints:

# Get settings
curl http://localhost:3001/api/settings

# Reload settings
curl -X POST http://localhost:3001/api/settings/reload

Migration Notes

Existing Client Code

Existing client code continues to work with LocalStorageSettingsAdapter
Optional: Switch to HybridSettingsAdapter for server sync
No breaking changes to existing settings store

Adding New Settings

Add to Settings interface in packages/shared/settings-types.ts
Update DEFAULT_SETTINGS with default value
If server needs it, add to ServerConfig interface
Update extractServerConfig() if needed
TypeScript will enforce updates throughout codebase

Benefits

✅ Type Safety: Strongly-typed configuration across client and server ✅ Code Sharing: Single source of truth for settings types ✅ Validation: Built-in runtime validation helpers ✅ Flexibility: File system adapter allows custom storage locations ✅ Singleton Pattern: Consistent configuration access on server ✅ API Endpoints: HTTP access to server configuration ✅ Documentation: Comprehensive README and inline comments ✅ Future-Proof: Easy to extend with new settings

Files Changed Summary

New Directories:

packages/shared/ (new package)
packages/server/src/adapters/ (new directory)

New Files: (9 files)

packages/shared/settings-types.ts
packages/shared/package.json
packages/shared/tsconfig.json
packages/server/src/settings-manager.ts
packages/server/src/adapters/FileSystemSettingsAdapter.ts
packages/server/README.md
packages/client/src/adapters/HybridSettingsAdapter.ts
This summary document

Modified Files: (4 files)

packages/server/src/index.ts
packages/server/package.json
packages/client/package.json
package.json (root)

FilesExpand file tree

SERVER_SETTINGS_IMPLEMENTATION.md

Latest commit

History