A sophisticated newsletter management application built with Next.js 15, TypeScript, and modern web technologies. ScrollOS helps you organize, read, and manage newsletters from multiple email accounts with intelligent categorization and powerful filtering capabilities.

(... rest of the content replaced with ScrollOS ...)

• Secure Authentication: Email/password authentication with bcrypt hashing
• Two-Factor Authentication: TOTP-based 2FA with backup codes
• Session Management: JWT-based sessions with secure token handling
• Password Reset: Secure password reset flow with email verification

• Multi-Provider Support: Connect Gmail and Outlook accounts
• OAuth 2.0 Integration: Secure OAuth flow for email providers
• Automatic Sync: Background synchronization with configurable intervals
• Smart Newsletter Detection: AI-powered newsletter identification using:
  • Content pattern analysis
  • Sender domain recognition
  • Email structure analysis
  • Newsletter service detection (Mailchimp, Substack, etc.)

• Smart Categorization: Automatic categorization based on sender, subject, and content
• Custom Categories: Create and manage personal categories with color coding
• Advanced Filtering: Powerful filtering system with:
  • Full-text search across content, subjects, and senders
  • Read/unread status filtering
  • Starred/unstarred filtering
  • Date range filtering (today, week, month)
  • Category-based filtering
  • Multi-sort options (date, sender, subject)
• Bulk Operations: Archive, star, and categorize multiple newsletters
• Whitelist Management: Whitelist specific domains and email addresses

• Multiple Reading Modes:
  • Normal Mode: Standard reading interface
  • Focus Mode: Distraction-free reading with minimal UI
  • Fullscreen Mode: Immersive reading experience
• Customizable Typography: Adjustable font size, line height, and reading width
• Reading Progress: Track reading progress with visual indicators
• Keyboard Shortcuts: Comprehensive keyboard navigation
• Reading Themes: Light, dark, and sepia themes

• Modern Design: Clean, intuitive interface inspired by modern email clients
• Responsive Layout: Optimized for desktop, tablet, and mobile devices
• Dark Mode Support: Automatic theme switching with system preference detection
• Accessibility: WCAG compliant with keyboard navigation and screen reader support
• Customizable Appearance: Personalize colors, spacing, and layout preferences

• Newsletter Rules: Create custom rules for automatic categorization and actions
• Pagination System:
  • Traditional pagination with page numbers
  • Load more mode for continuous scrolling
  • Smart loading states and error handling
• Real-time Sync: Live synchronization status with progress indicators
• Export Functionality: Export newsletters and user data
• Notification System: Configurable email and browser notifications

1. Visit the Signup Page: Navigate to /signup or click "Sign Up" on the homepage
2. Enter Your Details: Provide your email address and create a secure password
3. Verify Your Email: Check your inbox for a verification email and click the link
4. Complete Setup: You'll be redirected to the main dashboard

1. Navigate to Settings: Click the settings icon in the header or go to /settings/email
2. Add Email Account: Click "Connect Email Account"
3. Choose Provider: Select Gmail or Outlook
4. Authorize Access: Follow the OAuth flow to grant ScrollOS access to your emails
5. Configure Sync: Set sync frequency and enable/disable automatic syncing

1. Go to Categories: Navigate to /settings/categories or use the sidebar
2. Create Categories: Click "Add Category" to create custom categories
3. Customize Colors: Choose colors for easy visual identification
4. Set Rules: Create automatic categorization rules based on sender, subject, or content

• Sidebar: Navigation between folders (Inbox, Starred, Bin) and categories
• Newsletter List: Main area showing all newsletters with preview information
• Reading Pane: Right panel for reading selected newsletters
• Header: Search bar, account switcher, and sync status

• Click on newsletters to read them in the reading pane
• Use the sidebar to switch between different views
• Search bar for finding specific newsletters
• Filter button for advanced filtering options

1. Select a Newsletter: Click on any newsletter in the list
2. Reading Pane Opens: The newsletter content appears in the right panel
3. Reading Controls: Use the toolbar for navigation and actions
4. Keyboard Navigation: Use J/K or arrow keys to move between newsletters

1. Open Filters: Click the filter icon in the header
2. Search: Enter keywords to search across content, subjects, and senders
3. Status Filters: Filter by read/unread or starred/unstarred status
4. Date Range: Select time periods (today, this week, this month)
5. Categories: Choose specific categories to include
6. Sorting: Sort by date, sender, or subject in ascending/descending order

• Combine Filters: Use multiple filters together for precise results
• Clear Filters: Click "Clear All" to reset all filters
• Save Common Filters: Frequently used filter combinations are remembered
• Quick Search: Use the main search bar for instant results

1. Normal Mode: Standard interface with full toolbar and navigation
2. Focus Mode: Distraction-free reading with minimal UI elements
3. Fullscreen Mode: Immersive reading experience across the entire screen

• Font Size: Adjust text size using + and - buttons or keyboard shortcuts
• Line Height: Modify spacing between lines for better readability
• Reading Width: Control the maximum width of text for optimal reading
• Theme: Switch between light, dark, and sepia themes

1. Create Categories: Go to Settings > Categories and click "Add Category"
2. Assign Colors: Choose distinctive colors for easy identification
3. Automatic Categorization: Set up rules for automatic category assignment
4. Manual Assignment: Right-click newsletters to assign categories manually

• Star Newsletters: Click the star icon to mark important newsletters
• Archive Newsletters: Use the archive button to move newsletters to the bin
• Bulk Actions: Select multiple newsletters for batch operations
• Restore: Recover archived newsletters from the bin

1. Create Rules: Go to Settings > Rules to set up automatic actions
2. Define Conditions: Set criteria based on sender, subject, or content
3. Choose Actions: Automatically categorize, star, or move newsletters
4. Test Rules: Preview how rules will affect your newsletters

• Profile Information: Update your name, email, and profile picture
• Password Management: Change your password and enable two-factor authentication
• Account Security: Review login history and manage active sessions

• Default Reading Mode: Set your preferred reading mode
• Typography Settings: Configure default font size, line height, and width
• Theme Preferences: Choose light, dark, or system theme
• Auto-mark as Read: Enable automatic marking of newsletters as read

• Theme: Choose between light, dark, and system themes
• Accent Color: Customize the primary color of the interface
• Layout Options: Adjust sidebar visibility and compact mode
• Animations: Enable or disable interface animations

• Email Notifications: Configure email alerts for new newsletters
• Browser Notifications: Enable desktop notifications
• Quiet Hours: Set times when notifications are disabled
• Digest Options: Choose daily or weekly digest emails

1. Go to Email Settings: Navigate to Settings > Email
2. Add Account: Click "Connect Email Account" for each provider
3. Authorize Access: Complete OAuth flow for each account
4. Configure Sync: Set individual sync settings for each account

• Manual Sync: Click the sync button to manually refresh newsletters
• Auto Sync: Enable automatic background synchronization
• Sync Frequency: Set how often accounts should sync (hourly, daily, etc.)
• Sync Status: Monitor sync progress and troubleshoot issues

1. Domain Whitelist: Add trusted domains for newsletter import
2. Email Whitelist: Whitelist specific email addresses
3. Import Control: Choose which emails to import as newsletters
4. Filter Settings: Configure automatic filtering rules

• Reading Statistics: Track your reading habits and progress
• Category Distribution: See how newsletters are distributed across categories
• Sync History: Monitor email account synchronization
• Storage Usage: Check how much space your newsletters are using

1. Export Newsletters: Download newsletters in various formats
2. Data Backup: Export your account data for safekeeping
3. Import Options: Import newsletters from other services
4. Account Migration: Transfer data between accounts

• Global Shortcuts: Use keyboard shortcuts throughout the application
• Reading Shortcuts: Navigate and control reading experience
• Search Shortcuts: Quick access to search and filtering
• Custom Shortcuts: Configure your own keyboard shortcuts

Sync Problems

• Check your internet connection
• Verify email account credentials
• Review sync settings and frequency
• Check for API rate limits

Reading Issues

• Clear browser cache and cookies
• Try different reading modes
• Check font size and theme settings
• Disable browser extensions that might interfere

Performance Issues

• Reduce the number of newsletters loaded
• Use pagination instead of load more mode
• Clear browser cache
• Check available system resources

1. Check Documentation: Review this user guide and FAQ
2. Contact Support: Use the help section in settings
3. Report Issues: Submit bug reports through the feedback form
4. Community: Join discussions for tips and solutions

• Use Categories: Create meaningful categories for different types of newsletters
• Regular Cleanup: Archive old newsletters to keep your inbox manageable
• Star Important: Use starring to mark newsletters you want to revisit
• Set Rules: Create automatic rules to reduce manual organization

• Keyboard Shortcuts: Learn and use keyboard shortcuts for faster navigation
• Reading Mode: Use focus mode for distraction-free reading
• Batch Processing: Process newsletters in batches rather than one by one
• Search Regularly: Use search to find specific content quickly

• Whitelist Wisely: Only whitelist trusted sources to avoid spam
• Monitor Sync: Regularly check sync status and troubleshoot issues
• Backup Data: Export important newsletters and settings regularly
• Update Settings: Review and update preferences as your needs change

• Frontend: Next.js 15 with App Router, React 19, TypeScript
• Styling: Tailwind CSS 4.0 with custom design system
• Database: PostgreSQL with Drizzle ORM
• Authentication: NextAuth.js with custom credentials provider
• Email Integration: Gmail API, Microsoft Graph API
• UI Components: Radix UI primitives with custom components
• State Management: React hooks with custom state management
• Deployment: Vercel-ready with optimized build configuration

-- Core tables
newsletters (id, userId, emailAccountId, title, sender, subject, content, isRead, isStarred, isArchived, categoryId, receivedAt, ...)
users (id, email, password, twoFactorSecret, twoFactorEnabled, ...)
emailAccounts (id, userId, provider, email, accessToken, refreshToken, ...)
categories (id, userId, name, color, icon, isSystem, ...)

-- Authentication tables
accounts, sessions, verificationTokens, passwordResets

-- Configuration tables
userPreferences, newsletterRules, userNewsletterDomainWhitelist, userNewsletterEmailWhitelist

newsletter-product/
├── app/                    # Next.js App Router pages
│   ├── api/               # API routes
│   ├── auth/              # Authentication pages
│   ├── inbox/             # Main inbox interface
│   └── settings/          # User settings pages
├── components/            # Reusable UI components
│   ├── ui/               # Base UI components
│   ├── layout/           # Layout components
│   └── auth/             # Authentication components
├── lib/                  # Core utilities and services
│   ├── db.ts            # Database connection
│   ├── auth.ts          # Authentication configuration
│   ├── schema.ts        # Database schema
│   └── services/        # Business logic services
├── hooks/               # Custom React hooks
├── types/               # TypeScript type definitions
└── drizzle/             # Database migrations

• Node.js 18+
• PostgreSQL database
• Gmail/Outlook API credentials

1. Clone the repository

   git clone https://github.com/yourusername/newsletter-product.git
   cd newsletter-product

2. Install dependencies

   npm install

3. Set up environment variables

   cp .env.example .env.local

   Configure the following variables:

   # Database
   DATABASE_URL="postgresql://user:password@localhost:5432/newsletter_db"
   
   # Authentication
   NEXTAUTH_SECRET="your-secret-key"
   NEXTAUTH_URL="http://localhost:3000"
   
   # Email Providers
   GMAIL_CLIENT_ID="your-gmail-client-id"
   GMAIL_CLIENT_SECRET="your-gmail-client-secret"
   OUTLOOK_CLIENT_ID="your-outlook-client-id"
   OUTLOOK_CLIENT_SECRET="your-outlook-client-secret"
   
   # Email Service
   SMTP_HOST="smtp.gmail.com"
   SMTP_PORT="587"
   SMTP_USER="[email protected]"
   SMTP_PASS="your-app-password"

4. Set up the database

   # Run migrations
   npm run db:migrate
   
   # (Optional) Reset database
   npm run reset-db

5. Start the development server

   npm run dev

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

1. Create PostgreSQL database

   CREATE DATABASE newsletter_db;

2. Run migrations

   npm run db:migrate

3. View database with Drizzle Studio

   npm run db:studio

1. Go to Google Cloud Console
2. Create a new project or select existing one
3. Enable Gmail API
4. Create OAuth 2.0 credentials
5. Add authorized redirect URIs: http://localhost:3000/api/email/callback
6. Copy Client ID and Client Secret to environment variables

1. Go to Microsoft Azure Portal
2. Register a new application
3. Add Microsoft Graph API permissions (Mail.Read)
4. Create client secret
5. Add redirect URI: http://localhost:3000/api/email/callback
6. Copy Application ID and Client Secret to environment variables

1. Create Account: Sign up with your email address
2. Connect Email: Add your Gmail or Outlook account
3. Configure Categories: Create custom categories for organization
4. Set Preferences: Customize reading and appearance settings

1. View Inbox: Browse newsletters in the main inbox
2. Filter & Search: Use advanced filters to find specific newsletters
3. Read: Click on newsletters to read in the reading pane
4. Organize: Star, archive, or categorize newsletters
5. Sync: Monitor sync status and manage email accounts

• J / → - Next newsletter
• K / ← - Previous newsletter
• S - Toggle star
• E - Archive newsletter
• R - Toggle reading mode
• F - Toggle fullscreen
• + / - - Increase/decrease font size
• 0 - Reset font size
• ? - Show keyboard shortcuts
• / - Focus search
• Esc - Close modals, exit fullscreen

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

# Database
npm run db:push         # Push schema changes
npm run db:migrate      # Run migrations
npm run db:studio       # Open Drizzle Studio
npm run reset-db        # Reset database

# Code Quality
npm run lint            # Run ESLint
npm run lint:fix        # Fix linting issues
npm run format          # Format code with Prettier
npm run type-check      # TypeScript type checking

• TypeScript: Strict mode enabled
• ESLint: Airbnb configuration with custom rules
• Prettier: Consistent code formatting
• Conventional Commits: Standardized commit messages

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

1. Connect Repository: Link your GitHub repository to Vercel
2. Configure Environment: Add all environment variables
3. Deploy: Vercel will automatically deploy on push to main branch

1. Build the application

   npm run build

2. Set up production database

   npm run db:migrate

3. Start the server

   npm start

Ensure all environment variables are set in your production environment:

• Database connection string
• Authentication secrets
• Email provider credentials
• SMTP configuration

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 TypeScript best practices
• Write meaningful commit messages
• Add tests for new features
• Update documentation as needed
• Ensure accessibility compliance

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

• Next.js Team for the amazing framework
• Vercel for hosting and deployment
• Tailwind CSS for the utility-first CSS framework
• Drizzle ORM for type-safe database operations
• Radix UI for accessible component primitives

• Documentation: Wiki
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [email protected]

Made with ❤️ by the ScrollOS Team

This app uses Upstash Redis for caching and real-time features (sync progress, onboarding state, etc).

• Create a free Upstash Redis database: https://upstash.com/
• Copy your REST URL and REST TOKEN from the Upstash console.
• Set the following environment variables in your .env.local or deployment environment:
  • UPSTASH_REDIS_REST_URL (your Upstash Redis REST URL)
  • UPSTASH_REDIS_REST_TOKEN (your Upstash Redis REST token)

• Upstash Redis is used for:
  • Caching onboarding state
  • Caching categories and stats
  • Storing sync progress for real-time updates

No manual setup is needed beyond creating an Upstash Redis database and setting the environment variables.

For more details, see the Upstash Redis documentation.