bulltrackers-module 1.0.591 → 1.0.593

package/functions/generic-api/user-api/README_MIGRATION.md

@@ -1,152 +0,0 @@
-# User API Migration & Reorganization Summary
-
-## Overview
-
-This directory contains plans for:
-1. **Firestore Migration**: Restructuring user-centric data to use CID-based paths under `SignedInUsers/{cid}/...`
-2. **Code Reorganization**: Breaking down the 2573-line `data_helpers.js` into modular, maintainable files
-
-## Documents
-
-### 1. MIGRATION_PLAN.md
-**Purpose:** Complete migration strategy for Firestore paths
-**Key Points:**
-- Always use CID (not Firebase UID) for user data paths
-- Root data format: `{collection}/{date}/{cid}/{cid}` (document ID is CID)
-- Auto-migration on read: Try new format first, fallback to legacy, auto-migrate if found
-- 9 user-centric data types to migrate
-
-### 2. FIRESTORE_PATHS_INVENTORY.md
-**Purpose:** Quick reference of all Firestore paths
-**Key Points:**
-- Complete list of legacy and new paths
-- Organized by migration priority
-- Files that need updates
-- Migration checklist
-
-### 3. CODE_REORGANIZATION_PLAN.md
-**Purpose:** Plan to reorganize messy code structure
-**Key Points:**
-- Break down 2573-line `data_helpers.js` (29 functions) into 18 focused files
-- Create core utilities for shared functionality
-- Organize by feature domain (data, profile, watchlist, etc.)
-- Maintain backward compatibility during migration
-
-## Key Decisions
-
-### Firestore Paths
-✅ **Always use CID** - All user data paths use `{cid}`, not `{firebaseUid}`
-✅ **Root data format** - Task engine writes to `{collection}/{date}/{cid}/{cid}` (document ID is CID)
-✅ **Auto-migration** - Migrate on read, no batch migration needed initially
-✅ **Firebase UID mapping** - `signedInUsers/{firebaseUid}` is ONLY for UID→CID lookup
-
-### Code Organization
-✅ **Modular structure** - Split large files into focused, single-responsibility modules
-✅ **Core utilities** - Shared functionality in `helpers/core/`
-✅ **Feature domains** - Organize by feature (data, profile, watchlist, etc.)
-✅ **Backward compatibility** - Re-export from new locations to avoid breaking changes
-
-## Migration Priority
-
-### High Priority (User Actions/Creations)
-1. Notifications → `SignedInUsers/{cid}/notifications`
-2. Alerts → `SignedInUsers/{cid}/alerts`
-3. Watchlists → `SignedInUsers/{cid}/watchlists`
-4. Subscriptions → `SignedInUsers/{cid}/subscriptions`
-5. Verification → `SignedInUsers/{cid}/verification/data` (4 segments)
-6. Sync Requests → `SignedInUsers/{cid}/syncRequests`
-
-### Medium Priority (User Data Snapshots)
-7. Portfolio (latest) → `SignedInUsers/{cid}/portfolio/latest`
-8. Trade History (latest) → `SignedInUsers/{cid}/tradeHistory/latest`
-9. Social Posts (latest) → `SignedInUsers/{cid}/posts`
-
-## Implementation Order
-
-### Phase 1: Core Infrastructure
-1. Create `helpers/core/path_resolution_helpers.js` with migration support
-2. Create `helpers/core/data_lookup_helpers.js` with CID-based lookups
-3. Create `helpers/core/compression_helpers.js` for decompression
-4. Create `helpers/core/user_status_helpers.js` for user checks
-
-### Phase 2: Data Helpers
-1. Create `helpers/data/portfolio_helpers.js`
-2. Create `helpers/data/social_helpers.js`
-3. Create `helpers/data/computation_helpers.js`
-4. Create `helpers/data/instrument_helpers.js`
-
-### Phase 3: Profile & Feature Helpers
-1. Create `helpers/profile/` directory with PI and user profile helpers
-2. Create `helpers/watchlist/` directory with watchlist-specific helpers
-3. Create `helpers/search/` directory with PI search helpers
-4. Create `helpers/metrics/` directory with personalized metrics helpers
-
-### Phase 4: Update Existing Helpers
-1. Update `notification_helpers.js` to use CID-based paths
-2. Update `alert_helpers.js` to use CID-based paths
-3. Update `watchlist_helpers.js` to use CID-based paths
-4. Update `subscription_helpers.js` to use CID-based paths
-5. Update `verification_helpers.js` to use CID-based paths
-6. Update `user_sync_helpers.js` to use CID-based paths
-
-### Phase 5: Migration & Testing
-1. Implement auto-migration on read
-2. Test all endpoints with both legacy and new formats
-3. Monitor migration progress
-4. Remove legacy read fallback after all users migrated
-
-## Root Data Format Reference
-
-The task engine writes to these formats (DO NOT CHANGE):
-
-- **Portfolio:** `SignedInUserPortfolioData/{date}/{cid}/{cid}` (document ID is CID)
-- **Trade History:** `SignedInUserTradeHistoryData/{date}/{cid}/{cid}` (document ID is CID)
-- **Social Posts:** `SignedInUserSocialPostData/{date}/{cid}/{cid}` (document ID is CID)
-
-The API should read from these exact formats when querying root data.
-
-## Helper Functions
-
-### CID Resolution
-```javascript
-const { getCidFromFirebaseUid } = require('./helpers/collection_helpers');
-const cid = await getCidFromFirebaseUid(db, firebaseUid);
-```
-
-### Path Resolution with Migration
-```javascript
-const { readWithMigration } = require('./helpers/core/path_resolution_helpers');
-const data = await readWithMigration(db, newPath, legacyPath, { isCollection: false });
-```
-
-### Collection Path from Registry
-```javascript
-const { getCollectionPath } = require('../../config/collection_registry');
-const path = getCollectionPath('signedInUsers', 'notifications', { cid: '12345678' });
-// Returns: 'SignedInUsers/12345678/notifications'
-```
-
-## Testing Strategy
-
-1. **Unit Tests**: Test path resolution and migration logic
-2. **Integration Tests**: Test dual read/write with both formats
-3. **Migration Tests**: Test auto-migration on read
-4. **Rollback Tests**: Ensure legacy paths still work during transition
-
-## Next Steps
-
-1. ✅ Review migration plan (done)
-2. ⏳ Review code reorganization plan (done)
-3. ⏳ Start implementing core helpers
-4. ⏳ Begin migrating helper files one by one
-5. ⏳ Test each migration incrementally
-6. ⏳ Deploy with feature flags
-7. ⏳ Monitor and iterate
-
-## Questions?
-
-Refer to:
-- `MIGRATION_PLAN.md` for detailed migration strategy
-- `FIRESTORE_PATHS_INVENTORY.md` for path reference
-- `CODE_REORGANIZATION_PLAN.md` for code structure details
-

package/functions/generic-api/user-api/REFACTORING_COMPLETE.md

@@ -1,106 +0,0 @@
-# Refactoring Complete ✅
-
-## Summary
-
-The `data_helpers.js` file (2550 lines) has been completely refactored into organized, modular helper files with full migration support.
-
-## File Size Reduction
-
-- **Before**: `data_helpers.js` = 2550 lines
-- **After**: `data_helpers.js` = 90 lines (re-exports only)
-- **Reduction**: 96% smaller, now just a re-export hub
-
-## New File Structure
-
-```
-helpers/
-├── core/
-│   ├── compression_helpers.js (compression utilities)
-│   ├── data_lookup_helpers.js (find latest dates)
-│   ├── user_status_helpers.js (PI status checks)
-│   └── path_resolution_helpers.js (path resolution with migration)
-├── data/
-│   ├── portfolio_helpers.js (portfolio endpoints)
-│   ├── social_helpers.js (social posts)
-│   ├── computation_helpers.js (computation results)
-│   └── instrument_helpers.js (instrument mappings)
-├── profile/
-│   ├── pi_profile_helpers.js (PI profile & analytics)
-│   ├── user_profile_helpers.js (user verification & PI check)
-│   └── profile_view_helpers.js (profile view tracking)
-├── watchlist/
-│   ├── watchlist_data_helpers.js (legacy watchlist endpoints)
-│   ├── watchlist_generation_helpers.js (auto-generate)
-│   └── watchlist_analytics_helpers.js (trigger counts)
-├── search/
-│   ├── pi_search_helpers.js (PI search)
-│   └── pi_request_helpers.js (PI requests & rankings check)
-├── recommendations/
-│   └── recommendation_helpers.js (user recommendations)
-└── metrics/
-    └── personalized_metrics_helpers.js (personalized metrics)
-```
-
-## Migration Support
-
-All helper files now use the migration system:
-
-- **`readWithMigration()`** - Tries new path, falls back to legacy, auto-migrates on read
-- **`writeWithMigration()`** - Dual-write to both paths during transition
-- **Registry-based paths** - All paths resolved through `collection_registry.js`
-- **Legacy path mappings** - All legacy paths mapped in `path_resolution_helpers.js`
-
-## Legacy Path Mappings
-
-All legacy paths are now mapped and support auto-migration:
-
-### Signed-In User Data
-- `user_notifications/{firebaseUid}/notifications` → `SignedInUsers/{cid}/notifications`
-- `user_watchlists/{cid}/lists` → `SignedInUsers/{cid}/watchlists`
-- `user_verifications/{username}` → `SignedInUsers/{cid}/verification/data`
-- `user_sync_requests/{cid}/requests` → `SignedInUsers/{cid}/syncRequests`
-- `user_sync_requests/{cid}/global/latest` → `SignedInUsers/{cid}/syncStatus/latest`
-- `signed_in_users_social/{cid}/posts` → `SignedInUsers/{cid}/posts`
-
-### Popular Investor Data
-- `pi_fetch_requests/{piCid}/requests/{requestId}` → `PopularInvestors/{piCid}/fetchRequests/{requestId}`
-- `pi_fetch_requests/{piCid}/global/latest` → `PopularInvestors/{piCid}/fetchStatus/latest`
-- `pi_fetch_requests/{piCid}/user_requests/{userCid}` → `PopularInvestors/{piCid}/userFetchRequests/{userCid}`
-- `pi_reviews/{piCid}_{userCid}` → `PopularInvestors/{piCid}/reviews/{reviewId}`
-- `pi_social_posts/{piCid}/posts/{postId}` → `PopularInvestors/{piCid}/posts/{postId}`
-- `profile_views/{piCid}_{date}` → `PopularInvestors/{piCid}/profileViews/{date}`
-- `profile_views/individual_views/views/{piCid}_{viewerCid}_{timestamp}` → `PopularInvestors/{piCid}/views/{viewId}`
-
-## Backward Compatibility
-
-✅ **Zero Breaking Changes** - All existing imports continue to work:
-- `data_helpers.js` re-exports all functions from organized modules
-- All function signatures remain identical
-- All endpoints behave the same way
-
-## Benefits
-
-1. **Modularity** - Each file has a clear, single responsibility
-2. **Maintainability** - Easy to find and update specific functionality
-3. **DRY Compliance** - Shared utilities extracted to core helpers
-4. **Migration Support** - Auto-migration on read, dual-write on write
-5. **Registry-Based** - All paths use collection registry
-6. **Testability** - Smaller files are easier to test
-7. **Readability** - Clear organization makes code easier to understand
-
-## Next Steps
-
-1. ✅ All functions migrated to organized modules
-2. ✅ All functions use migration system
-3. ✅ Legacy paths mapped
-4. ✅ `data_helpers.js` cleaned up
-5. ⏳ Test all endpoints to ensure zero breaking changes
-6. ⏳ Update any external documentation
-
-## Notes
-
-- Root data collections remain unchanged (populated by task engines)
-- Public watchlists remain in `public_watchlists` (not user-centric)
-- System collections like `user_gcid_mappings` remain unchanged
-- Firebase UID → CID mapping stays in `signedInUsers/{firebaseUid}` main document
-

package/functions/generic-api/user-api/REFACTORING_STATUS.md

@@ -1,85 +0,0 @@
-# Refactoring Status
-
-## ✅ Completed
-
-### Core Infrastructure
-- ✅ Created `core/compression_helpers.js` - Decompression utilities
-- ✅ Created `core/data_lookup_helpers.js` - Data date lookup functions
-- ✅ Created `core/user_status_helpers.js` - User status checks
-- ✅ Created `core/path_resolution_helpers.js` - Path resolution with migration support
-- ✅ Updated `collection_helpers.js` - Re-exports from core for backward compatibility
-- ✅ Updated `collection_registry.js` - Added all new paths and legacy mappings
-
-### Data Helpers
-- ✅ Created `data/portfolio_helpers.js` - Portfolio endpoints
-- ✅ Created `data/social_helpers.js` - Social posts endpoints
-- ✅ Created `data/computation_helpers.js` - Computation endpoints
-- ✅ Created `data/instrument_helpers.js` - Instrument mappings
-
-### Profile Helpers
-- ✅ Created `profile/pi_profile_helpers.js` - PI profile and analytics
-- ✅ Created `profile/profile_view_helpers.js` - Profile view tracking with migration
-
-### Migration Support
-- ✅ Updated `path_resolution_helpers.js` with ALL legacy path mappings
-- ✅ Implemented `readWithMigration()` - Auto-migrates on read
-- ✅ Implemented `writeWithMigration()` - Dual-write during transition
-
-## 🔄 In Progress / Remaining
-
-### Profile Helpers
-- ⏳ `profile/user_profile_helpers.js`
-  - `getUserVerification` - Needs migration to use `SignedInUsers/{cid}/verification`
-  - `checkIfUserIsPopularInvestor` - Can use existing helpers
-
-### Watchlist Helpers
-- ⏳ `watchlist/watchlist_data_helpers.js` (Legacy)
-  - `getWatchlist` - Legacy endpoint, needs migration support
-  - `updateWatchlist` - Legacy endpoint, needs migration support
-- ⏳ `watchlist/watchlist_generation_helpers.js`
-  - `autoGenerateWatchlist` - Auto-generate from copied PIs
-- ⏳ `watchlist/watchlist_analytics_helpers.js`
-  - `getWatchlistTriggerCounts` - Watchlist analytics
-
-### Search & Recommendations
-- ⏳ `search/pi_search_helpers.js`
-  - `searchPopularInvestors` - PI search
-- ⏳ `search/pi_request_helpers.js`
-  - `requestPiAddition` - Request PI addition
-  - `checkPisInRankings` - Check PIs in rankings
-- ⏳ `recommendations/recommendation_helpers.js`
-  - `getUserRecommendations` - User recommendations
-
-### Metrics
-- ⏳ `metrics/personalized_metrics_helpers.js`
-  - `getSignedInUserPIPersonalizedMetrics` - Personalized metrics
-  - `generateSamplePIPersonalizedMetrics` - Sample data generator
-
-### Cleanup
-- ⏳ Remove all legacy function implementations from `data_helpers.js`
-- ⏳ Update `data_helpers.js` to only re-export from organized modules
-- ⏳ Update all helper files to use `readWithMigration` and `writeWithMigration`
-
-## Legacy Path Mappings Status
-
-All legacy paths are now mapped in `path_resolution_helpers.js`:
-- ✅ Signed-in user notifications, alerts, watchlists, subscriptions
-- ✅ User verification, sync requests, sync status
-- ✅ Portfolio, trade history, social posts
-- ✅ PI fetch requests, fetch status, user fetch requests
-- ✅ PI reviews, social posts, profile views, individual views
-
-## Next Steps
-
-1. Complete remaining helper file creation
-2. Update all functions to use migration system
-3. Remove legacy implementations from `data_helpers.js`
-4. Test all endpoints to ensure zero breaking changes
-5. Update documentation
-
-## File Size Reduction
-
-- **Before**: `data_helpers.js` = 2550 lines
-- **After (target)**: `data_helpers.js` = ~100 lines (re-exports only)
-- **Organized modules**: Each file 100-400 lines, clear responsibility
-

package/functions/generic-api/user-api/VERIFICATION_MIGRATION_NOTES.md

@@ -1,206 +0,0 @@
-# Verification Data Migration Notes
-
-## Current Implementation
-
-### Initiate Verification
-- **Path**: `{verificationsCollection}/{username}` (e.g., `verifications/marau2021`)
-- **Data**: `{ username, otp, status: 'PENDING', createdAt, expiresAt }`
-- **Purpose**: Store pending OTP before CID is known
-
-### Finalize Verification
-- **API Call**: `GET https://www.etoro.com/api/logininfo/v1.1/users/{username}`
-- **Response Contains**: `{ realCID, username, firstName, lastName, optOut, ... }`
-- **Current Action**: Updates verification doc with `{ status: 'VERIFIED', cid: realCID, verifiedAt, isOptOut }`
-- **Current Path**: Still at `{verificationsCollection}/{username}` (not migrated)
-
-## New Implementation
-
-### Initiate Verification (Unchanged)
-- **Path**: `{verificationsCollection}/{username}` (legacy, before CID known)
-- **Data**: `{ username, otp, status: 'PENDING', createdAt, expiresAt }`
-
-### Finalize Verification (Updated)
-- **After Bio Check API**:
-  1. Get `realCID` from `profileData.realCID`
-  2. Migrate verification data to: `SignedInUsers/{cid}/verification`
-  3. Store full profile data for reference
-  4. Delete or mark legacy verification as migrated
-
-- **New Path**: `SignedInUsers/{cid}/verification/data` (4 segments: collection/document/collection/document)
-  - Single document in subcollection to comply with Firestore even-segment rule
-- **New Data Structure**:
-```javascript
-{
-  username: 'Marau2021',
-  cid: 29312236,  // from profileData.realCID
-  firebaseUid: null,  // set later when Firebase account created
-  otp: 'I84Z9P',
-  status: 'VERIFIED',
-  createdAt: Timestamp,
-  expiresAt: Timestamp,
-  verifiedAt: Timestamp,
-  isOptOut: false,
-  profileData: {
-    realCID: 29312236,
-    gcid: 29595736,
-    demoCID: 30809243,
-    username: 'Marau2021',
-    firstName: 'Aiden',
-    lastName: 'Hawkins',
-    optOut: false,
-    isPi: false,
-    avatars: [...],
-    // ... other profile fields
-  }
-}
-```
-
-### Account Creation (New Step)
-- **When Firebase account is created**:
-  1. Get Firebase UID from auth system
-  2. Update verification document: `SignedInUsers/{cid}/verification`
-  3. Add: `{ firebaseUid: 'firebase-uid-here' }`
-  4. Also update: `signedInUsers/{firebaseUid}` with `{ etoroCID: cid }` (UID→CID mapping)
-
-## Migration Strategy
-
-### Option 1: Immediate Migration (Recommended)
-During `finalizeVerification`:
-1. Read from legacy path: `{verificationsCollection}/{username}`
-2. Get `realCID` from bio check API response
-3. Write to new path: `SignedInUsers/{cid}/verification`
-4. Delete legacy document (or mark as migrated)
-
-### Option 2: Dual Write (During Transition)
-During `finalizeVerification`:
-1. Write to both paths:
-   - Legacy: `{verificationsCollection}/{username}` (for backward compatibility)
-   - New: `SignedInUsers/{cid}/verification`
-2. Read from new path first, fallback to legacy
-3. Eventually remove legacy writes
-
-### Option 3: Auto-Migration on Read
-1. Keep legacy path for now
-2. When reading verification, check new path first
-3. If not found, read from legacy and migrate
-4. Eventually all verifications migrated
-
-## Implementation Changes Needed
-
-### verification_helpers.js
-
-#### initiateVerification
-- **No changes needed** - still uses legacy path (CID not known yet)
-
-#### finalizeVerification
-- **After getting `realCID` from API**:
-  ```javascript
-  const realCID = profileData.realCID;
-  
-  // 1. Read existing verification data
-  const legacyVerificationRef = db.collection(verificationsCollection).doc(username.toLowerCase());
-  const legacyVerificationDoc = await legacyVerificationRef.get();
-  const legacyData = legacyVerificationDoc.data();
-  
-  // 2. Create new verification document under CID
-  const newVerificationRef = db.collection('SignedInUsers')
-    .doc(String(realCID))
-    .collection('verification')
-    .doc('data'); // Single document named "data" to comply with Firestore even-segment rule (4 segments)
-  
-  await newVerificationRef.set({
-    username: legacyData.username,
-    cid: realCID,
-    firebaseUid: null, // Will be set when Firebase account created
-    otp: legacyData.otp,
-    status: 'VERIFIED',
-    createdAt: legacyData.createdAt,
-    expiresAt: legacyData.expiresAt,
-    verifiedAt: FieldValue.serverTimestamp(),
-    isOptOut: isOptOut,
-    profileData: profileData // Store full profile for reference
-  });
-  
-  // 3. Delete legacy verification (or mark as migrated)
-  await legacyVerificationRef.delete();
-  ```
-
-#### Account Creation Hook (New)
-- **When Firebase account is created** (in auth system or separate endpoint):
-  ```javascript
-  async function linkFirebaseAccountToVerification(db, firebaseUid, cid) {
-    // Update verification document with Firebase UID
-    const verificationRef = db.collection('SignedInUsers')
-      .doc(String(cid))
-      .collection('verification')
-      .doc('data'); // 4 segments: collection/document/collection/document
-    
-    await verificationRef.update({
-      firebaseUid: firebaseUid,
-      accountLinkedAt: FieldValue.serverTimestamp()
-    });
-    
-    // Also update UID→CID mapping
-    await db.collection('signedInUsers').doc(firebaseUid).set({
-      etoroCID: cid,
-      linkedAt: FieldValue.serverTimestamp()
-    }, { merge: true });
-  }
-  ```
-
-## Reading Verification Data
-
-### By CID (New)
-```javascript
-const verificationRef = db.collection('SignedInUsers')
-  .doc(String(cid))
-  .collection('verification')
-  .doc('data'); // 4 segments: collection/document/collection/document
-
-const verificationDoc = await verificationRef.get();
-if (verificationDoc.exists) {
-  return verificationDoc.data();
-}
-```
-
-### By Username (Legacy - During Migration)
-```javascript
-// Try new path first (if CID is known)
-// Fallback to legacy path if needed
-const legacyRef = db.collection(verificationsCollection).doc(username.toLowerCase());
-const legacyDoc = await legacyRef.get();
-if (legacyDoc.exists) {
-  // Auto-migrate if CID is available
-  const data = legacyDoc.data();
-  if (data.cid) {
-    // Migrate to new path
-    await migrateVerificationToCidPath(db, data.cid, data);
-  }
-  return data;
-}
-```
-
-## Benefits
-
-1. **Consistent Structure**: All user data under `SignedInUsers/{cid}/...`
-2. **Single Source of Truth**: One verification document per user (by CID)
-3. **Complete Profile Data**: Store full API response for reference
-4. **Firebase UID Linkage**: Connect Firebase account to eToro CID
-5. **Easier Queries**: Can query by CID instead of username
-
-## Registry Update
-
-Update `collection_registry.js`:
-```javascript
-verification: {
-    path: 'SignedInUsers/{cid}/verification/data',  // 4 segments: collection/document/collection/document
-    description: 'User verification status and OTP data (single document in subcollection)',
-    schema: '{ username, cid, firebaseUid, otp, status, createdAt, expiresAt, verifiedAt, isOptOut, profileData }',
-    dynamicSegments: ['{cid}'],
-    status: 'active',
-    legacyPaths: [
-        '{verificationsCollection}/{username}'  // Legacy path before CID known (2 segments)
-    ]
-}
-```
-

package/functions/generic-api/user-api/helpers/ORGANIZATION_COMPLETE.md

@@ -1,126 +0,0 @@
-# Helper Files Organization - Complete
-
-## Overview
-All helper files have been reorganized into logical subfolders for better maintainability and clarity.
-
-## New Directory Structure
-
-```
-helpers/
-├── alerts/                          # Alert-related functionality
-│   ├── alert_helpers.js             # Alert management (get, mark read, delete)
-│   ├── test_alert_helpers.js       # Test alert functionality for developers
-│   └── subscription_helpers.js     # Alert subscriptions for watchlists
-│
-├── verification/                    # User verification
-│   └── verification_helpers.js     # OTP bio check and account verification
-│
-├── sync/                            # User sync requests
-│   └── user_sync_helpers.js        # On-demand sync for user profiles
-│
-├── fetch/                           # On-demand data fetching
-│   └── on_demand_fetch_helpers.js  # PI data fetch requests with rate limiting
-│
-├── watchlist/                       # Watchlist management
-│   ├── watchlist_data_helpers.js    # Legacy single watchlist endpoints
-│   ├── watchlist_generation_helpers.js  # Auto-generation from copied PIs
-│   ├── watchlist_analytics_helpers.js   # Watchlist analytics and triggers
-│   └── watchlist_management_helpers.js   # Multi-watchlist CRUD operations
-│
-├── dev/                             # Developer tools
-│   └── dev_helpers.js               # Developer overrides and impersonation
-│
-├── reviews/                          # Review system
-│   └── review_helpers.js            # PI review submission and retrieval
-│
-├── notifications/                   # Notification system
-│   └── notification_helpers.js     # On-demand request notifications
-│
-├── core/                            # Core utilities
-│   ├── compression_helpers.js      # Data decompression
-│   ├── data_lookup_helpers.js       # Date lookup functions
-│   ├── path_resolution_helpers.js   # Path resolution with migration
-│   └── user_status_helpers.js      # User status checks
-│
-├── data/                            # Data endpoints
-│   ├── portfolio_helpers.js         # Portfolio data
-│   ├── social_helpers.js            # Social posts
-│   ├── computation_helpers.js       # Computation results
-│   └── instrument_helpers.js        # Instrument mappings
-│
-├── profile/                         # Profile endpoints
-│   ├── pi_profile_helpers.js       # PI profile and analytics
-│   ├── user_profile_helpers.js     # User profile and verification
-│   └── profile_view_helpers.js     # Profile view tracking
-│
-├── search/                          # Search functionality
-│   ├── pi_search_helpers.js        # PI search
-│   └── pi_request_helpers.js       # PI addition requests
-│
-├── recommendations/                 # Recommendations
-│   └── recommendation_helpers.js    # User recommendations
-│
-├── metrics/                         # Metrics
-│   └── personalized_metrics_helpers.js  # Personalized metrics
-│
-├── collection_helpers.js            # Re-exports from core (backward compat)
-└── data_helpers.js                 # Re-export hub (backward compat)
-```
-
-## File Organization by Purpose
-
-### Alerts (`alerts/`)
-- **alert_helpers.js**: Core alert management (get, mark read, delete, count)
-- **test_alert_helpers.js**: Developer tool for sending test alerts
-- **subscription_helpers.js**: Alert subscriptions for watchlist PIs
-
-### Verification (`verification/`)
-- **verification_helpers.js**: User account verification via OTP bio check
-
-### Sync (`sync/`)
-- **user_sync_helpers.js**: On-demand sync requests for user profiles (rate limited)
-
-### Fetch (`fetch/`)
-- **on_demand_fetch_helpers.js**: On-demand PI data fetching with rate limiting
-
-### Watchlist (`watchlist/`)
-- **watchlist_management_helpers.js**: Multi-watchlist CRUD operations (new system)
-- **watchlist_data_helpers.js**: Legacy single watchlist endpoints
-- **watchlist_generation_helpers.js**: Auto-generation from copied PIs
-- **watchlist_analytics_helpers.js**: Analytics and trigger counts
-
-### Dev (`dev/`)
-- **dev_helpers.js**: Developer overrides, impersonation, and testing tools
-
-### Reviews (`reviews/`)
-- **review_helpers.js**: PI review submission, retrieval, and eligibility checks
-
-### Notifications (`notifications/`)
-- **notification_helpers.js**: On-demand request completion notifications
-
-## Import Path Updates
-
-All imports have been updated to reflect the new structure:
-- `./dev_helpers` → `../dev/dev_helpers`
-- `./data_helpers` → `../data_helpers` (or appropriate relative path)
-- `./alert_helpers` → `../alerts/alert_helpers`
-- etc.
-
-## Backward Compatibility
-
-- `data_helpers.js` remains as a re-export hub for backward compatibility
-- `collection_helpers.js` re-exports from `core/path_resolution_helpers.js`
-- All existing imports continue to work
-
-## Benefits
-
-1. **Clear Organization**: Files are grouped by functionality
-2. **Easier Navigation**: Related files are in the same directory
-3. **Better Maintainability**: Smaller, focused files are easier to understand
-4. **Scalability**: Easy to add new files to appropriate folders
-5. **Zero Breaking Changes**: All existing imports still work
-
-## Next Steps
-
-The frontend can now be reviewed and updated to use the new import paths if desired, though backward compatibility is maintained.
-