diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..261eeb9 --- /dev/null +++ b/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/README.md b/README.md index 788cbbd..7ee41b6 100644 --- a/README.md +++ b/README.md @@ -1,361 +1,422 @@ -# Candidate Matching API +# Employee & Employer Matching Platform API [![Dev to Main PR](https://github.com/firatyll/candidate-matching/actions/workflows/dev-to-main-pr.yml/badge.svg)](https://github.com/firatyll/candidate-matching/actions/workflows/dev-to-main-pr.yml) -> **Note: This application is currently under active development. Features and API endpoints may change.** +## Overview -A RESTful API service for candidate and job position matching built with Node.js, Express, TypeScript, Prisma, and PostgreSQL. +**Employee & Employer Matching Backend System** that leverages **smart filtering** and **AI-powered semantic search** with embeddings to connect the right candidates with the perfect job opportunities. Built with modern technologies and enterprise-grade architecture. -## 🚀 CI/CD Pipeline +### Key Capabilities +- **AI-Powered Matching**: Advanced semantic search using OpenAI embeddings for intelligent candidate-job matching +- **Smart Filtering**: Multi-dimensional filtering by location, experience, salary, skills, availability, and more +- **Vector Search**: High-performance similarity search with ChromaDB for scalable matching algorithms +- **Real-time Synchronization**: Automatic sync of candidates and jobs to the vector database +- **Intelligent Ranking**: Relevance-based scoring and ranking of matches +- **Enterprise Security**: Rate limiting, request sanitization, and comprehensive security middleware -This repository includes an automated GitHub Actions pipeline that: -- ✅ Runs code quality checks on every push to `dev` branch -- 🤖 Generates AI-powered pull requests using OpenAI GPT-4 -- 📋 Automatically assigns reviewers and adds helpful labels -- 🔍 Includes comprehensive review checklists - -See [Pipeline Setup Guide](./.github/PIPELINE_SETUP.md) for configuration details. +## Tech Stack -## Features +### **Core Technologies** +- **Runtime**: Node.js 18+ +- **Framework**: Express.js +- **Language**: TypeScript (Full type safety) +- **Database**: PostgreSQL (Primary data store) +- **ORM**: Prisma (Type-safe database access) -- **Candidate Management**: Create, read, update, and delete candidate profiles -- **Job Position Management**: Manage job postings with detailed requirements -- **Application Tracking**: Track job applications and their statuses -- **🚀 AI-Powered Matching**: Semantic search-based candidate-job matching using OpenAI embeddings -- **Vector Search**: ChromaDB for efficient similarity search and ranking -- **Smart Filtering**: Metadata-based filtering with location, experience, salary, etc. -- **Auto-Sync**: Automatic synchronization of candidates and jobs to vector database -- **Schema Validation**: Robust input validation using Zod -- **Type Safety**: Full TypeScript implementation with Prisma-generated types -- **Database Relations**: Properly structured database with foreign key relationships -- **Error Handling**: Comprehensive error handling with detailed responses -- **CORS Support**: Cross-origin resource sharing enabled +### **AI & Search** +- **Vector Database**: ChromaDB (Similarity search & embeddings storage) +- **AI/ML Engine**: OpenAI Embeddings API (text-embedding-ada-002) +- **Search Algorithm**: Cosine similarity with metadata filtering -## Tech Stack +### **Validation & Security** +- **Schema Validation**: Zod (Runtime type checking) +- **Security**: Helmet.js, CORS, Rate limiting, Request sanitization +- **Encryption**: Crypto-JS for sensitive data handling -- **Runtime**: Node.js -- **Framework**: Express.js -- **Language**: TypeScript -- **Database**: PostgreSQL -- **ORM**: Prisma -- **Vector Database**: ChromaDB -- **AI/ML**: OpenAI Embeddings API -- **Validation**: Zod +### **Development & Deployment** - **Development**: Nodemon, ts-node +- **Build System**: TypeScript compiler +- **Testing**: Type checking and build validation +- **CI/CD**: GitHub Actions with automated PR generation +## API Routes -### Validation Rules - -#### Candidate Validation -- `firstName`: Minimum 2 characters -- `lastName`: Minimum 2 characters -- `email`: Valid email format, unique -- `phone`: Valid phone number format (optional) -- `skills`: Array with at least 1 skill -- `experience`: Non-negative number -- `location`: Minimum 2 characters -- `availability`: One of: "immediate", "within_week", "within_month", "not_available" -- `salary_expectation`: Non-negative number (optional) -- `resume_url`: Valid URL format (optional) +### **Candidate Management** +```http +GET /api/candidates # List all candidates +POST /api/candidates # Create new candidate +GET /api/candidates/:id # Get candidate by ID +PUT /api/candidates/:id # Update candidate +DELETE /api/candidates/:id # Delete candidate +``` -## Project Structure +### **Job Position Management** +```http +GET /api/jobs # List all job positions +POST /api/jobs # Create new job position +GET /api/jobs/:id # Get job position by ID +PUT /api/jobs/:id # Update job position +DELETE /api/jobs/:id # Delete job position +``` +### **Application Tracking** +```http +GET /api/applications # List all applications (with filters) +POST /api/applications # Create application (admin use) +POST /api/applications/apply # Apply to job (candidate use) +GET /api/applications/:id # Get application by ID +PUT /api/applications/:id # Update application +PATCH /api/applications/:id/status # Update application status (HR) +PATCH /api/applications/:id/withdraw # Withdraw application (candidate) +DELETE /api/applications/:id # Delete application + +# Specialized endpoints +GET /api/applications/candidate/:candidateId # Get candidate's applications +GET /api/applications/job/:jobId # Get job's applications ``` -src/ -├── controllers/ # Request handlers -│ └── candidate.controller.ts -├── generated/ # Prisma generated files -│ └── prisma/ -├── middlewares/ # Express middlewares -│ └── validation.middleware.ts -├── models/ # Database models (future use) -├── routes/ # API routes -│ └── candidate.routes.ts -├── schemas/ # Zod validation schemas -│ ├── candidate.schema.ts -│ ├── common.schema.ts -│ └── job.schema.ts -├── services/ # Business logic (future use) -├── utils/ # Utility functions -│ └── validation.utils.ts -└── index.ts # Application entry point - -prisma/ -├── schema.prisma # Prisma schema definition -└── migrations/ # Database migrations +### **AI Matching System** +```http +GET /api/matching/health # Health check +GET /api/matching/candidates/:id/jobs # Find matching jobs for candidate +GET /api/matching/jobs/:id/candidates # Find matching candidates for job +POST /api/matching/sync/candidates/:id # Sync individual candidate +POST /api/matching/sync/jobs/:id # Sync individual job +POST /api/matching/sync # Bulk sync (all/candidates/jobs) ``` -## Database Schema +#### **Matching Query Parameters** -### Models +**For Job Matching:** +- `limit`: Number of results (default: 10) +- `location`: Filter by location +- `remote_ok`: Remote work availability (true/false) +- `experience_level`: entry, mid, senior, lead +- `employment_type`: full_time, part_time, contract, internship +- `salary_min`, `salary_max`: Salary range filters -#### Candidate -- Primary key: `id` (UUID) -- Unique constraint: `email` -- Fields: firstName, lastName, email, phone, skills, experience, location, availability, salary_expectation, resume_url -- Timestamps: created_at, updated_at +**For Candidate Matching:** +- `limit`: Number of results (default: 10) +- `location`: Filter by location +- `availability`: immediate, within_week, within_month, not_available +- `min_experience`, `max_experience`: Experience range +- `max_salary_expectation`: Maximum salary expectation -#### JobPosition -- Primary key: `id` (UUID) -- Fields: title, company, description, required_skills, preferred_skills, experience_level, location, remote_ok, salary_min, salary_max, employment_type, status -- Timestamps: created_at, updated_at +## Project Structure -#### JobApplication -- Primary key: `id` (UUID) -- Foreign keys: candidate_id, job_position_id -- Unique constraint: (candidate_id, job_position_id) -- Fields: status, cover_letter, applied_at, updated_at - -### Enums -- `CandidateAvailability`: IMMEDIATE, WITHIN_WEEK, WITHIN_MONTH, NOT_AVAILABLE -- `ExperienceLevel`: ENTRY, MID, SENIOR, LEAD -- `EmploymentType`: FULL_TIME, PART_TIME, CONTRACT, INTERNSHIP -- `JobStatus`: ACTIVE, INACTIVE, FILLED -- `ApplicationStatus`: PENDING, REVIEWED, INTERVIEWED, OFFERED, ACCEPTED, REJECTED, WITHDRAWN - -## Development - -### Code Style -- Use TypeScript for type safety -- Follow consistent naming conventions (camelCase for variables, PascalCase for types) -- Use meaningful variable and function names -- Add proper error handling for all async operations - -### Database Changes -1. Modify the Prisma schema (`prisma/schema.prisma`) -2. Create and apply migration: -```bash -npx prisma migrate dev --name description_of_changes ``` -3. Regenerate Prisma client: -```bash -npx prisma generate +candidate-matching/ +├── 📁 .github/ +│ └── workflows/ +│ └── dev-to-main-pr.yml # CI/CD pipeline +├── 📁 prisma/ +│ ├── schema.prisma # Database schema +│ └── migrations/ # Database migrations +├── 📁 src/ +│ ├── index.ts # Application entry point +│ ├── 📁 config/ +│ │ └── matching.config.ts # Matching system configuration +│ ├── 📁 controllers/ # Request handlers +│ │ ├── candidate.controller.ts # Candidate CRUD operations +│ │ ├── job.controller.ts # Job position CRUD operations +│ │ ├── application.controller.ts # Application management +│ │ └── matching.controller.ts # AI matching endpoints +│ ├── 📁 middlewares/ # Express middlewares +│ │ ├── validation.middleware.ts # Schema validation +│ │ ├── enhanced-validation.middleware.ts +│ │ └── security.middleware.ts # Security & rate limiting +│ ├── 📁 routes/ # API route definitions +│ │ ├── candidate.routes.ts +│ │ ├── job.routes.ts +│ │ ├── application.routes.ts +│ │ └── matching.routes.ts +│ ├── 📁 schemas/ # Zod validation schemas +│ │ ├── candidate.schema.ts +│ │ ├── job.schema.ts +│ │ ├── application.schema.ts +│ │ └── common.schema.ts +│ ├── 📁 services/ +│ │ └── matching/ +│ │ └── vector-matching.service.ts # AI matching logic +│ ├── 📁 utils/ # Utility functions +│ │ ├── validation.utils.ts +│ │ ├── encryption.utils.ts +│ │ ├── sanitization.utils.ts +│ │ └── rate-limit.utils.ts +│ └── 📁 generated/ # Prisma generated files +│ └── prisma/ +├── package.json # Dependencies & scripts +├── tsconfig.json # TypeScript configuration +├── LICENSE # Apache 2.0 License +└── README.md ``` -### Adding New Endpoints -1. Create/update schemas in `src/schemas/` -2. Add controller functions in `src/controllers/` -3. Define routes in `src/routes/` -4. Import and use routes in `src/index.ts` +## CI/CD Pipeline + +Our automated GitHub Actions pipeline provides: + +### **Code Quality Assurance** +- TypeScript compilation validation +- Build process verification +- Automated code quality checks +- Comprehensive error reporting -## Scripts +### **Automated Workflow** +- AI-powered pull request generation using OpenAI GPT-4o-mini +- Automatic reviewer assignment +- Intelligent labeling system +- Detailed change analysis and reporting -| Script | Description | -|--------|-------------| -| `npm run dev` | Start development server with hot reload | -| `npm run build` | Build TypeScript to JavaScript | -| `npm run start` | Start production server | -| `npm run build:watch` | Watch mode for TypeScript compilation | -| `npm run clean` | Remove build directory | -| `npm run type-check` | Run TypeScript type checking | +### **Pipeline Triggers** +- Runs on every push to `dev` branch +- Manual workflow dispatch available +- Automatic PR creation from dev → main -## Installation +### **Quality Gates** +- All checks must pass before PR creation +- TypeScript strict mode validation +- Successful build requirement +- Automated deployment readiness verification -1. Clone the repository: +## Installation & Setup + +### **Prerequisites** +- Node.js 18+ +- PostgreSQL 12+ +- Git + +### **Quick Start** + +1. **Clone the Repository** ```bash -git clone +git clone https://github.com/firatyll/candidate-matching.git cd candidate-matching ``` -2. Install dependencies: +2. **Install Dependencies** ```bash npm install ``` -3. Copy environment variables: +3. **Environment Setup** ```bash cp .env.example .env +# Edit .env with your configuration (see Environment Variables section) ``` -4. Configure your environment variables (see [Environment Variables](#environment-variables)) - -5. Set up the database: +4. **Database Setup** ```bash +# Create PostgreSQL database +createdb candidate_matching + +# Run Prisma migrations npx prisma migrate dev --name init + +# Generate Prisma client npx prisma generate ``` -## Environment Variables +5. **ChromaDB Setup (Choose one method)** + +**Option A - Docker (Recommended):** +```bash +docker pull chromadb/chroma +docker run -p 8000:8000 chromadb/chroma +``` + +**Option B - Local Installation:** +```bash +pip install chromadb +chroma run --host localhost --port 8000 +``` + +6. **Start Development Server** +```bash +npm run dev +``` + +The API will be available at `http://localhost:3000` -Create a `.env` file in the root directory and configure the following variables: +### **Environment Variables** + +Create a `.env` file with the following configuration: ```env -# Database -DATABASE_URL="postgresql://username:password@localhost:5432/database_name?schema=public" +# Database Configuration +DATABASE_URL="postgresql://username:password@localhost:5432/candidate_matching?schema=public" -# Server +# Server Configuration PORT=3000 NODE_ENV=development +ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001 -# OpenAI API (required for AI matching) +# AI & Vector Search (Required for matching features) OPENAI_API_KEY=your_openai_api_key_here - -# ChromaDB (for vector search) CHROMA_HOST=localhost CHROMA_PORT=8000 CHROMA_URL=http://localhost:8000 + +# Security (Optional - defaults provided) +RATE_LIMIT_WINDOW_MS=900000 +RATE_LIMIT_MAX_REQUESTS=100 ``` -### Environment Variable Descriptions +#### **Environment Variable Details** + +| Variable | Description | Required | Default | +|----------|-------------|----------|---------| +| `DATABASE_URL` | PostgreSQL connection string | ✅ Yes | - | +| `PORT` | Server port number | ❌ No | 3000 | +| `NODE_ENV` | Environment mode | ❌ No | development | +| `OPENAI_API_KEY` | OpenAI API key for embeddings | ✅ Yes* | - | +| `CHROMA_URL` | ChromaDB server URL | ✅ Yes* | http://localhost:8000 | +| `ALLOWED_ORIGINS` | CORS allowed origins | ❌ No | localhost:3000 | -- `DATABASE_URL`: PostgreSQL connection string -- `PORT`: Port number for the server (default: 3000) -- `NODE_ENV`: Environment mode (development, production, test) -- `OPENAI_API_KEY`: **Required** - OpenAI API key for generating embeddings -- `CHROMA_HOST`: ChromaDB server host (default: localhost) -- `CHROMA_PORT`: ChromaDB server port (default: 8000) -- `CHROMA_URL`: Full ChromaDB server URL +*Required for AI matching features -## Database Setup +### **Database Schema** -1. **Create PostgreSQL Database**: +Our system uses three core models with proper relationships: + +#### **Candidate Model** ```sql -CREATE DATABASE database_name;◊ +- id (UUID, Primary Key) +- firstName, lastName (String, Required) +- email (String, Unique, Required) +- phone (String, Optional) +- skills (String[], Required, min 1) +- experience (Integer, Required, ≥0) +- location (String, Required) +- availability (Enum: immediate|within_week|within_month|not_available) +- salary_expectation (Integer, Optional) +- resume_url (String, Optional, Valid URL) +- created_at, updated_at (Timestamps) ``` -2. **Run Prisma Migrations**: -```bash -npx prisma migrate dev --name init +#### **JobPosition Model** +```sql +- id (UUID, Primary Key) +- title, company (String, Required) +- description (String, Required, min 10 chars) +- required_skills, preferred_skills (String[]) +- experience_level (Enum: entry|mid|senior|lead) +- location (String, Required) +- remote_ok (Boolean, Default: false) +- salary_min, salary_max (Integer, Optional) +- employment_type (Enum: full_time|part_time|contract|internship) +- status (Enum: active|inactive|filled, Default: active) +- created_at, updated_at (Timestamps) ``` -3. **Generate Prisma Client**: -```bash -npx prisma generate +#### **JobApplication Model** +```sql +- id (UUID, Primary Key) +- candidate_id, job_position_id (UUID, Foreign Keys) +- status (Enum: pending|reviewed|interviewed|offered|accepted|rejected|withdrawn) +- cover_letter (String, Optional) +- applied_at, updated_at (Timestamps) +- Unique constraint: (candidate_id, job_position_id) ``` -4. **View Database (Optional)**: -```bash -npx prisma studio -``` +## Available Scripts -## ChromaDB Setup +| Script | Description | Usage | +|--------|-------------|-------| +| `npm run dev` | Start development server with hot reload | Development | +| `npm run build` | Build TypeScript to JavaScript | Production prep | +| `npm start` | Start production server | Production | +| `npm run build:watch` | Watch mode TypeScript compilation | Development | +| `npm run type-check` | Run TypeScript type checking only | Validation | +| `npm run clean` | Remove build directory | Cleanup | +| `npm run validate` | Run all checks (lint + build) | CI/CD | -### Option 1: Docker (Recommended) -```bash -# Pull and run ChromaDB -docker pull chromadb/chroma -docker run -p 8000:8000 chromadb/chroma -``` +## 🤝 Contributing -### Option 2: Local Installation -```bash -# Install ChromaDB -pip install chromadb +We welcome contributions to improve the Employee & Employer Matching Platform! -# Run ChromaDB server -chroma run --host localhost --port 8000 -``` +### **Development Workflow** -### Verify ChromaDB is Running +1. **Fork the Repository** ```bash -curl http://localhost:8000/api/v1/heartbeat +git clone https://github.com/your-username/candidate-matching.git +cd candidate-matching ``` -## AI Matching System - -### Initial Setup -1. **Get OpenAI API Key**: Visit [OpenAI Platform](https://platform.openai.com/) and create an API key -2. **Add to Environment**: Set `OPENAI_API_KEY` in your `.env` file -3. **Start ChromaDB**: Ensure ChromaDB is running on port 8000 -4. **Sync Data**: Use the sync endpoints to populate the vector database - -### Matching API Endpoints - -#### Health Check -```http -GET /api/matching/health +2. **Create Feature Branch** +```bash +git checkout -b feature/your-feature-name ``` -#### Find Matching Jobs for Candidate -```http -GET /api/matching/candidates/{candidateId}/jobs?limit=10&location=Istanbul&remote_ok=true +3. **Development Setup** +```bash +npm install +cp .env.example .env +# Configure your .env file +npx prisma migrate dev +npm run dev ``` -#### Find Matching Candidates for Job -```http -GET /api/matching/jobs/{jobId}/candidates?limit=10&availability=immediate&min_experience=2 -``` +4. **Code Quality Standards** +- Use TypeScript for all code +- Follow existing naming conventions (camelCase variables, PascalCase types) +- Add proper error handling for async operations +- Write meaningful commit messages +- Update documentation for new features -#### Sync Individual Items -```http -POST /api/matching/sync/candidates/{candidateId} -POST /api/matching/sync/jobs/{jobId} +5. **Testing Your Changes** +```bash +npm run type-check # Verify TypeScript compilation +npm run build # Test build process +npm run validate # Run all quality checks ``` -#### Bulk Sync -```http -POST /api/matching/sync -Content-Type: application/json - -{ - "type": "all" // or "candidates" or "jobs" -} +6. **Submit Changes** +```bash +git add . +git commit -m "feat: add your feature description" +git push origin feature/your-feature-name ``` -### Query Parameters for Job Matching -- `limit`: Number of results (default: 10) -- `location`: Filter by location -- `remote_ok`: Filter by remote work availability (true/false) -- `experience_level`: Filter by experience level (entry, mid, senior, lead) -- `employment_type`: Filter by employment type (full_time, part_time, contract, internship) -- `salary_min`: Minimum salary filter -- `salary_max`: Maximum salary filter - -### Query Parameters for Candidate Matching -- `limit`: Number of results (default: 10) -- `location`: Filter by location -- `availability`: Filter by availability (immediate, within_week, within_month, not_available) -- `min_experience`: Minimum years of experience -- `max_experience`: Maximum years of experience -- `max_salary_expectation`: Maximum salary expectation +Then create a Pull Request targeting the `dev` branch. -## Running the Application +### **Database Changes** +1. Modify `prisma/schema.prisma` +2. Create migration: `npx prisma migrate dev --name description` +3. Regenerate client: `npx prisma generate` -### Development Mode -```bash -npm run dev -``` +### **Adding New Endpoints** +1. Create/update schemas in `src/schemas/` +2. Add controller functions in `src/controllers/` +3. Define routes in `src/routes/` +4. Import routes in `src/index.ts` -### Production Mode -```bash -npm run build -npm start -``` +### **Code Review Process** +- All PRs require review before merging +- Automated CI/CD checks must pass +- AI-generated PR descriptions help reviewers +- Manual testing of new features encouraged -### Other Commands -```bash -# Build the project -npm run build - -# Watch mode for TypeScript compilation -npm run build:watch +## License -# Type checking only -npm run type-check +This project is licensed under the **Apache License 2.0**. See the [LICENSE](LICENSE) file for details. -# Clean build directory -npm run clean ``` +Copyright 2025 Candidate Matching Platform -The server will start on `http://localhost:3000` (or the port specified in your `.env` file). - -## Contributing +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at -1. Fork the repository -2. Create a feature branch (`git checkout -b feature/new-feature`) -3. Commit your changes (`git commit -am 'Add new feature'`) -4. Push to the branch (`git push origin feature/new-feature`) -5. Create a Pull Request + http://www.apache.org/licenses/LICENSE-2.0 -### Development Guidelines -- Write clear commit messages -- Add appropriate error handling -- Update documentation for new features -- Follow existing code style and patterns -- Test your changes thoroughly +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +``` -## License +--- -This project is licensed under the [](License). +**🚀 Built with modern technologies for scalable employee-employer matching**