LeafLyx - E-Book Marketplace

A modern e-commerce platform for selling and distributing e-books with subscription-based access, built with Next.js 14, Clerk authentication, Stripe payments, and Supabase.

🚀 Features

Core E-commerce

• Book Catalog: Browse, search, and filter books by category, author, price, and rating
• Shopping Cart: Add, remove, and manage cart items with format selection
• Secure Payments: Stripe integration for one-time purchases and subscriptions
• File Management: Cloudflare R2 integration for secure file storage and delivery

Subscription System

• Flexible Plans: Basic ($9/month), Standard ($15/month), Annual ($59/year)
• Access Control: Book access based on subscription status and usage limits
• Premium Features: Download capabilities with premium add-on
• Usage Tracking: Monitor books consumed vs. subscription limits

User Experience

• Authentication: Clerk-powered user management with social login
• Responsive Design: Mobile-first approach with beautiful UI
• Search & Discovery: Advanced search with auto-suggestions
• Reviews & Ratings: User-generated reviews with helpful voting
• Wishlist: Save books for later purchase

Technical Features

• TypeScript: Full type safety throughout the application
• shadcn/ui: Modern, accessible UI components
• Performance: Optimized with Next.js App Router and Image optimization
• SEO: Meta tags, structured data, and sitemap generation
• Error Handling: Comprehensive error boundaries and user feedback

🛠️ Tech Stack

• Framework: Next.js 14 with App Router
• Language: TypeScript
• Styling: Tailwind CSS + shadcn/ui
• Authentication: Clerk
• Database: Supabase (PostgreSQL)
• Payments: Stripe
• File Storage: Cloudflare R2
• State Management: React Query + React Hook Form
• Validation: Zod
• Deployment: Vercel

📦 Installation

1. Clone the repository

   git clone <repository-url>
   cd leaflyx

2. Install dependencies

   npm install

3. Set up environment variables Create a .env.local file in the root directory:

   # Database
   DATABASE_URL=your_supabase_database_url
   NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
   NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
   SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key
   
   # Authentication
   CLERK_SECRET_KEY=your_clerk_secret_key
   NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_clerk_publishable_key
   CLERK_WEBHOOK_SECRET=your_clerk_webhook_secret
   
   # Payments
   STRIPE_SECRET_KEY=your_stripe_secret_key
   NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=your_stripe_publishable_key
   STRIPE_WEBHOOK_SECRET=your_stripe_webhook_secret
   
   # File Storage
   CLOUDFLARE_ACCOUNT_ID=your_cloudflare_account_id
   CLOUDFLARE_R2_ACCESS_KEY=your_r2_access_key
   CLOUDFLARE_R2_SECRET_KEY=your_r2_secret_key
   CLOUDFLARE_R2_BUCKET_NAME=your_r2_bucket_name
   CLOUDFLARE_R2_ENDPOINT=your_r2_endpoint
   
   # External APIs
   GOOGLE_BOOKS_API_KEY=your_google_books_api_key
   
   # Application
   NEXT_PUBLIC_APP_URL=http://localhost:3000
   NEXT_PUBLIC_APP_NAME="LeafLyx"

4. Set up the database

   • Create a Supabase project
   • Run the SQL schema from schema.sql in your Supabase SQL editor
   • Configure Row Level Security (RLS) policies

5. Configure Clerk

   • Create a Clerk application
   • Set up authentication routes and webhooks
   • Configure social login providers (optional)

6. Set up Stripe

   • Create a Stripe account
   • Configure webhook endpoints
   • Set up subscription products and prices

7. Configure Cloudflare R2

   • Create an R2 bucket
   • Set up API tokens with appropriate permissions
   • Configure CORS settings

8. Run the development server

npm run dev

9. Open your browser Navigate to http://localhost:3000

🏗️ Project Structure

src/
├── app/                          # Next.js App Router
│   ├── (auth)/                   # Auth group routes
│   ├── (main)/                   # Main app routes  
│   ├── api/                      # API routes
│   ├── globals.css
│   ├── layout.tsx
│   └── page.tsx                  # Homepage
├── components/                   # Reusable components
│   ├── ui/                       # shadcn/ui components
│   ├── auth/
│   ├── books/
│   ├── cart/
│   ├── layout/
│   └── subscription/
├── lib/                          # Utilities & configurations
├── hooks/                        # Custom React hooks
├── types/                        # TypeScript definitions
└── middleware.ts

🔧 Development

Available Scripts

• npm run dev - Start development server
• npm run build - Build for production
• npm run start - Start production server
• npm run lint - Run ESLint
• npm run type-check - Run TypeScript type checking

Code Style

• TypeScript: Strict typing throughout
• ESLint: Code linting with Next.js configuration
• Prettier: Code formatting (configured via ESLint)
• Components: Reusable, composable components
• Error Handling: Comprehensive error boundaries

Database Schema

The application uses a comprehensive PostgreSQL schema with the following main tables:

• users - User profiles and preferences
• books - Book metadata and pricing
• book_files - File storage information
• subscriptions - User subscription data
• user_book_access - Book access permissions
• carts & cart_items - Shopping cart functionality
• orders & order_items - Purchase history
• book_reviews & book_ratings - User reviews and ratings
• wishlists - User wishlist management

🚀 Deployment

Vercel Deployment

1. Connect your repository to Vercel
2. Configure environment variables in Vercel dashboard
3. Deploy - Vercel will automatically build and deploy your application

Environment Variables for Production

Make sure to set all required environment variables in your Vercel project settings:

• Database credentials
• Authentication keys
• Payment processing keys
• File storage credentials
• External API keys

Database Migration

For production deployment:

1. Run database migrations using the schema from schema.sql
2. Seed initial data (categories, subscription plans, etc.)
3. Configure RLS policies for security
4. Set up monitoring and logging

🔒 Security

Authentication & Authorization

• Clerk Integration: Secure user authentication with multi-factor support
• Role-Based Access: User, admin roles with specific permissions
• API Protection: JWT verification on all protected endpoints
• Session Management: Secure session handling

Data Protection

• Encryption: Data encrypted in transit and at rest
• PCI Compliance: Stripe handles all payment data
• File Security: Signed URLs for secure file access
• Rate Limiting: API rate limits to prevent abuse

File Access Security

• Access Verification: Verify user permissions before file access
• Signed URLs: Time-limited URLs for secure downloads
• Download Tracking: Log all download attempts
• Content Protection: DMCA compliance procedures

📊 Monitoring & Analytics

Performance Monitoring

• Core Web Vitals: Track loading performance
• API Response Times: Monitor backend performance
• Error Tracking: Comprehensive error logging
• User Analytics: Track user behavior and engagement

Business Metrics

• Subscription Conversion: Track subscription sign-ups
• Revenue Analytics: Monitor sales and revenue
• User Retention: Track user engagement over time
• Book Performance: Monitor popular titles and categories

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• TypeScript: Use strict typing for all new code
• Testing: Write tests for new features
• Documentation: Update documentation for API changes
• Code Review: All changes require code review
• Performance: Consider performance impact of changes

📄 License

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

🆘 Support

For support and questions:

• Documentation: Check the project documentation
• Issues: Create an issue in the GitHub repository
• Discussions: Use GitHub Discussions for questions
• Email: Contact the development team

🗺️ Roadmap

Phase 1 (Current)

• ✅ Core e-commerce functionality
• ✅ User authentication
• ✅ Subscription system
• ✅ File management

Phase 2 (Next)

• 🔄 In-browser reading experience
• 🔄 Enhanced recommendations
• 🔄 Social features (reviews, ratings)
• 🔄 Advanced search filters

Phase 3 (Future)

• 📋 Physical book marketplace
• 📋 Author/publisher portal
• 📋 Mobile app development
• 📋 API for third-party integrations

---

Built with ❤️ by the LeafLyx team