WIP
This commit is contained in:
377
docs/README.md
Normal file
377
docs/README.md
Normal file
@ -0,0 +1,377 @@
|
||||
# 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! 📚**
|
||||
Reference in New Issue
Block a user