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.

   docker-compose up --build
   

4. Access the application

   • Frontend: http://localhost:12000
   • Backend API: http://localhost:3001 (from host) or http://merchantsofhope-supplyanddemandportal-backend:3001 (from other containers)
   • Database: merchantsofhope-supplyanddemandportal-database:5432 (inside Docker network)

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

Running CI Tests Locally

To validate the entire CI pipeline on your local machine before pushing to Gitea, use the dedicated test configuration. This command builds the necessary images and runs both backend and frontend test suites, exiting with a status code indicating success or failure.

docker-compose -f docker-compose.yml -f docker-compose.test.yml up --build --abort-on-container-exit

Frontend Tests

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