Docs App Mode Preference — Local vs Cloud Toggle

Problem

The docs-angular app has no clear, persistent way to switch between local (filesystem) and cloud (MongoDB) documentation sources. Current behavior is implicit and scattered:

• Config editor: Tries backend-docs-api first, falls back to assets — no user control
• Project selection: Always loads from assets/docs-folders-config.json — ignores cloud
• CloudTransferService.isCloudMode: Only set after a successful transfer — not a preference
• No single source of truth for "I want local" vs "I want cloud"

Goal

Provide an explicit, user-controlled toggle stored in gograb-api.user_preferences, so:

1. Users can easily switch between local and cloud mode
2. Preference persists across sessions and devices (when logged in)
3. All docs-angular consumers (project list, config editor, etc.) respect the same setting
4. Anonymous users default to local (no preference = local)

Architecture

Data Flow

User toggles "Local" / "Cloud"
        ↓
PUT /api/users/me/preferences { docs: { appMode: 'local' | 'cloud' } }
        ↓
backend-api → user_preferences (MongoDB)
        ↓
docs-angular: On load, GET /api/users/me/preferences
        ↓
docsAppMode signal → project-selection, config-editor, etc.

Preference Location

Collection: gograb-api.user_preferences
Field: docs.appMode — new sub-document for docs-specific preferences

// New sub-schema
@Schema({ _id: false })
export class DocsPreferences {
  @Prop({
    type: String,
    enum: ['local', 'cloud'],
    default: 'local',
  })
  appMode: 'local' | 'cloud';
}

// In UserPreferences
@Prop({ type: DocsPreferences, default: () => ({ appMode: 'local' }) })
docs: DocsPreferences;

Rationale: Separate docs sub-schema (like chromeExtension, chat) keeps docs preferences extensible (e.g. defaultProject, sidebarCollapsed later).

Default by role (Session 218):

• executive, developer, system → default local (they can switch to cloud)
• Others (readers, etc.) → default cloud (they cannot access local filesystem)

Backend Changes (backend-api / libs-api)

1. Schema (libs/libs-api/backend-core)

• Add DocsPreferences class with appMode: 'local' | 'cloud'
• Add docs: DocsPreferences to UserPreferences
• Add to UpdatePreferencesInput: docs?: Partial<DocsPreferences>
• Add to PreferencesResult: docs: DocsPreferences
• Add to getDefaultPreferences and toPreferencesResult
• Update updatePreferences to handle input.docs

2. API

• GET /api/users/me/preferences — already returns full preferences; will include docs
• PUT /api/users/me/preferences — already accepts partial updates; add docs support

No new endpoints. Existing preferences API is sufficient.

Frontend Changes (docs-angular)

1. Docs App Mode Service (new)

File: apps/docs-angular/src/app/services/docs-app-mode.service.ts

• docsAppMode = signal<'local' | 'cloud'>('local')
• loadFromPreferences() — GET /api/users/me/preferences, set signal
• setMode(mode: 'local' | 'cloud') — PUT preferences, update signal
• Fallback: If not authenticated or request fails → 'local'
• APP_INITIALIZER or early in app bootstrap: call loadFromPreferences()

2. Project Selection State

File: apps/docs-angular/src/app/state/project-selection.state.ts

• Inject DocsAppModeService
• In LoadAvailableProjects:
  • If docsAppMode() === 'cloud': fetch from DocsApiService.getFoldersConfig() (via backend-docs-api)
  • If docsAppMode() === 'local': fetch from assets/docs-folders-config.json (current behavior)
• When mode changes, re-run LoadAvailableProjects (or expose a RefreshProjects action)

3. Config Editor

File: apps/docs-angular/src/app/admin/config-editor/config-editor.component.ts

• Inject DocsAppModeService
• In loadConfiguration(): use docsAppMode() to decide source (cloud first vs local first)
• Replace implicit "try cloud, fallback local" with explicit: if cloud → only cloud; if local → only local
• Add mode toggle UI in header/settings area

4. Settings UI

Location: Admin area — either in Config Editor header or a dedicated Settings page

UI: Toggle or segmented control:

• Local — Use documentation from your project files (docs/, assets/docs-folders-config.json)
• Cloud — Use documentation from MongoDB (backend-docs-api)

Visibility: Only show when user is authenticated. Anonymous users always use local.

5. API Base for Preferences

• docs-angular uses backendApiUrl (proxy /api → backend-api:3000)
• GET /api/users/me/preferences and PUT /api/users/me/preferences require JWT
• Auth interceptor already adds token for /api/ routes

Edge Cases

Implementation Order

1. Backend: Add DocsPreferences schema + service support
2. DocsAppModeService: Create service, load on init
3. Project selection: Use mode to choose config source
4. Config editor: Use mode + add toggle UI
5. Admin dashboard: Optional quick link to toggle (or keep in config editor only)

Files to Create/Modify

Success Criteria

• User can toggle Local/Cloud in docs admin
• Preference persists in MongoDB user_preferences.docs.appMode
• Project list and config editor both respect the mode
• Anonymous users default to local with no errors
• Clear visual indicator of current mode (e.g. badge: "Local" / "Cloud")