# User Management - Design Document

## Overview

The User Management system transforms the existing client-side bookmark manager into a full-stack web application with multi-user support. The system uses a Node.js/Express backend with PostgreSQL database for data persistence, JWT-based authentication, and maintains the existing frontend while adding user authentication flows. The architecture follows RESTful API principles with proper security measures including password hashing, session management, and data isolation between users.

## Architecture

### High-Level Architecture

```mermaid
graph TB
    CLIENT[Frontend Client]
    AUTH[Authentication Layer]
    API[REST API Layer]
    BIZ[Business Logic Layer]
    DATA[Data Access Layer]
    DB[(PostgreSQL Database)]
    EMAIL[Email Service]
    
    CLIENT --> AUTH
    AUTH --> API
    API --> BIZ
    BIZ --> DATA
    DATA --> DB
    BIZ --> EMAIL
    
    subgraph "Backend Services"
        AUTH
        API
        BIZ
        DATA
    end
    
    subgraph "External Services"
        EMAIL
        DB
    end
```

### Technology Stack

**Backend**:
- Node.js with Express.js framework
- PostgreSQL database with pg (node-postgres) driver
- bcrypt for password hashing
- jsonwebtoken for JWT authentication
- nodemailer for email services
- express-rate-limit for API rate limiting
- helmet for security headers

**Frontend**:
- Existing vanilla JavaScript application
- Fetch API for HTTP requests
- JWT token storage in httpOnly cookies
- Enhanced UI for authentication flows

### Application Flow

1. **User Registration**: Email validation → Password hashing → Database storage → Email verification
2. **Authentication**: Credential validation → JWT token generation → Session establishment
3. **Bookmark Operations**: Token validation → User authorization → Database operations → Response
4. **Session Management**: Token refresh → Expiration handling → Logout cleanup

## Components and Interfaces

### 1. User Authentication Service

**Purpose**: Handle user registration, login, password management, and session control

**Key Methods**:
- `registerUser(email, password)` - Create new user account
- `authenticateUser(email, password)` - Validate credentials and create session
- `generateJWT(userId)` - Create authentication token
- `validateToken(token)` - Verify token validity
- `resetPassword(email)` - Initiate password reset flow
- `changePassword(userId, currentPassword, newPassword)` - Update user password

**Security Features**:
- bcrypt password hashing with salt rounds (12)
- JWT tokens with 24-hour expiration
- Password strength validation
- Rate limiting on authentication endpoints
- Secure cookie configuration

### 2. User Data Model

```typescript
interface User {
    id: string;              // UUID primary key
    email: string;           // Unique email address
    password_hash: string;   // bcrypt hashed password
    is_verified: boolean;    // Email verification status
    created_at: Date;        // Account creation timestamp
    updated_at: Date;        // Last profile update
    last_login: Date;        // Last successful login
    verification_token?: string;  // Email verification token
    reset_token?: string;    // Password reset token
    reset_expires?: Date;    // Reset token expiration
}
```

### 3. Enhanced Bookmark Data Model

```typescript
interface Bookmark {
    id: string;              // UUID primary key
    user_id: string;         // Foreign key to users table
    title: string;           // Bookmark title
    url: string;             // Target URL
    folder: string;          // Folder path
    add_date: Date;          // Creation timestamp
    last_modified: Date;     // Last update timestamp
    icon: string;            // Favicon URL or data URI
    status: 'unknown' | 'valid' | 'invalid' | 'testing' | 'duplicate';
    created_at: Date;        // Database creation timestamp
    updated_at: Date;        // Database update timestamp
}
```

### 4. Database Schema

**Users Table**:
```sql
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    is_verified BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    last_login TIMESTAMP,
    verification_token VARCHAR(255),
    reset_token VARCHAR(255),
    reset_expires TIMESTAMP
);

CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_verification_token ON users(verification_token);
CREATE INDEX idx_users_reset_token ON users(reset_token);
```

**Bookmarks Table**:
```sql
CREATE TABLE bookmarks (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    title VARCHAR(500) NOT NULL,
    url TEXT NOT NULL,
    folder VARCHAR(255) DEFAULT '',
    add_date TIMESTAMP NOT NULL,
    last_modified TIMESTAMP,
    icon TEXT,
    status VARCHAR(20) DEFAULT 'unknown',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_bookmarks_user_id ON bookmarks(user_id);
CREATE INDEX idx_bookmarks_folder ON bookmarks(user_id, folder);
CREATE INDEX idx_bookmarks_status ON bookmarks(user_id, status);
CREATE INDEX idx_bookmarks_url ON bookmarks(user_id, url);
```

### 5. REST API Endpoints

**Authentication Endpoints**:
- `POST /api/auth/register` - User registration
- `POST /api/auth/login` - User login
- `POST /api/auth/logout` - User logout
- `POST /api/auth/refresh` - Token refresh
- `POST /api/auth/forgot-password` - Password reset request
- `POST /api/auth/reset-password` - Password reset confirmation
- `GET /api/auth/verify/:token` - Email verification

**User Management Endpoints**:
- `GET /api/user/profile` - Get user profile
- `PUT /api/user/profile` - Update user profile
- `POST /api/user/change-password` - Change password
- `DELETE /api/user/account` - Delete user account

**Bookmark Endpoints**:
- `GET /api/bookmarks` - Get user's bookmarks (with pagination)
- `POST /api/bookmarks` - Create new bookmark
- `PUT /api/bookmarks/:id` - Update bookmark
- `DELETE /api/bookmarks/:id` - Delete bookmark
- `POST /api/bookmarks/import` - Import bookmarks
- `GET /api/bookmarks/export` - Export bookmarks
- `POST /api/bookmarks/test-links` - Test bookmark links
- `POST /api/bookmarks/find-duplicates` - Find duplicate bookmarks

### 6. Middleware Components

**Authentication Middleware**:
```javascript
const authenticateToken = (req, res, next) => {
    const token = req.cookies.authToken;
    if (!token) return res.status(401).json({ error: 'Access denied' });
    
    try {
        const verified = jwt.verify(token, process.env.JWT_SECRET);
        req.user = verified;
        next();
    } catch (error) {
        res.status(400).json({ error: 'Invalid token' });
    }
};
```

**Rate Limiting Middleware**:
```javascript
const authLimiter = rateLimit({
    windowMs: 15 * 60 * 1000, // 15 minutes
    max: 5, // 5 attempts per window
    message: 'Too many authentication attempts'
});
```

## Data Models

### Session Management

**JWT Payload Structure**:
```typescript
interface JWTPayload {
    userId: string;
    email: string;
    iat: number;        // Issued at
    exp: number;        // Expiration
}
```

**Cookie Configuration**:
```javascript
const cookieOptions = {
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    sameSite: 'strict',
    maxAge: 24 * 60 * 60 * 1000 // 24 hours
};
```

### Email Templates

**Verification Email**:
- Subject: "Verify your Bookmark Manager account"
- Content: Welcome message with verification link
- Link format: `${baseUrl}/verify/${verificationToken}`

**Password Reset Email**:
- Subject: "Reset your Bookmark Manager password"
- Content: Reset instructions with secure link
- Link format: `${baseUrl}/reset-password/${resetToken}`
- Expiration: 1 hour

## Error Handling

### API Error Response Format

```typescript
interface APIError {
    error: string;           // Error message
    code?: string;          // Error code for client handling
    details?: any;          // Additional error details
    timestamp: string;      // ISO timestamp
}
```

### Error Categories

**Authentication Errors (401)**:
- Invalid credentials
- Token expired
- Token invalid
- Account not verified

**Authorization Errors (403)**:
- Insufficient permissions
- Account suspended
- Resource access denied

**Validation Errors (400)**:
- Invalid email format
- Weak password
- Missing required fields
- Invalid data format

**Server Errors (500)**:
- Database connection failed
- Email service unavailable
- Internal server error

### Error Logging Strategy

```javascript
const logger = {
    error: (message, meta) => {
        console.error({
            timestamp: new Date().toISOString(),
            level: 'error',
            message,
            ...meta
        });
    },
    warn: (message, meta) => {
        console.warn({
            timestamp: new Date().toISOString(),
            level: 'warn',
            message,
            ...meta
        });
    }
};
```

## Testing Strategy

### Unit Testing

**Authentication Service Tests**:
- Password hashing and verification
- JWT token generation and validation
- Email validation logic
- Password strength validation

**Database Layer Tests**:
- User CRUD operations
- Bookmark CRUD operations
- Data isolation between users
- Query performance with large datasets

**API Endpoint Tests**:
- Request validation
- Authentication middleware
- Error response formats
- Rate limiting behavior

### Integration Testing

**Authentication Flow Tests**:
1. Registration → Email verification → Login
2. Login → Token refresh → Logout
3. Password reset → New password → Login
4. Failed login attempts → Account lockout

**Bookmark Management Tests**:
1. Login → Import bookmarks → Verify isolation
2. CRUD operations → Data persistence
3. Link testing → Status updates
4. Export functionality → Data integrity

### Security Testing

**Authentication Security**:
- SQL injection prevention
- XSS protection
- CSRF protection
- Rate limiting effectiveness
- Password brute force protection

**Data Security**:
- User data isolation
- Sensitive data exposure
- Token security
- Session management

### Performance Testing

**Load Testing Scenarios**:
- Concurrent user registrations
- Simultaneous bookmark operations
- Large bookmark imports
- Database query performance

**Scalability Testing**:
- Database connection pooling
- Memory usage under load
- Response times with large datasets

## User Interface Design

### Authentication Pages

**Login Page Layout**:
```
┌─────────────────────────────────────┐
│ Bookmark Manager                    │
├─────────────────────────────────────┤
│ ┌─────────────────────────────────┐ │
│ │ Email: [________________]       │ │
│ │ Password: [________________]    │ │
│ │ [ ] Remember me                 │ │
│ │ [Login] [Forgot Password?]      │ │
│ │ Don't have an account? Register │ │
│ └─────────────────────────────────┘ │
└─────────────────────────────────────┘
```

**Registration Page Layout**:
```
┌─────────────────────────────────────┐
│ Create Account                      │
├─────────────────────────────────────┤
│ ┌─────────────────────────────────┐ │
│ │ Email: [________________]       │ │
│ │ Password: [________________]    │ │
│ │ Confirm: [________________]     │ │
│ │ Password Requirements:          │ │
│ │ ✓ 8+ characters                 │ │
│ │ ✓ Uppercase letter              │ │
│ │ ✓ Number                        │ │
│ │ [Create Account]                │ │
│ │ Already have an account? Login  │ │
│ └─────────────────────────────────┘ │
└─────────────────────────────────────┘
```

### Enhanced Main Application

**Header with User Menu**:
```
┌─────────────────────────────────────┐
│ Bookmark Manager    [user@email.com]│
│                     [Profile ▼]     │
│                     - Account       │
│                     - Settings      │
│                     - Logout        │
├─────────────────────────────────────┤
│ [Import] [Export] [Add Bookmark]    │
└─────────────────────────────────────┘
```

### Responsive Design Considerations

**Mobile Authentication**:
- Full-screen login/register forms
- Touch-friendly input fields
- Clear error messaging
- Simplified navigation

**Tablet/Desktop**:
- Centered authentication forms
- Side-by-side login/register options
- Enhanced user menu
- Consistent with existing bookmark UI

## Security Considerations

### Password Security

**Hashing Strategy**:
- bcrypt with 12 salt rounds
- Automatic salt generation
- Timing attack prevention
- Password history (optional)

**Password Policy**:
- Minimum 8 characters
- At least one uppercase letter
- At least one lowercase letter
- At least one number
- At least one special character
- Common password blacklist

### Token Security

**JWT Configuration**:
- Strong secret key (256-bit)
- Short expiration times (24 hours)
- Secure cookie storage
- Token refresh mechanism
- Blacklist for revoked tokens

### API Security

**Request Security**:
- HTTPS enforcement
- CORS configuration
- Rate limiting per endpoint
- Input validation and sanitization
- SQL injection prevention

**Response Security**:
- Security headers (helmet.js)
- Error message sanitization
- No sensitive data exposure
- Proper HTTP status codes

### Database Security

**Connection Security**:
- Connection string encryption
- Connection pooling limits
- Query timeout configuration
- Prepared statements only

**Data Protection**:
- User data isolation
- Soft delete for audit trails
- Regular backup procedures
- Access logging

## Performance Optimizations

### Database Optimizations

**Indexing Strategy**:
- Primary keys on all tables
- Foreign key indexes
- Composite indexes for common queries
- Partial indexes for filtered queries

**Query Optimization**:
- Pagination for large result sets
- Efficient JOIN operations
- Query result caching
- Connection pooling

### API Performance

**Response Optimization**:
- Gzip compression
- JSON response minification
- Conditional requests (ETags)
- Appropriate cache headers

**Request Handling**:
- Async/await patterns
- Error handling middleware
- Request timeout configuration
- Memory leak prevention

### Frontend Integration

**Token Management**:
- Automatic token refresh
- Graceful authentication failures
- Offline capability considerations
- Local storage cleanup

**API Integration**:
- Request retry logic
- Loading state management
- Error boundary implementation
- Optimistic updates where appropriate

## Deployment Considerations

### Environment Configuration

**Development Environment**:
- Local PostgreSQL instance
- Development JWT secrets
- Debug logging enabled
- CORS allowing localhost

**Production Environment**:
- Managed database service
- Environment variable secrets
- Production logging configuration
- Strict CORS policy
- HTTPS enforcement

### Monitoring and Logging

**Application Monitoring**:
- Request/response logging
- Error rate monitoring
- Performance metrics
- User activity tracking

**Security Monitoring**:
- Failed authentication attempts
- Suspicious activity detection
- Rate limit violations
- Token usage patterns

This design document provides a comprehensive blueprint for implementing secure, scalable user management functionality that integrates seamlessly with the existing bookmark manager while maintaining high security standards and excellent user experience.