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)**
   ```bash
   docker-compose up --build
   ```

4. **Initialize the database**
   ```bash
   # Run database migrations
   docker-compose exec merchantsofhope-supplyanddemandportal-backend npm run migrate
   
   # Seed the database with sample data
   docker-compose exec merchantsofhope-supplyanddemandportal-backend npm run seed
   ```

5. **Access the application**
   - Frontend: http://localhost:12000
   - Backend API: http://merchantsofhope-supplyanddemandportal-backend:3001 (inside Docker network) or http://localhost:3001 when running natively
   - Database: merchantsofhope-supplyanddemandportal-database:5432 (inside Docker network)

### Alternative: Native Node.js workflow

If you prefer running services outside Docker:

```bash
# Install dependencies
cd backend && npm install
cd ../frontend && npm install

# Start backend (uses .env)
cd ../backend
npm run dev

# In a separate terminal start frontend
cd ../frontend
npm start
```

Ensure a PostgreSQL instance is running and the `DATABASE_URL` in `.env` points to it. The frontend `.env.development` file pins the dev server to `0.0.0.0:12000` so it matches the Docker behaviour.

### 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

### Backend Tests
```bash
# Run all tests
docker-compose exec merchantsofhope-supplyanddemandportal-backend npm test

# Run tests in watch mode
docker-compose exec merchantsofhope-supplyanddemandportal-backend npm run test:watch
```

### Frontend Tests
```bash
# Run frontend tests
docker-compose exec merchantsofhope-supplyanddemandportal-frontend npm test
```

To run tests without Docker, execute `npm test` inside `backend/` or `frontend/` after installing dependencies.

## 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.