Google Drive & Backup System
Relevant source files
The following files were used as context for generating this wiki page:
The Google Drive & Backup System is a core infrastructure component of CodeBot designed to ensure data persistence and user-driven data portability. It provides mechanisms for both manual and automated backups of code snippets, collections, and user preferences. The system integrates with the Google Drive API via OAuth 2.0 Device Authorization, allowing users to sync their data to a cloud storage provider directly from the Telegram interface or the WebApp.
This system encompasses a comprehensive backup lifecycle, including personal local backups (ZIP exports), scheduled cloud synchronization, and granular restore capabilities. It handles various data types, from small text-based snippets to large binary files, with specialized logic for deduplication and version control.
Sources: webapp/README.md, services/google_drive_service.py:1-50, webapp/templates/settings.html:113-130
## Core Architecture & Components
The backup system is divided into several layers: the service layer handling API interactions, the presentation layer managing UI interactions (Telegram and WebApp), and the storage layer for persistence.
### Google Drive Service
The GoogleDriveService is the central orchestration point for all Google Drive interactions. It manages the OAuth 2.0 flow, folder hierarchy creation, and file uploads. Key capabilities include:
- OAuth Management: Implements Device Authorization flow (
start_device_authorization,poll_device_token) and token persistence with encryption. - Path Resolution: Handles nested folder creation (
ensure_path) and ensures a default root folder (get_or_create_default_folder). - Resumable Uploads: Supports chunked, resumable uploads for improved reliability with larger files.
Sources: services/google_drive_service.py:53-150, services/google_drive_service.py:403-460, services/google_drive_service.py:588-660
### Backup Service & Local Persistence
Beyond cloud storage, the system supports personal local backups. Users can export their entire database state as a password-protected ZIP archive.
- Export/Import: Processes for generating full data snapshots and restoring them, including handling file overwrites or new version creation.
- Disk Backups: An automated server-side backup mechanism that saves copies to a local disk according to a user-defined schedule.
Sources: webapp/templates/settings.html:113-170, webapp/templates/settings.html:236-260
### Data Flow: Scheduled Backup
The following diagram illustrates the automated flow when a scheduled backup job is triggered.
The system prioritizes categories based on user preferences stored in drive_prefs.
Sources: handlers/drive/menu.py:65-180, services/google_drive_service.py:926-980
## Google Drive Integration
### Authentication Flow
The system uses the Google OAuth 2.0 Device Flow, which is ideal for bot interfaces where a traditional browser-based redirect may be complex.
### Storage Hierarchy & Filenaming
The system organizes files into a structured hierarchy within the user's Google Drive. By default, it creates a folder named גיבויי_קודלי (CodeBot Backups).
| Category | Subpath | Filename Pattern |
|---|---|---|
| ZIP | /zip | BKP_zip_[Entity]_v[Ver]_[Date].zip |
| All | /הכל | BKP_הכל_[BotLabel]_v[Ver]_[Date].zip |
| Repo | /לפי_ריפו/[RepoName] | BKP_by_repo_[RepoName]_v[Ver]_[Date].zip |
| Large | /קבצים_גדולים | BKP_קבצים_גדולים_[BotLabel]_v[Ver]_[Date].zip |
Sources: services/google_drive_service.py:488-510, services/google_drive_service.py:532-550
## Backup Management
### Automated Scheduling
Users can configure backup frequencies through the interface. The system supports various intervals handled by a background job queue.
- Available Intervals:
daily,every3(3 days),weekly,biweekly,monthly. - Job Persistence: Jobs are registered in the
job_registryand tracked viajob_trackerfor observability. - Smart Retries: On authentication failure during a scheduled job, the system notifies the user and requests re-authorization.
Sources: handlers/drive/menu.py:80-150, webapp/templates/settings.html:200-215
### Local Backup & Restore Logic
Local backups are managed via the WebApp settings.
- Deduplication: When uploading ZIPs to Drive, the system checks for existing
md5Checksumin the cloud or tracksuploaded_backup_idsin the database to prevent redundant transfers. - Restore Handling: During restoration, users can choose to overwrite existing files, which creates new versions in the database while preserving historical versions.
Sources: services/google_drive_service.py:726-800, webapp/templates/settings.html:132-155
## Database Schema: Drive Preferences
User-specific backup configurations are stored within the users collection under the drive_prefs field.
| Field | Type | Description |
|---|---|---|
target_folder_id | String | The Google Drive ID of the root backup folder. |
schedule | String | Current interval key (e.g., "weekly"). |
last_backup_at | ISO Date | Timestamp of the last successful backup. |
schedule_next_at | ISO Date | Planned timestamp for the next automated run. |
uploaded_backup_ids | Array[String] | List of local backup IDs already synced to Drive. |
drive_version_counters | Object | Version numbers for different backup categories. |
Sources: database/repository.py:1085-1120, services/google_drive_service.py:512-525
## Conclusion
The Google Drive & Backup System provides a resilient data safety net for CodeBot users. By combining manual exports with sophisticated cloud synchronization features like deduplication, resumable uploads, and automated scheduling, the system ensures that user code snippets and configurations are securely stored and easily recoverable across different platforms.
Sources: webapp/README.md, handlers/drive/menu.py:1033