CardVault

CardVault is a Flutter app to capture, upload, OCR, and manage business cards across mobile and web.

Features

• Email/password authentication with Firebase Auth
• Add cards manually or by image upload/capture
• OCR extraction pipeline (mobile + web) with parser cleanup
• Cloudinary image hosting for card/profile images
• Firestore-backed card vault and profile storage
• Dashboard with active cards, vault images, and business type insights
• Dark/Light theme toggle with persisted preference
• Responsive auth UI with card-themed design and 3D background support (web)

Tech Stack

• Flutter (Dart)
• Firebase Auth
• Cloud Firestore
• Cloudinary (image upload + hosted URLs)
• Google ML Kit Text Recognition (mobile OCR)
• Tesseract.js (web OCR via JS interop)
• http package for API uploads/calls
• fl_chart for dashboard chart

Setup Instructions

1) Prerequisites

• Flutter SDK (3.x)
• Dart SDK (bundled with Flutter)
• Node.js + npm (only if using Firebase Functions)
• Firebase project configured for:
  • Authentication (Email/Password)
  • Cloud Firestore

2) Clone and install dependencies

git clone https://github.com/cybercomet-07/CardVault.git
cd CardVault
flutter pub get

3) Firebase config

This project expects lib/firebase_options.dart generated by FlutterFire.

If regenerating:

dart pub global activate flutterfire_cli
flutterfire configure

4) Cloudinary config

Update values in lib/core/services/storage_card_service.dart:

• _cloudName
• _uploadPreset (unsigned preset)

Then ensure upload preset is active in Cloudinary Console.

5) Run app

flutter run

For web:

flutter run -d chrome

Architecture Overview

The app uses a service-first Flutter architecture:

• UI in lib/features/*
• data models in lib/core/models/*
• reusable services in lib/core/services/*
• shared UI primitives in lib/core/widgets/*

Managed backend services handle identity and persistence:

• Firebase Auth for user sessions
• Firestore for card/profile documents
• Cloudinary for image files

Full system design: see architecture.md.

OCR Implementation

OCR is implemented in layered steps:

1. Image source: capture/upload card image
2. Platform OCR:
   • mobile: ML Kit (card_ocr_service_io.dart)
   • web: Tesseract.js (card_ocr_service_web.dart, web/index.html)
3. Text normalization + field extraction:
   • parser in card_text_parser.dart
   • extracts person, company, phone, email, website, address, business type
4. User review/edit + save

Fallback behavior:

• If one OCR path fails, app returns empty/null extraction without crashing.
• Manual edit remains available before save.

Search Implementation

Card data is stored in Firestore and surfaced through dashboard/cards views. Search/filtering is based on saved card fields and display state in app services/pages.

Core files:

• lib/features/cards/cards_page.dart
• lib/features/dashboard/dashboard_page.dart
• lib/core/services/firestore_card_service.dart

Project Structure

Primary active structure:

lib/
  app.dart
  main.dart
  features/
    auth/
    cards/
    dashboard/
    settings/
    splash/
  core/
    models/
    router/
    services/
    theme/
    widgets/
web/
  index.html

Note: repository also contains earlier scaffold/prototype folders (presentation/, data/, domain/, etc.) that are not part of the current main runtime flow.

Deployment

• GitHub repo: https://github.com/cybercomet-07/CardVault
• Suggested web deployment:
  • Firebase Hosting or similar static hosting for Flutter web build.

Known Limitations

• OCR accuracy is image-quality dependent; exact extraction for all cards is not guaranteed.
• Web camera/file behavior depends on browser capabilities and permissions.
• For enterprise-grade OCR accuracy, a server-side OCR pipeline can be added later.