Birthday Reminder Application

# Birthday Reminder Application

## Overview

This is a full-stack birthday reminder application built with React (frontend), Express (backend), and PostgreSQL (database via Drizzle ORM). The application helps users track and manage birthdays for friends, family, and colleagues, with email notification capabilities. It features a modern, dark-mode interface inspired by productivity tools like Linear and Notion, using shadcn/ui components built on Radix UI primitives.

## Documentation

For detailed documentation, see the following guides in the `docs/` folder:

| Document | Audience | Description |
|----------|----------|-------------|
| [Developer Guide](docs/DEVELOPER_GUIDE.md) | Developers | Technical documentation covering architecture, database schema, authentication, and how to add new features |
| [Product Guide](docs/PRODUCT_GUIDE.md) | Product Managers | Feature overview, user flows, business logic, and roadmap considerations |
| [API Reference](docs/API_REFERENCE.md) | Developers | Complete API endpoint documentation with request/response examples |
| [Design Guidelines](design_guidelines.md) | Designers/Developers | UI/UX specifications, typography, colors, and component patterns |

## User Preferences

- Preferred communication style: Simple, everyday language (Spanish preferred)
- Language: Spanish as default UI language
- Date format: dd/mm/yyyy for display and input

## System Architecture

### Frontend Architecture

**Framework & Build System**
- **React 18** with TypeScript for type-safe component development
- **Vite** as the build tool and development server with HMR (Hot Module Replacement)
- **Wouter** for lightweight client-side routing instead of React Router

**UI Component System**
- **shadcn/ui** component library (New York style variant) with Radix UI primitives
- **Tailwind CSS** for utility-first styling with custom design tokens
- **CSS Variables** for theming support (dark mode default)
- Components are aliased via `@/components` path mapping

**State Management**
- **TanStack Query (React Query)** for server state management and data fetching
- Local component state with React hooks for UI state
- Custom language context provider for internationalization (Spanish/English)
- Custom hooks: `useAuth`, `useBirthdays`, `useSettings`

**Design System**
- Custom color system with HSL-based CSS variables
- Neutral base color scheme with support for semantic colors (primary, secondary, destructive, etc.)
- Custom border radius values (9px, 6px, 3px)
- Typography using Inter font from Google Fonts CDN
- Responsive design with mobile-first approach

**Key Features**
- Birthday list with filtering by tag (family, friends, work, other) and time period
- Add/edit birthday forms with validation
- Excel import functionality for bulk birthday uploads
- Email settings configuration for notification preferences
- Authentication system (login/register) with session-based auth
- Toast notifications for user feedback
- Multi-language support (Spanish/English)

### Backend Architecture

**Server Framework**
- **Express.js** with TypeScript for API endpoints
- Custom middleware for request logging with timestamps
- Static file serving for production builds
- Session-based authentication with Passport.js

**Development vs Production**
- Development mode uses Vite middleware for HMR
- Production mode serves pre-built static assets from `dist/public`
- Environment-aware configuration via `NODE_ENV`

**Build Process**
- **esbuild** for server-side bundling with selective dependency bundling
- Allowlist approach for bundling specific dependencies (reduces syscalls for cold starts)
- Client built separately via Vite

**API Structure**
- Routes prefixed with `/api`
- Storage interface abstraction for data operations
- Implements `DatabaseStorage` class using Drizzle ORM

**Storage Layer**
- Interface-based design (`IStorage`) for flexibility
- Methods for user CRUD operations (getUser, getUserByEmail, createUser)
- Methods for birthday CRUD (getBirthdaysByUserId, createBirthday, updateBirthday, deleteBirthday)
- Integrated with Drizzle ORM for PostgreSQL persistence

### Data Storage

**Database Setup**
- **Drizzle ORM** configured for PostgreSQL dialect
- **Neon Database** serverless driver (`@neondatabase/serverless`) with HTTP transport
- Migration files stored in `./migrations` directory
- Schema defined in `shared/schema.ts`

**Schema Design**
- **Users table**: email, password (hashed with bcrypt), notification settings
- **Birthdays table**: userId (FK), name, birthDate, tag (enum: family/friends/work/other)
- Uses `gen_random_uuid()` for primary keys (UUID strings)
- Zod integration via `drizzle-zod` for runtime validation
- Shared schema between client and server via `@shared` alias

**Database Connection**
- Connection configured via `DATABASE_URL` environment variable
- Uses `drizzle({ client: sql, schema })` pattern for proper Neon HTTP driver integration
- Drizzle Kit configured for schema push (`db:push` script)

**Known Issues - Neon HTTP Driver**
- The Neon HTTP driver has a known bug where empty query results cause `TypeError: Cannot read properties of null (reading 'map')`
- Workaround: Wrap queries in try-catch and handle the specific error, falling back to re-fetching data
- Affects `.returning()` calls and empty `.select()` results

### Authentication & Authorization

**Authentication Strategy**
- Passport.js with LocalStrategy for email/password authentication
- express-session for session management
- MemoryStore for development (consider connect-pg-simple for production)
- bcryptjs for password hashing
- SESSION_SECRET environment variable required

**Admin Authorization**
- Users have `isAdmin` boolean field (default: false)
- Admin-only endpoints protected by `requireAdmin` middleware (returns 403 for non-admin)
- Admin endpoints: `/api/admin/users`, `/api/admin/email-logs`, `/api/admin/upcoming-reminders`
- Frontend hides admin link for non-admin users
- Frontend route protection shows 404 for non-admin accessing /admin
- To make a user admin: `UPDATE users SET is_admin = true WHERE email = '[email protected]'`

### External Dependencies

**Database & ORM**
- PostgreSQL (via Neon serverless)
- Drizzle ORM for query building and migrations
- Drizzle Kit for schema management

**UI Component Libraries**
- Radix UI primitives (20+ component packages)
- Tailwind CSS with PostCSS and Autoprefixer
- Lucide React for icons
- class-variance-authority (CVA) for component variants
- embla-carousel-react for carousel functionality
- react-day-picker for calendar/date selection

**Form Management & Validation**
- React Hook Form with Hookform Resolvers
- Zod for schema validation
- zod-validation-error for user-friendly error messages

**Utilities**
- date-fns for date manipulation
- clsx and tailwind-merge for className utilities
- nanoid for unique ID generation

**Email Notifications**
- **nodemailer** configured with Ethereal for development testing (captures emails without delivery)
- Production-ready with configurable SMTP (Resend, SendGrid, etc.) via environment variables
- Email templates support Spanish/English with HTML formatting
- `email_logs` table tracks all sent emails with status, messageId, and errors
- **reminderService** evaluates upcoming birthdays based on user preferences
- Debug endpoint `/api/debug/send-reminder` for testing (returns Ethereal preview URL)
- Cron endpoint `/api/cron/process-reminders` for scheduled reminder processing
- Email settings UI complete with timing and notification preferences

**Development Tools**
- Replit-specific plugins for error overlay, cartographer, and dev banner
- TypeScript with strict mode enabled
- Source map support via @jridgewell/trace-mapping

**Potential Integrations** (dependencies present but not actively used)
- Stripe for payments
- Google Generative AI
- OpenAI
- WebSocket (ws)
- Excel processing (xlsx)
- File uploads (multer)
- Rate limiting (express-rate-limit)

**Build & Deployment**
- Production build creates single CJS bundle for server
- Client assets bundled separately
- External dependencies not in allowlist remain as node_modules references
- Scripts: `dev` (development), `build` (production), `start` (run production), `db:push` (schema sync)