A modern email client built with Next.js, Shadcn UI, and Supabase. This application provides a clean and intuitive interface for managing emails with features like authentication, real-time updates, and a responsive design.

• Modern UI with Shadcn UI components
• Authentication with Supabase (email/password + Google OAuth)
• Multi-account support for managing multiple email accounts
• Real-time email updates via Supabase subscriptions
• Responsive design that works on all devices
• Dark mode support with theme switching
• Rich text editor for email composition
• Advanced email management (folders, labels, priority, etc.)
• File attachments support
• Email scheduling and snoozing
• Search functionality with filters

This project follows a modular, feature-based architecture designed for scalability and maintainability:

src/
├── features/           # Feature-based modules
│   ├── auth/          # Authentication
│   ├── mail/          # Email functionality
│   ├── account/       # Account management
│   └── settings/      # User settings
├── components/         # Shared components
│   ├── ui/            # Base UI components
│   ├── common/        # Common business components
│   └── layout/        # Layout components
├── lib/               # Core utilities
│   ├── instant/       # InstantDB placeholders (frontend-only)
│   ├── constants/     # App constants
│   ├── types/         # Global types
│   └── validations/   # Validation schemas
└── app/               # Next.js App Router
    ├── (auth)/        # Auth route group
    ├── (dashboard)/   # Dashboard route group
    └── api/           # API routes

• Frontend: Next.js 14, React 18, TypeScript
• UI Framework: Shadcn UI (Radix UI primitives)
• Styling: Tailwind CSS
• Backend: Supabase (PostgreSQL, Auth, Real-time)
• Rich Text: TipTap editor
• State Management: React hooks + Context
• Validation: Zod schemas
• Icons: Lucide React

1. Clone the repository

   git clone <repository-url>
   cd Q-mail

2. Install dependencies

   npm install
   # or
   yarn install
   # or
   pnpm install

3. Set up environment variables

   cp .env.example .env.local

   Add your Supabase credentials:

   # Supabase removed. Placeholder envs will be added for InstantDB later.

4. Set up the database

   # Run Supabase migrations
   npx supabase db push

5. Start the development server

npm run dev
# or
yarn dev
# or
pnpm dev

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

Each feature is self-contained with its own components, hooks, services, and types:

• auth/ - Authentication, login, signup, password reset
• mail/ - Email composition, display, list, management
• account/ - Multi-account switching, profile management
• settings/ - User preferences, themes, notifications

• ui/ - Base UI components from Shadcn UI
• common/ - Shared business components (loading, error handling)
• layout/ - Layout components (header, sidebar, footer)

• instant/ - InstantDB placeholder clients (no network)
• constants/ - Application constants and configurations
• types/ - Global TypeScript type definitions
• validations/ - Zod validation schemas
• utils/ - General utility functions

# Development
npm run dev          # Start development server
npm run build        # Build for production
npm run start        # Start production server
npm run lint         # Run ESLint

# Database
npm run db:push      # Push database migrations
npm run db:reset     # Reset database
npm run db:seed      # Seed database with sample data

• Feature-based: Each feature has its own directory with components, hooks, services, and types
• Barrel exports: Clean imports using index files
• Type safety: Comprehensive TypeScript types throughout
• Validation: Zod schemas for form validation
• Error handling: Error boundaries and proper error states

1. Create a new feature directory in src/features/
2. Add the standard structure: components/, hooks/, services/, types/, utils/
3. Create an index.ts file for barrel exports
4. Add types to src/lib/types/ if needed
5. Add validation schemas to src/lib/validations/ if needed

# Run tests
npm run test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

• Architecture Guide - Detailed architecture documentation
• Migration Guide - Guide for updating imports after refactoring
• Refactoring Summary - Summary of the refactoring work

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

The app can be deployed to any platform that supports Next.js:

• Netlify
• Railway
• DigitalOcean App Platform
• AWS Amplify

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

• Follow the existing code structure and patterns
• Add proper TypeScript types
• Include validation schemas for forms
• Write tests for new features
• Update documentation as needed

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

• Next.js for the amazing React framework
• Shadcn UI for the beautiful component library // Supabase removed; backend will be rebuilt with InstantDB
• TipTap for the rich text editor
• Tailwind CSS for the utility-first CSS framework

If you have any questions or need help:

1. Check the documentation
2. Search existing issues
3. Create a new issue

Built with ❤️ using modern web technologies