bookmarksite/docs

Bookmark Manager Application

A full-stack bookmark management application with user authentication, built with Node.js/Express backend and vanilla JavaScript frontend.

Features

• User Authentication: Registration, login, email verification, password reset
• Bookmark Management: Create, read, update, delete bookmarks with folders
• Security: JWT authentication, password hashing, SQL injection prevention, XSS protection
• Data Import/Export: Import from browser bookmarks, export to JSON
• Search & Filter: Search bookmarks by title/URL, filter by folder/status
• Responsive Design: Works on desktop and mobile devices

Prerequisites

• Node.js (v16 or higher)
• PostgreSQL (v12 or higher)
• npm or yarn package manager

Quick Start

1. Database Setup

First, create a PostgreSQL database:

# Connect to PostgreSQL
psql -U postgres

# Create database
CREATE DATABASE bookmark_manager;
CREATE DATABASE bookmark_manager_test; -- For testing

# Create user (optional)
CREATE USER bookmark_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE bookmark_manager TO bookmark_user;
GRANT ALL PRIVILEGES ON DATABASE bookmark_manager_test TO bookmark_user;

2. Backend Setup

# Navigate to backend directory
cd backend

# Install dependencies
npm install

# Copy environment file
cp .env.example .env

# Edit .env file with your database credentials
nano .env

Configure your .env file:

# Database Configuration
DB_HOST=localhost
DB_PORT=5432
DB_NAME=bookmark_manager
DB_USER=postgres
DB_PASSWORD=your_password

# JWT Configuration
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
JWT_EXPIRES_IN=24h

# Email Configuration (for verification emails)
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USER=your-email@gmail.com
EMAIL_PASS=your-app-password

# Server Configuration
PORT=3000
NODE_ENV=development

3. Initialize Database

# Initialize database tables
npm run db:init

# Check database status
npm run db:status

4. Start the Backend Server

# Development mode (with auto-reload)
npm run dev

# Or production mode
npm start

The backend server will start on http://localhost:3000

5. Access the Application

The backend now serves the frontend static files automatically:

• Start the backend server: npm run dev (from the backend directory)
• Open your browser to: http://localhost:3001
• The frontend files (HTML, CSS, JS) are served directly by the backend

Alternative: Use a separate web server (optional)

# From the root directory, serve with any static server
npx http-server -p 8080
# Then open http://localhost:8080
# Note: You'll need to update API URLs in the frontend to point to localhost:3001

Running Tests

The application includes a comprehensive test suite with unit tests, integration tests, and security tests.

Test Setup

cd backend

# Make sure test database exists
psql -U postgres -c "CREATE DATABASE bookmark_manager_test;"

# Run all tests
npm test

# Run specific test types
npm run test:unit        # Unit tests only
npm run test:integration # Integration tests only
npm run test:security    # Security tests only

# Run tests with coverage report
npm run test:coverage

# Run tests in watch mode (for development)
npm run test:watch

Test Database

The tests use a separate test database (bookmark_manager_test) to avoid affecting your development data. The test suite automatically:

• Sets up test database tables
• Runs tests in isolation
• Cleans up test data after each test

API Documentation

Authentication Endpoints

• POST /api/auth/register - Register new user
• POST /api/auth/login - Login user
• POST /api/auth/logout - Logout user
• GET /api/auth/verify/:token - Verify email
• POST /api/auth/forgot-password - Request password reset
• POST /api/auth/reset-password - Reset password
• POST /api/auth/refresh - Refresh JWT token

User 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 account
• GET /api/user/verify-token - Verify current token

Bookmark Endpoints

• GET /api/bookmarks - Get user bookmarks (with pagination/filtering)
• GET /api/bookmarks/:id - Get specific bookmark
• POST /api/bookmarks - Create bookmark
• PUT /api/bookmarks/:id - Update bookmark
• DELETE /api/bookmarks/:id - Delete bookmark
• GET /api/bookmarks/folders - Get user folders
• GET /api/bookmarks/stats - Get bookmark statistics
• POST /api/bookmarks/bulk - Bulk create bookmarks
• POST /api/bookmarks/export - Export bookmarks
• POST /api/bookmarks/migrate - Migrate bookmarks from localStorage

Database Management

Available Commands

# Initialize database (create tables)
npm run db:init

# Check database status
npm run db:status

# Reset database (drop and recreate tables)
npm run db:reset

# Validate database structure
npm run db:validate

# Clean up database
npm run db:cleanup

# Run database diagnostics
npm run db:diagnostics

Manual Database Operations

# Connect to database
psql -U postgres -d bookmark_manager

# View tables
\dt

# View users
SELECT id, email, is_verified, created_at FROM users;

# View bookmarks count by user
SELECT u.email, COUNT(b.id) as bookmark_count 
FROM users u 
LEFT JOIN bookmarks b ON u.id = b.user_id 
GROUP BY u.id, u.email;

Development

Project Structure

├── backend/                 # Backend Node.js application
│   ├── src/
│   │   ├── config/         # Configuration files
│   │   ├── controllers/    # Route controllers
│   │   ├── database/       # Database connection and utilities
│   │   ├── middleware/     # Express middleware
│   │   ├── models/         # Data models
│   │   ├── routes/         # API routes
│   │   └── services/       # Business logic services
│   ├── tests/              # Test files
│   │   ├── unit/          # Unit tests
│   │   ├── integration/   # Integration tests
│   │   ├── security/      # Security tests
│   │   └── helpers/       # Test utilities
│   └── scripts/           # Database and utility scripts
├── frontend files/         # Frontend HTML, CSS, JS files
├── tests/                 # Frontend tests
└── README.md

Adding New Features

1. Backend: Add routes in backend/src/routes/, models in backend/src/models/, services in backend/src/services/
2. Frontend: Update HTML files and script.js
3. Tests: Add corresponding tests in backend/tests/
4. Database: Update migrations in backend/src/database/migrations/

Code Style

• Use ESLint and Prettier for code formatting
• Follow RESTful API conventions
• Use async/await for asynchronous operations
• Implement proper error handling
• Add comprehensive tests for new features

Security Features

• Password Security: bcrypt hashing with salt rounds
• JWT Authentication: Secure token-based authentication
• SQL Injection Prevention: Parameterized queries
• XSS Protection: Input validation and sanitization
• Rate Limiting: Prevents brute force attacks
• CORS Protection: Configured for security
• Helmet: Security headers middleware
• Data Validation: Comprehensive input validation

Troubleshooting

Common Issues

Database Connection Error

# Check if PostgreSQL is running
sudo systemctl status postgresql

# Check database exists
psql -U postgres -l | grep bookmark_manager

Port Already in Use

# Find process using port 3000
lsof -i :3000

# Kill process
kill -9 <PID>

Email Verification Not Working

• Check email configuration in .env
• For Gmail, use App Passwords instead of regular password
• Check spam folder for verification emails

Tests Failing

# Reset test database
npm run db:reset
psql -U postgres -c "DROP DATABASE IF EXISTS bookmark_manager_test;"
psql -U postgres -c "CREATE DATABASE bookmark_manager_test;"

# Run tests again
npm test

Logs

Application logs are stored in backend/logs/:

• app-YYYY-MM-DD.log - General application logs
• auth-YYYY-MM-DD.log - Authentication logs
• database-YYYY-MM-DD.log - Database operation logs
• security-YYYY-MM-DD.log - Security-related logs

Production Deployment

Environment Variables

Set these environment variables for production:

NODE_ENV=production
JWT_SECRET=your-very-secure-secret-key
DB_HOST=your-production-db-host
DB_NAME=your-production-db-name
DB_USER=your-production-db-user
DB_PASSWORD=your-production-db-password
EMAIL_HOST=your-smtp-host
EMAIL_USER=your-email
EMAIL_PASS=your-email-password

Deployment Steps

1. Set up production database
2. Configure environment variables
3. Run database migrations: npm run db:init
4. Start application: npm start
5. Set up reverse proxy (nginx) if needed
6. Configure SSL certificates
7. Set up monitoring and logging

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make changes and add tests
4. Run tests: npm test
5. Commit changes: git commit -am 'Add feature'
6. Push to branch: git push origin feature-name
7. Submit a pull request

License

This project is licensed under the ISC License.

Support

For issues and questions:

1. Check the troubleshooting section above
2. Review the logs in backend/logs/
3. Run database diagnostics: npm run db:diagnostics
4. Check test results: npm test

---

Happy bookmarking! 📚