# Best Homepage Ever (BHE) - LLM Context File

## Project Overview
Best Homepage Ever is a customizable homepage application serving thousands of daily users. It provides a personalized dashboard with widgets, weather information, financial data, and productivity tools, all with a focus on speed and dark theme UX.

**Current Version**: 3.8.4 (client), 3.1.4 (server)
**Status**: Production-ready, actively maintained
**Users**: 50,000+ daily active users
**Domain**: Production hosted on 74.208.51.207

## Tech Stack & Architecture

### Frontend (client/)
- **Framework**: Vue 3.5.18 + TypeScript + Vite
- **UI Library**: Vuetify 3.9.5 (Material Design)
- **State Management**: Pinia stores
- **Development Port**: http://localhost:8081 → http://localhost:3005
- **Build Tool**: Vite with HMR, PWA support

### Backend (server/)
- **Runtime**: Node.js + Express.js
- **Database**: MongoDB (development: localhost:27017/bhe, production: Atlas)
- **Caching**: Redis (session management, API caching)
- **Process Manager**: PM2 with clustering
- **External APIs**: OpenAI, Alpha Vantage (stocks), Google Places, Weather APIs

### Infrastructure
- **Production**: PM2 process named "BHE"
- **CDN**: Cloudflare
- **Authentication**: JWT with refresh tokens
- **File Storage**: AWS S3 for user uploads

## Project Structure

```
besthomepageever/
├── client/                    # Vue 3.5 frontend application
│   ├── src/
│   │   ├── components/        # Reusable UI components
│   │   ├── pages/            # Page-level components
│   │   ├── stores/           # Pinia state management
│   │   ├── widgets/          # Widget-specific components
│   │   └── icons/            # Custom SVG icon components
│   ├── public/               # Static assets
│   └── package.json          # Frontend dependencies
├── server/                   # Node.js backend
│   ├── routes/               # Express API endpoints
│   ├── models/               # MongoDB schemas (Mongoose)
│   ├── utils/                # Helper functions and utilities
│   ├── config/               # Database and environment config
│   └── package.json          # Backend dependencies
├── docs/                     # Project documentation
│   ├── HOMEPAGE_DEVELOPMENT.md   # Main development guide
│   ├── DEPLOYMENT_GUIDE.md       # Production deployment
│   ├── FINANCIAL_DASHBOARD_GUIDE.md  # Stock features
│   └── Justins/              # Personal developer notes
└── updates/                  # Update tracking and changelogs
```

## Core Features & Components

### Widget System
- **Widgets.vue**: Main grid display with drag-and-drop functionality
- **WidgetsModal.vue**: Add/edit widget dialog interface
- **Widget Types**: Default websites, custom user sites, productivity tools
- **Management**: Full CRUD operations, drag-and-drop reordering

### User Customization
- **Backgrounds**: Image uploads, color selection, auto-rotation
- **Display Settings**: Dark mode (primary), navbar visibility, auto-hide
- **Search Integration**: Multiple engines (Google, Bing, DuckDuckGo, Brave)
- **Personalization**: Widget sizing, title display, layout preferences

### Weather System
- **WeatherWidget.vue**: Smart location-based weather display
- **Location Sources**: Geolocation API, Google Places API custom selection
- **Data Flow**: Always fetch Fahrenheit → frontend unit conversion
- **Backend**: `/server/routes/weather.js` with Redis caching (30min TTL)
- **User Experience**: Permission-based, no preload, modal-aware visibility

### Financial/Stock Features
- **Stock Market Integration**: Real-time quotes via Alpha Vantage API
- **Mortgage Rates**: Current market rates display
- **Performance Optimization**: Intelligent caching, bulk API calls
- **Rate Limiting**: User activity-based refresh intervals

### Account System
- **Authentication**: JWT-based with automatic refresh
- **User Profiles**: Name, country, profile pictures, ranking system
- **Settings Sync**: Cross-device synchronization via database
- **Notes System**: Personal note-taking with full CRUD operations

## Database Schema (MongoDB)

### Primary Collections
- **users**: User accounts with embedded settings, widgets, notes
  - Fields: email, firstName, lastName, password, profilePicture, rank
  - Embedded: settings (backgrounds, display, search, widgets)
- **tickets**: Support system with notification integration
- **notifications**: User notifications with Redis caching
- **openais**: OpenAI chat integration records

### User Ranks
- **0**: Basic User (default)
- **1**: Admin/Owner (full system access)

## Development Guidelines

### Code Patterns
- **Vue Components**: `<script setup lang="ts">` pattern preferred
- **Component Naming**: PascalCase (`MyWidget.vue`)
- **Props & Events**: TypeScript interfaces with `defineProps()`
- **API Integration**: Async/await with proper error handling
- **Styling**: Vuetify components + scoped SCSS

### Performance Considerations
- **Homepage Speed**: Critical for 20k+ daily users
- **Lazy Loading**: Route-based code splitting
- **Caching Strategy**: Redis for API responses, localStorage for preferences
- **CSS Containment**: Prevent style leaks between components

### State Management
- **Pinia Stores**: Preferred for shared state
- **Component Communication**: Props down, events up
- **API Patterns**: Composables for reusable request logic

## Development Commands

### Quick Start
```bash
# Frontend development
cd client && npm run dev

# Backend development
cd server && npm run dev

# Check services
redis-cli ping
pm2 list
pm2 logs BHE --lines 50
```

### Build & Deploy
```bash
# Frontend build
cd client && npm run build

# Format code
npm run format  # Available in both client/ and server/

# Version management
npm run version:patch  # Increment patch version
```

## Environment Configuration

### Development (.env files)
```bash
# client/.env.development
VITE_API_BASE_URL=http://localhost:3005/api

# server/.env.development
MONGO_URI=mongodb://localhost:27017/bhe
REDIS_URL=redis://localhost:6379
ALPHA_VANTAGE_API_KEY=your_key_here
```

## API Structure

### Key Endpoints
- **Authentication**: `/api/auth/*` (login, register, refresh)
- **User Management**: `/api/users/*` (profile, settings, widgets)
- **Weather**: `/api/weather/*` (current conditions, forecasts)
- **Financial**: `/api/stocks/*`, `/api/mortgage-rates`
- **Notes**: `/api/notes/*` (CRUD operations)
- **Notifications**: `/api/notifications/*`

## Security & Best Practices

### Authentication Flow
1. JWT tokens with refresh mechanism
2. Secure password hashing (bcrypt)
3. Input validation on all endpoints
4. Rate limiting for API protection

### Data Protection
- No secrets in client-side code
- Environment variables for sensitive data
- Input sanitization for XSS prevention
- CORS configuration for API security

## Common Development Issues

### Database Connection
- **Issue**: Different local databases between machines
- **Solution**: Verify connection to correct database name (`bhe`)
- **Check**: User ranks and authentication working properly

### Admin Access
- **Setup**: Update user rank to 1 for admin features
- **Command**: Use provided Node.js script in HOMEPAGE_DEVELOPMENT.md

### CORS & API Issues
- **Frontend**: Ensure VITE_API_BASE_URL matches server
- **Backend**: Verify Express CORS configuration
- **Authentication**: Check JWT token expiry and refresh logic

## Performance & Optimization

### Frontend Optimization
- **Vue 3.5 Features**: Composition API, tree-shaking
- **Vite Benefits**: Fast HMR, optimized bundling
- **Component Caching**: Keep-alive for inactive components
- **Asset Optimization**: Image compression, font subsetting

### Backend Optimization
- **Redis Caching**: API responses, session data
- **MongoDB Indexes**: Optimized user queries
- **PM2 Clustering**: Multiple Node.js processes
- **Rate Management**: Idle detection, dynamic intervals

## External Integrations

### APIs in Use
- **Alpha Vantage**: Stock market data and financial information
- **Google Places**: Location search and geocoding
- **OpenAI**: AI chat functionality integration
- **Weather API**: Current conditions and forecasts

### File Management
- **AWS S3**: User profile pictures and background images
- **Local Storage**: Temporary files and caching

## Future Development Priorities

### High Priority
1. Enhanced Google Search integration
2. Digital Notes expansion with rich text
3. Additional widget types and customization
4. Continued performance optimization

### Technical Improvements
1. Component library standardization
2. Comprehensive testing framework
3. Accessibility compliance (WCAG)
4. PWA features (offline support)

## Development Workflow

### Git Strategy
- **main**: Production-ready code
- **feature/**: New feature development branches
- **Current Branch**: feature/bhe-2025/main

### Quality Assurance
1. Console error checking
2. Responsive design testing
3. Authentication flow verification
4. Performance monitoring

## Additional Context

### Color Palette (Dark Theme)
- **Primary**: #212121, #1f202d, #24303d, grey-darken-4
- **Accent**: #6ad1dc (cyan) for interactive elements
- **Background**: #25303d (main theme)
- **Hover**: rgba(140, 229, 239, 0.08)

### Component Patterns
- **Save States**: Loading animations with success feedback
- **Form Validation**: Client-server synchronized rules
- **Error Handling**: User-friendly toast notifications
- **Responsive Design**: Mobile-first with Vuetify breakpoints

This file provides comprehensive context for LLM assistants working with the Best Homepage Ever codebase. The project emphasizes performance, user experience, and maintainable code patterns while serving a large user base with personalized homepage functionality.