add changes
This commit is contained in:
AD2025
263
backend/README.md
Normal file
263
backend/README.md
Normal file
@@ -0,0 +1,263 @@
|
||||
# Interview Quiz Application - Backend
|
||||
|
||||
MySQL + Express + Node.js Backend API
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
backend/
|
||||
├── config/ # Configuration files (database, etc.)
|
||||
├── controllers/ # Request handlers
|
||||
├── middleware/ # Custom middleware (auth, validation, etc.)
|
||||
├── models/ # Sequelize models
|
||||
├── routes/ # API route definitions
|
||||
├── migrations/ # Database migrations
|
||||
├── seeders/ # Database seeders
|
||||
├── tests/ # Test files
|
||||
├── server.js # Main application entry point
|
||||
├── .env # Environment variables (not in git)
|
||||
├── .env.example # Environment variables template
|
||||
└── package.json # Dependencies and scripts
|
||||
```
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Node.js 18+
|
||||
- MySQL 8.0+
|
||||
- npm or yarn
|
||||
|
||||
## Installation
|
||||
|
||||
1. **Navigate to backend directory:**
|
||||
```bash
|
||||
cd backend
|
||||
```
|
||||
|
||||
2. **Install dependencies:**
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
3. **Setup environment variables:**
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
Then edit `.env` with your database credentials.
|
||||
|
||||
4. **Create MySQL database:**
|
||||
```sql
|
||||
CREATE DATABASE interview_quiz_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
|
||||
```
|
||||
|
||||
## Running the Application
|
||||
|
||||
### Development Mode
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
Uses nodemon for auto-restart on file changes.
|
||||
|
||||
### Production Mode
|
||||
```bash
|
||||
npm start
|
||||
```
|
||||
|
||||
### Server will start on:
|
||||
- **URL:** http://localhost:3000
|
||||
- **API Endpoint:** http://localhost:3000/api
|
||||
- **Health Check:** http://localhost:3000/health
|
||||
|
||||
## Database Management
|
||||
|
||||
### Initialize Sequelize
|
||||
```bash
|
||||
npx sequelize-cli init
|
||||
```
|
||||
|
||||
### Run Migrations
|
||||
```bash
|
||||
npm run migrate
|
||||
```
|
||||
|
||||
### Undo Last Migration
|
||||
```bash
|
||||
npm run migrate:undo
|
||||
```
|
||||
|
||||
### Run Seeders
|
||||
```bash
|
||||
npm run seed
|
||||
```
|
||||
|
||||
### Undo Seeders
|
||||
```bash
|
||||
npm run seed:undo
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
### Run all tests
|
||||
```bash
|
||||
npm test
|
||||
```
|
||||
|
||||
### Run tests in watch mode
|
||||
```bash
|
||||
npm run test:watch
|
||||
```
|
||||
|
||||
## API Endpoints
|
||||
|
||||
Coming soon... (Will be documented as features are implemented)
|
||||
|
||||
### Authentication
|
||||
- `POST /api/auth/register` - Register new user
|
||||
- `POST /api/auth/login` - Login user
|
||||
- `POST /api/auth/logout` - Logout user
|
||||
- `GET /api/auth/verify` - Verify JWT token
|
||||
|
||||
### Categories
|
||||
- `GET /api/categories` - Get all categories
|
||||
- `GET /api/categories/:id` - Get category by ID
|
||||
|
||||
### Questions
|
||||
- `GET /api/questions/category/:categoryId` - Get questions by category
|
||||
- `GET /api/questions/:id` - Get question by ID
|
||||
- `GET /api/questions/search` - Search questions
|
||||
|
||||
### Quiz
|
||||
- `POST /api/quiz/start` - Start quiz session
|
||||
- `POST /api/quiz/submit` - Submit answer
|
||||
- `POST /api/quiz/complete` - Complete quiz session
|
||||
- `GET /api/quiz/session/:sessionId` - Get session details
|
||||
|
||||
### User Dashboard
|
||||
- `GET /api/users/:userId/dashboard` - Get user dashboard
|
||||
- `GET /api/users/:userId/history` - Get quiz history
|
||||
- `PUT /api/users/:userId` - Update user profile
|
||||
|
||||
### Admin
|
||||
- `GET /api/admin/statistics` - Get system statistics
|
||||
- `GET /api/admin/guest-settings` - Get guest settings
|
||||
- `PUT /api/admin/guest-settings` - Update guest settings
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `NODE_ENV` | Environment (development/production) | development |
|
||||
| `PORT` | Server port | 3000 |
|
||||
| `API_PREFIX` | API route prefix | /api |
|
||||
| `DB_HOST` | MySQL host | localhost |
|
||||
| `DB_PORT` | MySQL port | 3306 |
|
||||
| `DB_NAME` | Database name | interview_quiz_db |
|
||||
| `DB_USER` | Database user | root |
|
||||
| `DB_PASSWORD` | Database password | - |
|
||||
| `JWT_SECRET` | Secret key for JWT tokens | - |
|
||||
| `JWT_EXPIRE` | JWT expiration time | 24h |
|
||||
| `CORS_ORIGIN` | Allowed CORS origin | http://localhost:4200 |
|
||||
|
||||
## Development Workflow
|
||||
|
||||
1. **Create a feature branch**
|
||||
```bash
|
||||
git checkout -b feature/your-feature-name
|
||||
```
|
||||
|
||||
2. **Implement your feature**
|
||||
- Follow the tasks in `BACKEND_TASKS.md`
|
||||
- Write tests for your code
|
||||
- Update this README if needed
|
||||
|
||||
3. **Test your changes**
|
||||
```bash
|
||||
npm test
|
||||
```
|
||||
|
||||
4. **Commit and push**
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "feat: your feature description"
|
||||
git push origin feature/your-feature-name
|
||||
```
|
||||
|
||||
## Technologies Used
|
||||
|
||||
- **Express.js** - Web framework
|
||||
- **Sequelize** - ORM for MySQL
|
||||
- **MySQL2** - MySQL driver
|
||||
- **JWT** - Authentication
|
||||
- **Bcrypt** - Password hashing
|
||||
- **Helmet** - Security headers
|
||||
- **CORS** - Cross-origin resource sharing
|
||||
- **Morgan** - HTTP request logger
|
||||
- **Express Validator** - Input validation
|
||||
- **Express Rate Limit** - Rate limiting
|
||||
- **Jest** - Testing framework
|
||||
- **Supertest** - API testing
|
||||
|
||||
## Testing Database Connection
|
||||
|
||||
To test the database connection:
|
||||
|
||||
```bash
|
||||
npm run test:db
|
||||
```
|
||||
|
||||
This will verify:
|
||||
- MySQL server is running
|
||||
- Database credentials are correct
|
||||
- Database exists
|
||||
- Connection is successful
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
All environment variables are validated on server startup. To manually validate:
|
||||
|
||||
```bash
|
||||
npm run validate:env
|
||||
```
|
||||
|
||||
To generate a new JWT secret:
|
||||
|
||||
```bash
|
||||
npm run generate:jwt
|
||||
```
|
||||
|
||||
See [ENVIRONMENT_GUIDE.md](./ENVIRONMENT_GUIDE.md) for complete configuration documentation.
|
||||
|
||||
## Testing Models
|
||||
|
||||
To test the User model:
|
||||
|
||||
```bash
|
||||
npm run test:user
|
||||
```
|
||||
|
||||
This verifies:
|
||||
- User creation with UUID
|
||||
- Password hashing
|
||||
- Password comparison
|
||||
- Validation rules
|
||||
- Helper methods
|
||||
|
||||
## Next Steps
|
||||
|
||||
Follow the tasks in `BACKEND_TASKS.md`:
|
||||
- ✅ Task 1: Project Initialization (COMPLETED)
|
||||
- ✅ Task 2: Database Setup (COMPLETED)
|
||||
- ✅ Task 3: Environment Configuration (COMPLETED)
|
||||
- ✅ Task 4: Create User Model & Migration (COMPLETED)
|
||||
- 🔄 Task 5: Create Categories Model & Migration (NEXT)
|
||||
- ... and more
|
||||
|
||||
## Documentation References
|
||||
|
||||
- [BACKEND_TASKS.md](../BACKEND_TASKS.md) - Complete task list
|
||||
- [SEQUELIZE_QUICK_REFERENCE.md](../SEQUELIZE_QUICK_REFERENCE.md) - Code examples
|
||||
- [SAMPLE_MIGRATIONS.md](../SAMPLE_MIGRATIONS.md) - Migration templates
|
||||
- [interview_quiz_user_story.md](../interview_quiz_user_story.md) - Full specification
|
||||
|
||||
## License
|
||||
|
||||
ISC
|
||||
Reference in New Issue
Block a user