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

   git clone <repository-url>
   cd MerchantsOfHope-SupplyANdDemandPortal
   

2. Copy environment template

   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.

   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:

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

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

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