EmployeeManagementSystem/backend-deno/README.md

# Work Allocation Backend - Deno TypeScript

A secure, type-safe backend for the Work Allocation System built with Deno and
TypeScript.

## Features

### Security Improvements

- **Strong Password Hashing**: bcrypt with configurable rounds (default: 12)
- **JWT Authentication**: Secure token-based authentication with HMAC-SHA256
- **Rate Limiting**: Configurable request rate limiting to prevent abuse
- **CORS Protection**: Configurable cross-origin resource sharing
- **Security Headers**: X-Frame-Options, X-Content-Type-Options, XSS protection
- **Input Sanitization**: Protection against XSS and injection attacks
- **Strict TypeScript**: Full type safety with strict compiler options

### Technical Stack

- **Runtime**: Deno 2.x
- **Framework**: Oak (Deno's Express-like framework)
- **Database**: MySQL 8.0 with mysql2 driver
- **Authentication**: JWT with djwt library
- **Password Hashing**: bcrypt

## Prerequisites

- [Deno](https://deno.land/) 2.0 or higher
- MySQL 8.0 (via Docker or local installation)

## Installation

1. **Install Deno** (if not already installed):

   ```bash
   curl -fsSL https://deno.land/install.sh | sh
   ```

2. **Configure environment**:

   ```bash
   cp .env.example .env
   # Edit .env with your database credentials
   ```

3. **Start the database** (if using Docker):

   ```bash
   cd .. && docker-compose up -d
   ```

## Running the Server

### Development Mode (with auto-reload)

```bash
deno task dev
```

### Production Mode

```bash
deno task start
```

### Seed the Database

```bash
deno task seed
```

## API Endpoints

### Authentication

- `POST /api/auth/login` - User login
- `GET /api/auth/me` - Get current user
- `POST /api/auth/change-password` - Change password

### Users

- `GET /api/users` - List users (filtered by role)
- `GET /api/users/:id` - Get user by ID
- `POST /api/users` - Create user (Admin/Supervisor)
- `PUT /api/users/:id` - Update user (Admin/Supervisor)
- `DELETE /api/users/:id` - Delete user (Admin/Supervisor)

### Departments

- `GET /api/departments` - List departments
- `GET /api/departments/:id` - Get department
- `GET /api/departments/:id/sub-departments` - Get sub-departments
- `POST /api/departments` - Create department (SuperAdmin)
- `POST /api/departments/:id/sub-departments` - Create sub-department
  (SuperAdmin)

### Work Allocations

- `GET /api/work-allocations` - List allocations (role-filtered)
- `GET /api/work-allocations/:id` - Get allocation
- `POST /api/work-allocations` - Create allocation (Supervisor/Admin)
- `PUT /api/work-allocations/:id/status` - Update status (Supervisor/Admin)
- `DELETE /api/work-allocations/:id` - Delete allocation (Supervisor/Admin)

### Attendance

- `GET /api/attendance` - List attendance records
- `GET /api/attendance/:id` - Get attendance record
- `POST /api/attendance/check-in` - Check in employee (Supervisor/Admin)
- `POST /api/attendance/check-out` - Check out employee (Supervisor/Admin)
- `GET /api/attendance/summary/stats` - Get attendance summary

### Contractor Rates

- `GET /api/contractor-rates` - List rates
- `GET /api/contractor-rates/contractor/:id/current` - Get current rate
- `POST /api/contractor-rates` - Set rate (Supervisor/Admin)
- `PUT /api/contractor-rates/:id` - Update rate (Supervisor/Admin)
- `DELETE /api/contractor-rates/:id` - Delete rate (Supervisor/Admin)

### Health Check

- `GET /health` - Server health status

## Environment Variables

| Variable                  | Description             | Default                 |
| ------------------------- | ----------------------- | ----------------------- |
| `PORT`                    | Server port             | 3000                    |
| `DB_HOST`                 | Database host           | localhost               |
| `DB_USER`                 | Database user           | root                    |
| `DB_PASSWORD`             | Database password       | admin123                |
| `DB_NAME`                 | Database name           | work_allocation         |
| `DB_PORT`                 | Database port           | 3306                    |
| `JWT_SECRET`              | JWT signing secret      | (change in production!) |
| `JWT_EXPIRES_IN`          | Token expiration        | 7d                      |
| `BCRYPT_ROUNDS`           | Password hash rounds    | 12                      |
| `RATE_LIMIT_WINDOW_MS`    | Rate limit window       | 900000 (15 min)         |
| `RATE_LIMIT_MAX_REQUESTS` | Max requests per window | 100                     |
| `CORS_ORIGIN`             | Allowed CORS origins    | <http://localhost:5173> |
| `NODE_ENV`                | Environment             | development             |

## Security Best Practices

### For Production

1. **Change JWT Secret**: Use a strong, random secret

   ```bash
   JWT_SECRET=$(openssl rand -base64 64)
   ```

2. **Enable HTTPS**: Use a reverse proxy (nginx) with SSL

3. **Set Production Environment**:

   ```bash
   NODE_ENV=production
   ```

4. **Increase bcrypt rounds** (if performance allows):

   ```bash
   BCRYPT_ROUNDS=14
   ```

5. **Configure CORS** for your domain:

   ```bash
   CORS_ORIGIN=https://yourdomain.com
   ```

## Project Structure

```bash
backend-deno/
├── config/
│   ├── database.ts    # Database connection pool
│   └── env.ts         # Environment configuration
├── middleware/
│   ├── auth.ts        # JWT authentication & authorization
│   └── security.ts    # Security middleware (CORS, rate limit, etc.)
├── routes/
│   ├── auth.ts        # Authentication routes
│   ├── users.ts       # User management routes
│   ├── departments.ts # Department routes
│   ├── work-allocations.ts
│   ├── attendance.ts
│   └── contractor-rates.ts
├── scripts/
│   └── seed.ts        # Database seeding script
├── types/
│   └── index.ts       # TypeScript type definitions
├── main.ts            # Application entry point
├── deno.json          # Deno configuration
└── .env               # Environment variables
```

## Differences from Node.js Backend

| Feature         | Node.js              | Deno                 |
| --------------- | -------------------- | -------------------- |
| Runtime         | Node.js              | Deno                 |
| Package Manager | npm                  | Built-in (JSR/npm)   |
| TypeScript      | Requires compilation | Native support       |
| Security        | Manual setup         | Secure by default    |
| Permissions     | Full access          | Explicit permissions |
| Framework       | Express              | Oak                  |

## License

MIT