377 lines
9.5 KiB
Markdown
377 lines
9.5 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
```env
|
|
# 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
|
|
|
|
```bash
|
|
# Initialize database tables
|
|
npm run db:init
|
|
|
|
# Check database status
|
|
npm run db:status
|
|
```
|
|
|
|
### 4. Start the Backend Server
|
|
|
|
```bash
|
|
# 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)**
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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**
|
|
```bash
|
|
# Check if PostgreSQL is running
|
|
sudo systemctl status postgresql
|
|
|
|
# Check database exists
|
|
psql -U postgres -l | grep bookmark_manager
|
|
```
|
|
|
|
**Port Already in Use**
|
|
```bash
|
|
# 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**
|
|
```bash
|
|
# 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:
|
|
|
|
```env
|
|
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! 📚** |