MOHPortal/README.md

# MerchantsOfHope-SupplyANdDemandPortal - Recruiter Workflow SAAS

A comprehensive SAAS application for managing recruiter workflows, built with modern technologies and following TDD principles.

## Features

### Core Functionality
- **User Management**: Multi-role authentication system (Admin, Recruiter, Employer, Candidate)
- **Employer Management**: Company profiles, job postings, candidate management
- **Candidate Management**: Profile creation, resume uploads, application tracking
- **Job Management**: Job posting creation, filtering, search capabilities
- **Application Tracking**: End-to-end application workflow management
- **Resume Management**: File upload, download, and management system

### User Roles
- **Admin**: Full system access and user management
- **Recruiter**: Candidate and employer management, job posting oversight
- **Employer**: Job posting creation, candidate review, application management
- **Candidate**: Job browsing, application submission, profile management

## Technology Stack

### Backend
- **Node.js** with Express.js
- **PostgreSQL** database
- **JWT** authentication
- **Multer** for file uploads
- **Jest** for testing
- **Docker** containerization

### Frontend
- **React 18** with modern hooks
- **React Router** for navigation
- **React Query** for data fetching
- **Tailwind CSS** for styling
- **Lucide React** for icons
- **React Hot Toast** for notifications

### Infrastructure
- **Docker Compose** for orchestration
- **PostgreSQL** database
- **File upload** handling with proper validation

## Getting Started

### Prerequisites
- Docker and Docker Compose
- Git

### Installation

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd MerchantsOfHope-SupplyANdDemandPortal
   ```

2. **Copy environment template**
   ```bash
   cp .env.example .env
   ```
   The defaults support Docker-based development. Adjust values as needed for local tooling or deployment pipelines.

3. **Start the application with Docker (recommended for parity)**
   This single command builds the images, starts all services, runs database migrations, and seeds the database with sample data.
   ```bash
   POSTGRES_PASSWORD=merchantsofhope_dev_password JWT_SECRET=merchantsofhope_dev_jwt_secret_key_2025 docker compose up --build -d
   ```

4. **Access the application**
   - **Frontend**: http://localhost:12000 (React app with nginx)
   - **API**: http://localhost:12000/api/* (proxied to backend)
   - **Backend**: Not directly accessible (internal Docker network only)
   - **Database**: Internal Docker network only

### Environment Variables

The backend now derives its `DATABASE_URL` automatically when the `POSTGRES_*` variables are present. The following additional variables are available:

```bash
# Request throttling defaults (~100 requests / 15 minutes)
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX=100

# Uploads directory (overridable if you mount elsewhere)
UPLOAD_DIR=uploads/resumes

# Optional entrypoint controls
RUN_MIGRATIONS=true
RUN_SEED=false

# Database pool and wait tuning (milliseconds)
DB_POOL_MAX=10
DB_POOL_IDLE_MS=30000
DB_POOL_CONNECTION_TIMEOUT_MS=5000
DB_WAIT_TIMEOUT_MS=60000
```

Set `POSTGRES_PASSWORD` and `JWT_SECRET` before launching the stack. See `.env.example` for the full list.

### Demo Accounts

The application comes with pre-seeded demo accounts:

- **Admin**: admin@merchantsofhope.org / admin123
- **Recruiter**: recruiter@merchantsofhope.org / recruiter123
- **Employer**: employer@techcorp.com / employer123
- **Candidate**: candidate@example.com / candidate123

## API Documentation

### Authentication Endpoints
- `POST /api/auth/register` - User registration
- `POST /api/auth/login` - User login
- `GET /api/auth/me` - Get current user
- `POST /api/auth/logout` - User logout

### User Management
- `GET /api/users` - List all users (Admin only)
- `GET /api/users/:id` - Get user by ID
- `PUT /api/users/:id` - Update user profile
- `PUT /api/users/:id/deactivate` - Deactivate user (Admin only)

### Job Management
- `GET /api/jobs` - List jobs with filtering
- `GET /api/jobs/:id` - Get job details
- `POST /api/jobs` - Create job posting
- `PUT /api/jobs/:id` - Update job posting
- `DELETE /api/jobs/:id` - Delete job posting

### Candidate Management
- `GET /api/candidates` - List candidates with filtering
- `GET /api/candidates/:id` - Get candidate details
- `POST /api/candidates` - Create candidate profile
- `PUT /api/candidates/:id` - Update candidate profile

### Application Management
- `GET /api/applications` - List applications
- `GET /api/applications/:id` - Get application details
- `POST /api/applications` - Submit application
- `PUT /api/applications/:id/status` - Update application status

### Resume Management
- `GET /api/resumes/candidate/:candidateId` - Get candidate resumes
- `POST /api/resumes/upload` - Upload resume
- `GET /api/resumes/:id/download` - Download resume
- `PUT /api/resumes/:id/primary` - Set primary resume
- `DELETE /api/resumes/:id` - Delete resume

## Testing

### Quality Gates & Tests

`npm run lint` and `npm test` must pass in both the backend and frontend. By default, the backend Jest suite bootstraps a disposable Postgres instance via Docker (using `docker-compose.test.yml`), so Docker must be available on your workstation. To point the tests at an existing database (e.g., CI runners), set `USE_DOCKER_TEST_DB=false` and supply `DATABASE_URL`/`POSTGRES_*`.

Quick commands:

```bash
# Backend
cd backend
npm install
npm run lint
npm test -- --runInBand --coverage

# Frontend
cd frontend
npm install
npm run lint
npm test -- --watchAll=false --coverage
```

To mirror CI in one shot, run the helper script from the repository root:

```bash
./scripts/run-ci-tests.sh
```

The script executes linting followed by the backend and frontend test suites (each with coverage reporting). Coverage thresholds are enforced by Jest to guard against regressions.
The helper waits for the ad-hoc PostgreSQL container, honours the backend entrypoint (which now blocks on database readiness, runs migrations, and optionally seeds), and then runs both suites with coverage thresholds enforced.

## Continuous Integration

Gitea Actions configuration lives in `.gitea/workflows/ci.yml`. It:
- Runs backend and frontend unit tests on every push or pull request.
- Builds Docker images on pushes to the `main` branch, ready to publish to a registry (requires `REGISTRY_*` secrets).

See inline comments in the workflow for required secrets.

## Deployment

### Coolify

Follow `docs/COOLIFY_DEPLOYMENT.md` for guidance on connecting this repository to a Coolify environment, configuring secrets, and enabling automated deploys via Gitea CI.

## Project Structure
```
MerchantsOfHope-SupplyANdDemandPortal/
├── backend/
│   ├── src/
│   │   ├── routes/          # API route handlers
│   │   ├── middleware/     # Authentication middleware
│   │   ├── database/       # Database schema and migrations
│   │   ├── tests/          # Backend tests
│   │   └── server.js       # Main server file
│   ├── uploads/            # File upload directory
│   └── Dockerfile
├── frontend/
│   ├── src/
│   │   ├── components/     # Reusable React components
│   │   ├── pages/          # Page components
│   │   ├── contexts/       # React contexts
│   │   └── App.js          # Main App component
│   └── Dockerfile
├── docker-compose.yml      # Docker orchestration
└── README.md
```

### Database Schema

The application uses a comprehensive PostgreSQL schema with the following main tables:
- `users` - User authentication and basic info
- `employers` - Company/employer profiles
- `candidates` - Candidate profiles and skills
- `jobs` - Job postings with requirements
- `applications` - Job applications and status tracking
- `resumes` - Resume file management
- `interviews` - Interview scheduling and management

## Features in Detail

### Job Management
- Advanced filtering by location, salary, experience level, skills
- Search functionality across job titles and descriptions
- Remote work support
- Application deadline management
- Status tracking (active, paused, closed, draft)

### Candidate Management
- Skills-based filtering and search
- Experience level categorization
- Location-based filtering
- Salary expectation tracking
- Portfolio and social media links

### Application Workflow
- Multi-stage application process
- Status tracking (applied, reviewed, shortlisted, interviewed, offered, rejected)
- Notes and comments system
- Interview scheduling capabilities

### File Management
- Secure resume upload with validation
- Multiple file format support (PDF, DOC, DOCX, TXT)
- File size limits and type validation
- Primary resume designation
- Secure download with proper access controls

## Security Features

- JWT-based authentication
- Role-based access control
- Password hashing with bcrypt
- File upload validation
- SQL injection prevention
- CORS configuration
- Helmet.js security headers

## Performance Considerations

- Database indexing for optimal query performance
- Pagination for large datasets
- Efficient file handling
- Optimized React components
- Proper error handling and logging

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

## License

This project is licensed under the MIT License.

## Support

For support and questions, please contact the development team or create an issue in the repository.