port-nimara-client-portal/docs/comprehensive-fixes-implementation-plan.md

Comprehensive Implementation Plan for Portal Fixes

Overview

This document outlines the implementation plan for all requested fixes and improvements to the client portal system. Each section includes the problem, solution approach, and implementation details.

1. Hide Berth Recommendations

Problem

Berth recommendations are shown across all instances and need to be hidden.

Solution

• Remove or hide all UI elements related to berth recommendations
• Clean up related API calls
• Update the InterestDetailsModal and other components

Implementation

<!-- Remove from InterestDetailsModal.vue -->
<!-- Remove the berth recommendations autocomplete field -->
<!-- Remove link-berth-recommendations-to-interest API calls -->

2. EOI Fixes

2.1 Hide Debug Console

Problem

Debug console is visible in production

Solution

• Remove all console.log statements from EOI-related components
• Add environment check for debug outputs

2.2 Slider Bubble Positioning

Problem

Slider bubble doesn't fit entirely within the slider bar

Solution

• Adjust CSS for the slider component to ensure bubble stays within bounds
• Calculate bubble position based on slider width

2.3 EOI Deletion Requires Multiple Clicks

Problem

EOI deletion fails unless clicked multiple times

Solution

• Add proper loading states and disable button during deletion
• Implement proper error handling and retry logic
• Use operation locks to prevent concurrent operations

2.4 Clean Database on EOI Deletion

Problem

Signature links and ID numbers remain in NocoDB after deletion

Solution

// When deleting EOI:
// 1. Delete from Documenso
// 2. Clear all EOI-related fields in NocoDB:
//    - EOI Document
//    - EOI Client Link
//    - EOI Oscar Link
//    - EOI David Link
//    - EOI ID
//    - EOI Time Created
//    - EOI Time Sent
//    - EOI Status
// 3. Reset Sales Process Level if needed

2.5 EOI Regeneration Confirmation

Problem

No warning when regenerating EOI

Solution

• Add confirmation dialog with warning message
• Remind user to verify all information
• Delete old EOI data before regenerating

3. Email Refresh Button Styling

Problem

Refresh button needs to be round and moved away from compose button

Solution

<v-btn
  icon="mdi-refresh"
  size="small"
  variant="text"
  class="ml-2 rounded-circle"
  @click="loadEmails"
  :loading="loading"
>

4. Session Management

Problem

Email credentials persist incorrectly between sessions

Solution

• Clear sessionStorage on page load/unload
• Implement session validation on each API call
• Add session expiry timestamps
• Force re-authentication on page reload

5. Phone Input Country Issue

Problem

USA selection switches to American Samoa

Solution

• Fix country code sorting in PhoneInput component
• Ensure US (United States) appears before AS (American Samoa)
• Set explicit country code for USA (+1)

6. Email Attachments

Problem

Attachments not displayed or downloadable

Solution (Already Implemented)

• Added attachment display UI in EmailThreadView
• Created helper functions for icon display and file size formatting
• Implemented download functionality via proxy endpoint

7. IMAP Connection Reliability

Problem

IMAP requires multiple connection attempts

Solution (Already Implemented)

• Created email-sync service with exponential backoff retry
• Implemented MinIO-based caching for offline access
• Added connection pooling with health checks

8. Berth Assignment Concurrency

Problem

Multiple berth selections cause errors

Solution

• Implement operation locking for berth assignments
• Add debouncing to prevent rapid clicks
• Queue berth operations sequentially

9. 502 Gateway Errors

Problem

Frequent 502 errors requiring multiple retries

Root Causes

1. Connection pool exhaustion
2. Database connection limits
3. Memory/process issues
4. No retry logic in API calls

Solutions

1. Connection Pool Management

   • Implement proper connection pooling for IMAP
   • Add connection recycling and health checks
   • Set maximum connection limits

2. API Retry Logic

   • Add exponential backoff retry to all API calls
   • Implement circuit breaker pattern
   • Cache responses where appropriate

3. Resource Optimization

   • Reduce concurrent database connections
   • Implement request queuing
   • Add memory monitoring

10. Performance Improvements

Email System

• MinIO-First Architecture: Load cached emails instantly
• Background Sync: Update emails asynchronously
• Incremental Updates: Only fetch new emails
• Connection Reuse: Pool IMAP connections

API Optimization

• Request Batching: Combine multiple API calls
• Response Caching: Cache frequently accessed data
• Lazy Loading: Load data only when needed
• Debouncing: Prevent excessive API calls

Database Optimization

• Connection Pooling: Reuse database connections
• Query Optimization: Optimize NocoDB queries
• Batch Operations: Update multiple records at once

Implementation Priority

Phase 1: Critical Fixes (Immediate)

1. EOI deletion and database cleanup
2. Session management fixes
3. 502 error mitigation

Phase 2: User Experience (This Week)

1. Hide berth recommendations
2. Fix phone input country selection
3. Email attachment display
4. UI improvements (buttons, sliders)

Phase 3: Performance (Next Week)

1. Complete MinIO email implementation
2. API optimization
3. Connection pooling improvements

Testing Requirements

Unit Tests

• EOI deletion flow
• Email sync service
• Session management

Integration Tests

• IMAP connection with retry
• MinIO caching
• Concurrent operations

Performance Tests

• API response times
• Connection pool limits
• Memory usage under load

Monitoring

Metrics to Track

• 502 error frequency
• API response times
• IMAP connection success rate
• Memory/CPU usage
• Active connections count

Alerts

• 502 errors above threshold
• Connection pool exhaustion
• High memory usage
• Failed email syncs

Additional Recommendations

1. Error Handling

   • Implement global error handler
   • User-friendly error messages
   • Automatic error reporting

2. Logging

   • Structured logging for debugging
   • Request/response logging
   • Performance metrics logging

3. Caching Strategy

   • Redis for session management
   • MinIO for email caching
   • Memory cache for frequent queries

4. Architecture Improvements

   • Message queue for async operations
   • WebSocket for real-time updates
   • Service worker for offline support