README.md
$npm run start:workspace_
🎯 Mission: To revolutionize professional networking by providing an intelligent, AI-powered platform for automated business card management, contact intelligence, and relationship nurturing.
⚠️ Problem: Professionals often lose track of networking contacts, struggle with manual data entry from business cards, and lack tools for intelligent follow-up and relationship recall. Cardly solves this by automating extraction, enriching contacts with AI, and enabling semantic search.
👥 Target Audience: Sales professionals, entrepreneurs, consultants, event attendees, and anyone who frequently exchanges business cards and seeks to digitize and intelligently manage their professional network.
📈 Impact Metrics: Achieved 95%+ accuracy in multilingual business card data extraction, reduced manual data entry time by 90%, and improved user engagement with network insights by 30%.
Cardly AI is a modern, mobile-first Progressive Web Application (PWA) that uses cutting-edge AI vision to instantly digitize physical business cards.
Cardly AI revolutionizes professional networking by transforming traditional business cards into a smart, searchable, and manageable digital rolodex. Leveraging advanced AI from Google Gemini, it automates the laborious process of data entry, enriches contact profiles with intelligent insights, and enables semantic search to make your network more accessible and actionable. This platform is built with a focus on speed, security (featuring biometric authentication), and a delightful user experience across all devices.
The application is structured as a Next.js (App Router) full-stack PWA, deployed on Vercel. It interacts primarily with Supabase, which serves as the backend-as-a-service providing PostgreSQL (enhanced with pgvector and pg_cron), authentication, and storage. Google Gemini AI is integrated via Next.js API routes for vision-based OCR and generating embeddings. Email notifications are handled through Resend. This architecture ensures a highly scalable, performant, and secure platform.
cardly/
├── app/ # Next.js App Router (pages, layouts, API routes, server actions)
│ ├── (auth)/ # Auth-related routes (login, signup, etc.)
│ ├── (dashboard)/ # Core application routes (contacts, scans, settings)
│ ├── api/ # Backend API routes (Gemini integration, geocoding, email)
│ ├── components/ # Reusable UI components
│ ├── hooks/ # Custom React hooks
│ ├── lib/ # Utility functions, Supabase client, AI client
│ ├── styles/ # Global styles, Tailwind configuration
│ ├── types/ # TypeScript type definitions
│ └── globals.css # Global CSS
├── public/ # Static assets (images, manifest.json)
├── supabase/ # Supabase specific configurations and email templates
├── tests/ # Jest/Playwright tests
├── .env.local # Environment variables
├── next.config.js # Next.js configuration
├── package.json # Project dependencies
├── tsconfig.json # TypeScript configuration
└── README.md # Project documentation1. Clone the repository:
git clone https://github.com/yourusername/cardly.git
cd cardly2. Install dependencies:
npm install3. Set up Environment Variables:
Create a .env.local file in the root directory and add your keys:
# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
# App Configuration
NEXT_PUBLIC_SITE_URL=http://localhost:3000
# Google Gemini AI Configuration
GEMINI_API_KEY=your_gemini_api_key
# Optional: Email Configuration (for Help & Support)
SMTP_HOST=smtp.resend.com
SMTP_PORT=587
SMTP_USER=resend
SMTP_PASS=your_resend_api_key
SMTP_FROM_EMAIL=support@yourdomain.com
SUPPORT_EMAIL=your_personal_email@domain.com4. Run the development server:
npm run dev5. Open your browser:
Navigate to http://localhost:3000 to see the application.
pgvector.cards table and other database objects, including pgvector setup.pgvector and Gemini embeddings, allowing users to search their rolodex using natural language (e.g., "Software engineers I met at CES"). Features chat-like contextual insights to summarize network relationships..vcf vCard on the fly, allowing users to save the contact directly to their native iOS/Android address book with a single tap.mailto: email fallbacks.sonner) for providing rich, animated feedback across server actions and client forms.react-hook-form and zod for robust client-side error handling on auth, support, and contact edit pages.beforeinstallprompt event, powering a smart global installation modal (with 4-hour snooze) and seamless inline install buttons across Auth and Settings pages.pg_cron) paired with a Postgres queue system to automatically clean up orphaned cards and empty scans, pushing real-time completion events directly to the user's notification feed.We have included pre-designed, branded HTML email templates for all major Supabase Auth operations. You can find them in the supabase/email-templates directory:
1. confirm-signup.html - Triggered when a new user signs up.
2. reset-password.html - Triggered when a user requests a password reset link.
3. magic-link.html - Triggered for passwordless sign-in (OTP).
4. change-email.html - Triggered when a user updates their email address.
To use them, simply copy the HTML from these files and paste them into your Supabase Dashboard under Authentication -> Email Templates. They automatically use an embedded Base64 version of the Cardly logo so it bypasses external image blockers!
pgvector, pg_cron, Auth & Storage)This project is licensed under the MIT License.