CardNova MVP - Digital Business Cards

CardNova is a modern digital business card platform that allows professionals to create, share, and manage their digital business cards through QR codes. Built with Next.js 15, Supabase, and Tailwind CSS.

🌟 Features

Current MVP Features

• Free Digital Cards: Create one professional digital business card
• QR Code Sharing: Generate QR codes for instant sharing
• Mobile Optimized: Cards look great on all devices
• Contact Export: vCard download for easy contact saving
• Real-time Preview: See changes instantly while editing
• Secure Authentication: Powered by Supabase Auth
• Professional Design: Clean, modern interface

Planned Pro Features

• Multiple digital business cards
• Custom card templates and themes
• Analytics and view tracking
• Profile photos
• Social media links integration
• Remove CardNova branding
• Priority support

🚀 Quick Start

Prerequisites

• Node.js 18+
• A Supabase account (free tier works)

1. Clone and Install

git clone <your-repo-url>
cd cardnova-mvp
npm install

2. Set Up Supabase

1. Create a new project at supabase.com
2. Go to Project Settings > API
3. Copy your project URL and anon key
4. Run the database setup:
   • Go to your Supabase dashboard > SQL Editor
   • Copy and run the contents of database-setup.sql

3. Environment Configuration

cp .env.example .env.local

Edit .env.local with your values:

NEXT_PUBLIC_SUPABASE_URL=your-supabase-project-url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-supabase-anon-key
NEXT_PUBLIC_APP_URL=http://localhost:3000

4. Run the Development Server

npm run dev

Visit http://localhost:3000 to see your app!

🏗️ Project Structure

cardnova-mvp/
├── app/                    # Next.js App Router
│   ├── (auth)/            # Authentication pages
│   │   ├── login/
│   │   └── signup/
│   ├── dashboard/         # Protected dashboard pages
│   │   ├── cards/new/     # Card creation
│   │   └── card/[id]/edit/ # Card editing
│   ├── card/[slug]/       # Public card pages
│   ├── pricing/           # Pricing page
│   ├── layout.tsx         # Root layout
│   ├── page.tsx          # Homepage
│   └── globals.css       # Global styles
├── components/           # Reusable components
│   ├── ui/              # ShadCN UI components
│   ├── CardCreator.tsx
│   ├── CardEditor.tsx
│   ├── CardPreview.tsx
│   ├── QRCodeDisplay.tsx
│   └── ...
├── lib/                 # Utility libraries
│   ├── supabase/       # Supabase client configuration
│   └── providers/      # React providers
└── database-setup.sql  # Database schema

🎯 MVP Development Philosophy

This MVP focuses on proving the core value proposition: that people want digital business cards and will share them via QR codes. Every feature is designed around this goal.

Design Constraints

• Free tier limitation: One card per user (reduces complexity)
• Theme consistency: Uses only design system colors from globals.css
• Mobile-first: QR scanning happens on phones
• No-app-required: Works in any mobile browser
• Fast loading: Public cards must load instantly

Technology Choices

• Next.js 15: Full-stack React with App Router
• Supabase: Authentication, database, and real-time features
• TailwindCSS + ShadCN: Consistent, accessible UI components
• React Query: Efficient data fetching and caching
• QR Code: Client-side QR generation for better performance

🔧 Development Guidelines

Component Architecture

• Page components: Data fetching and layout only
• Feature components: Business logic and state management
• UI components: Pure presentation (from ShadCN)

Styling Rules

• Use theme classes: bg-background, text-foreground, etc.
• Avoid direct colors: No bg-blue-500, use bg-primary instead
• Spacing: Standard padding classes p-4, p-6, p-8
• Responsive: Mobile-first approach with sm:, md:, lg: breakpoints

Error Handling

• Show clear, actionable error messages
• Use ShadCN Alert components for consistency
• Implement loading states for all async operations
• Handle network failures gracefully

🚢 Deployment

Vercel (Recommended)

1. Push your code to GitHub
2. Connect repository to Vercel
3. Add environment variables in Vercel dashboard
4. Deploy automatically on push to main

Environment Variables for Production

NEXT_PUBLIC_SUPABASE_URL=your-production-supabase-url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-production-supabase-anon-key  
NEXT_PUBLIC_APP_URL=https://your-domain.com

Performance Checklist

• [ ] Public card pages load in <1 second
• [ ] QR codes work on iOS and Android
• [ ] vCard downloads work correctly
• [ ] Mobile responsive design tested
• [ ] Error boundaries implemented

📊 Success Metrics

The MVP succeeds when:

• Time to first card: <2 minutes from signup
• QR code reliability: Works on all major phone cameras
• Page load speed: Public cards <1s on 3G
• User completion: >80% complete card creation flow

🔮 Roadmap

Immediate Post-MVP

1. User feedback collection: In-app feedback forms
2. Analytics: Basic usage tracking
3. Performance optimization: Image optimization, caching
4. Mobile app: PWA features for offline QR access

Future Features

1. Team accounts: Multiple cards per organization
2. Card templates: Industry-specific designs
3. Integrations: CRM, email signatures, LinkedIn
4. Advanced QR codes: Dynamic QR codes, tracking
5. White-labeling: Custom branding for enterprises

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Follow the coding conventions in this README
4. Test your changes thoroughly
5. Submit a pull request

Coding Standards

• TypeScript strict mode enabled
• ESLint and Prettier configured
• Component props properly typed
• Error handling implemented
• Mobile responsiveness tested

📝 License

This project is licensed under the MIT License. See LICENSE file for details.

🆘 Support

• Documentation: This README and inline code comments
• Issues: GitHub Issues for bugs and feature requests
• Discussions: GitHub Discussions for questions

Built with ❤️ by the CardNova team. Making professional networking simple and digital.