Vaulty

Vaulty — Technical App Architecture Deep-Dive

This document details the internal architecture, design patterns, state flow, cryptographic safeguards, and native platform integration of Vaulty.

1. Architectural Layers & Structure

Vaulty follows clean, modular architectural boundaries:

lib/
├── app/                  # Application composition, routing (GoRouter), live bootstrap
├── core/
│   ├── l10n/             # Internationalization engine (AppStrings, hi.dart, en)
│   ├── theme/            # Pixel-inspired Material 3 tokens, colors, typography, abstract art
│   ├── utils/            # Formatters (dates, file sizes, mime types)
│   └── widgets/          # Atomic reusable UI components (AppCard, AppButton, NoticeCenter)
├── domain/
│   ├── models/           # Pure domain models (Document, StorageInfo, SearchFilter, AuditEvent)
│   └── repositories/     # Repository interfaces (DocumentRepository, AuthRepository, SearchRepository)
├── data/
│   ├── cache/            # Hardware-backed AES-256-GCM local encrypted cache & envelopes
│   ├── device/           # Native bridges (biometrics, notifications, sharing, file validation)
│   ├── drive/            # Google Drive v3 REST API implementation, OAuth verification, metadata codec
│   └── mock/             # Fixtures and deterministic test scenarios
└── features/
    ├── auth/             # Login, account gate, biometric lock screen
    ├── home/             # Home shell, storage quota card, abstract card banner, recents
    ├── documents/        # Document list/grid, live file preview, metadata details, quick actions
    ├── search/           # Filter chips, instant query matching, advanced search sheet
    ├── upload/           # Intake sheets (camera, gallery, files), document metadata forms
    ├── imports/          # Android SEND share-intent review and batch staging
    ├── settings/         # Appearance, language selector, cache controls, reminders, danger zone
    └── trash/            # Soft-delete management, restore, and 30-day sync purge

2. State Management & Provider Graph

Vaulty utilizes Riverpod 2.6 for reactive, decoupled, compile-safe dependency injection and state management.

graph TD
    Auth[authProvider: Google User State] --> DocRepo[documentRepositoryProvider]
    Auth --> DriveAPI[driveApiProvider]
    Auth --> Cache[vaultCacheProvider]
    
    DocRepo --> DocList[documentListProvider: Active Files]
    DocRepo --> TrashList[trashListProvider: Deleted Files]
    DocRepo --> StorageInfo[storageInfoProvider: Drive Quota]
    
    DocList --> FilteredDocs[filteredDocumentsProvider]
    SearchFilter[searchFilterProvider] --> FilteredDocs
    
    FilteredDocs --> HomeRecents[homeRecentsProvider]
    FilteredDocs --> DocumentScreen[Documents Screen View]
    
    UiPref[uiPreferencesProvider: Theme / Language] --> ThemeMode[AppTheme & Locale]

Key Provider Design Patterns:

3. Storage & Google Drive API v3 Protocol

Vaulty interacts with Google Drive’s REST API v3 using direct client-side HTTP calls (lib/data/drive/drive_api.dart).

Google Drive Metadata Schema

Documents are stored with canonical metadata mapped directly to Google Drive properties:

{
  "name": "Passport_Front.pdf",
  "mimeType": "application/pdf",
  "parents": ["appDataFolder"],
  "properties": {
    "vaulty_owner": "Aditya Chaudhari",
    "vaulty_tags": "travel,id,passport",
    "vaulty_kind": "pdf",
    "vaulty_uploaded_at": "2026-10-15T10:00:00.000Z",
    "vaulty_renewal_date": "2028-05-15",
    "vaulty_deleted_at": null
  }
}

Resumable Chunked Upload Protocol

For files up to 50 MB:

  1. Initiate session with POST https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable.
  2. Stream binary payload in 256 KB aligned chunks with Content-Range headers.
  3. Handle transient network drops through exponential backoff retry.

4. Hardware-Backed Cryptographic Engine

Vaulty employs authenticated encryption (AES-256-GCM) for all files cached on the local Android filesystem.

Encryption Pipeline:

  1. Master Key Generation: A 256-bit AES master key is generated via the hardware-backed AndroidKeyStore provider.
  2. Encrypted Envelope: When a document is downloaded for preview or offline reading:
    • A unique 96-bit Initialization Vector (IV) is generated per file.
    • The document payload is encrypted using AES-GCM.
    • The resulting payload, 128-bit authentication tag, and cryptographic metadata are saved inside the application’s private internal storage (/data/user/0/in.teamparadox.vaulty/cache/).
  3. Decryption on Demand: When opening in an external app, a transient decrypted copy is created strictly inside the private FileProvider directory and marked for deletion upon app pause.

5. Native Platform Bridge (MainActivity.kt)

The Android host communicates with Flutter via dedicated MethodChannel and EventChannel pipelines:

  1. Native PDF Preview Rendering:
    • android.graphics.pdf.PdfRenderer opens the local PDF and rasterizes the first page into an in-memory Bitmap.
    • The bitmap bytes are returned directly to Flutter as a Uint8List, eliminating the need for heavy external viewing plugins.
  2. Share Intent Interception:
    • MainActivity.kt handles Intent.ACTION_SEND and Intent.ACTION_SEND_MULTIPLE.
    • Content URIs from external apps (WhatsApp, Chrome, Gmail) are opened using Android’s ContentResolver, verified, copied into temporary sandboxed storage, and dispatched into Flutter’s incomingShareProvider.
  3. Device Boot & Renewal Alarms:
    • BootReceiver.kt listens to android.intent.action.BOOT_COMPLETED.
    • On reboot, the native receiver invokes Flutter’s background renewal registration task to re-arm all pending document expiry alarms with Android’s AlarmManager.

6. Internationalization & String Interpolation

Vaulty features an in-house, zero-dependency localization engine (AppStrings & hi.dart) optimized for performance and strict user data privacy.

This site is open source. Improve this page.