Skip to main content

ArangoDB Integration Plan

This document outlines the detailed implementation plan for integrating ArangoDB into the Runway Calculator application.

Overview​

The Runway Calculator needs robust data persistence, synchronization, and version control capabilities. ArangoDB will serve as our primary database, offering:

  1. Cloud-based storage for scenarios
  2. Multi-user collaboration features
  3. Version history and audit trails
  4. Backup and disaster recovery
  5. Multi-device synchronization

Database Schema​

Collections​

  1. users - User accounts and profiles

    • _key: User ID (UUID)
    • username: Login username
    • email: User email
    • password_hash: Secure password hash
    • display_name: User's display name
    • created_at: Account creation timestamp
    • last_login: Last login timestamp
    • verified: Email verification status
    • roles: Array of user roles

  2. scenarios - Financial scenarios

    • _key: Scenario ID (UUID)
    • name: Scenario name
    • owner_id: Reference to user ID
    • data: Full scenario JSON data
    • created_at: Creation timestamp
    • updated_at: Last update timestamp
    • version: Current version number
    • is_template: Whether this is a template scenario
    • parent_scenario_id: For scenarios created from templates

  3. scenario_versions - Version history for scenarios

    • _key: Version ID (UUID)
    • scenario_id: Reference to scenario ID
    • version_number: Sequential version number
    • data: Full scenario JSON at this version
    • created_at: Version creation timestamp
    • created_by: User who created this version
    • change_description: Optional description of changes

  4. backups - Dedicated backup collection

    • _key: Backup ID (UUID)
    • scenario_id: Reference to scenario ID
    • data: Full scenario JSON at backup time
    • created_at: Backup timestamp
    • created_by: User who created the backup
    • backup_type: "automatic", "manual", "scheduled"
    • reason: Optional reason for backup
    • metadata: Additional backup metadata

  5. scenario_access - Sharing and permissions

    • _key: Access ID (UUID)
    • scenario_id: Reference to scenario ID
    • user_id: Reference to user ID
    • access_type: "owner", "editor", "viewer"
    • granted_at: When access was granted
    • granted_by: User who granted the access

  6. audit_log - Change tracking and audit trail

    • _key: Log ID (UUID)
    • user_id: User who made the change
    • timestamp: When the change occurred
    • resource_type: "scenario", "user", etc.
    • resource_id: ID of affected resource
    • action: "create", "update", "delete", "share", etc.
    • before: Optional state before change
    • after: Optional state after change
    • ip_address: IP address of request
    • device_id: Device identifier

  7. devices - Device registration for sync

    • _key: Device ID (UUID)
    • user_id: Reference to user ID
    • device_name: Human-readable device name
    • device_type: "desktop", "mobile", "tablet"
    • last_sync: Last synchronization timestamp
    • last_ip: Last IP address
    • user_agent: Browser/device user agent
    • created_at: First seen timestamp

Implementation Plan​

Phase 1: Basic Connectivity and Configuration​

  1. Update configuration with ArangoDB connection details
  2. Support both local development and cloud environment
  3. Add connection health checks and retry logic
  4. Set up authentication and session management

Phase 2: Synchronization and Persistence​

  1. Enhance ScenarioService for cloud storage
  2. Implement robust two-way synchronization
  3. Add conflict resolution for concurrent edits
  4. Optimize for large datasets with batching
  5. Add progress indicators for sync operations

Phase 3: Backup and Versioning​

  1. Implement real ArangoDB backup functionality
  2. Create UI for viewing and restoring backups
  3. Set up automatic versioning for all edits
  4. Add metadata to version history for context
  5. Implement point-in-time scenario restoration

Phase 4: Logging and Audit Trails​

  1. Create comprehensive audit logging
  2. Track all scenario operations with user details
  3. Record detailed change information
  4. Implement diff tracking for scenario versions
  5. Create UI for browsing change history

Phase 5: Disaster Recovery​

  1. Set up scheduled backups with verification
  2. Implement backup rotation and retention policies
  3. Create restoration procedures and testing
  4. Document disaster recovery processes
  5. Support point-in-time recovery from backups

Phase 6: Multi-Device Synchronization​

  1. Implement device registration and tracking
  2. Add device-specific sync status monitoring
  3. Create advanced conflict resolution for multi-device edits
  4. Support device-specific permissions and settings
  5. Add notification system for changes from other devices

Testing Strategy​

  1. Create mock implementations for offline testing
  2. Develop integration tests for ArangoDB operations
  3. Set up continuous testing in both local and cloud environments
  4. Implement scenario-based testing for complex sync cases
  5. Add performance testing for large datasets

Rollout Plan​

  1. Deploy to development environment with local ArangoDB
  2. Test thoroughly with synthetic data
  3. Deploy to staging with cloud ArangoDB instance
  4. Conduct user acceptance testing (UAT)
  5. Deploy to production on Google Cloud Platform (GCP)
  6. Monitor and adjust based on performance metrics

Future Enhancements​

  1. Add caching layer for improved performance
  2. Implement database sharding for horizontal scaling
  3. Add real-time collaborative editing features
  4. Enhance analytics with time-series data
  5. Create advanced backup export/import options