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)

   docker-compose up --build
   

4. Initialize the database

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

# 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

# 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

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