Hire Smarter, Faster. A full-stack applicant tracking system (ATS) for small-to-medium businesses, featuring a Kanban hiring pipeline, interview scheduling, team scorecards, and hiring analytics.
| Layer | Technology |
|---|---|
| Frontend | React 18, TypeScript, Vite |
| Backend | FastAPI, SQLAlchemy, Pydantic v2 |
| Database | PostgreSQL (via psycopg2) |
| Styling | Tailwind CSS |
| Charts | Recharts |
| Drag & Drop | @hello-pangea/dnd |
| Migrations | Alembic |
| CLI | Click |
| Testing | pytest (backend), Vitest + Testing Library (frontend) |
- Python 3.11+
- Node.js 18+
- PostgreSQL 14+
# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate # Linux/macOS
# venv\Scripts\activate # Windows
# Install Python dependencies
make install
# or: pip install -r requirements.txtcd frontend
npm installCopy the example file and configure your settings:
cp .env.example .env| Variable | Description | Default |
|---|---|---|
DATABASE_URL |
PostgreSQL connection string | postgresql://user:password@localhost:5432/hireflow |
SECRET_KEY |
Application secret key | change-me-to-a-random-secret-key |
CORS_ORIGINS |
Comma-separated allowed origins | http://localhost:3000,http://localhost:5173 |
APP_ENV |
Environment (development / production) |
development |
LOG_LEVEL |
Logging level | INFO |
LOG_FILE |
Log file path | logs/hireflow.log |
UPLOAD_DIR |
Resume upload directory | uploads/resumes |
MAX_UPLOAD_SIZE_MB |
Max resume upload size in MB | 10 |
python -m src.main init-dbPopulates the database with sample jobs, candidates, applications, interviews, and scorecards:
python -m src.main seedpython -m src.main serve
# Runs on http://localhost:8000 with hot reload enabledcd frontend
npm run dev
# Runs on http://localhost:5173python -m src.main --help # Show all commands
python -m src.main info # Show current configuration
python -m src.main run # List available tasks
python -m src.main run seed-data # Run the seed-data task| Flag | Description |
|---|---|
--verbose / -v |
Enable DEBUG-level logging |
--quiet / -q |
Suppress all output except errors |
--version |
Show version |
uvicorn src.api:app --host 0.0.0.0 --port 8000 --workers 4cd frontend
npm run build
npm run preview
# Or serve the dist/ directory with your preferred static file serverhireflow/
├── src/
│ ├── main.py # CLI entry point
│ ├── config.py # Settings (env vars)
│ ├── core/
│ │ ├── database.py # SQLAlchemy engine & session
│ │ └── auth.py # Authentication utilities
│ ├── models/
│ │ ├── job.py # Job model
│ │ ├── candidate.py # Candidate model
│ │ ├── application.py # Application model
│ │ ├── interview.py # Interview model
│ │ ├── scorecard.py # Scorecard model
│ │ └── resume.py # Resume model
│ ├── api/
│ │ ├── jobs.py # /api/jobs endpoints
│ │ ├── candidates.py # /api/candidates endpoints
│ │ ├── interviews.py # /api/interviews endpoints
│ │ ├── analytics.py # /api/analytics endpoints
│ │ ├── dashboard.py # /api/dashboard endpoints
│ │ ├── auth.py # /api/auth endpoints
│ │ ├── seed.py # /api/seed endpoint
│ │ └── schemas.py # Pydantic request/response schemas
│ ├── services/ # Business logic layer
│ │ ├── candidate_service.py
│ │ ├── interview_service.py
│ │ ├── scorecard_service.py
│ │ ├── job_service.py
│ │ └── analytics.py
│ ├── tasks/ # Automation tasks
│ └── utils/ # Logging, retry, rate limiting
├── frontend/
│ ├── src/
│ │ ├── App.tsx # Root component & routing
│ │ ├── pages/
│ │ │ ├── DashboardPage.tsx # Summary cards, activity feed, funnel
│ │ │ ├── JobsPage.tsx # Job listings with filters
│ │ │ ├── CandidatesPage.tsx # Candidate search & table
│ │ │ ├── CalendarPage.tsx # Interview calendar view
│ │ │ └── AnalyticsPage.tsx # Hiring analytics & charts
│ │ ├── components/
│ │ │ ├── Layout.tsx # App shell with sidebar
│ │ │ ├── Sidebar.tsx # Navigation sidebar
│ │ │ ├── SummaryCards.tsx # Dashboard metric cards
│ │ │ ├── ActivityFeed.tsx # Recent activity timeline
│ │ │ └── HiringFunnel.tsx # Pipeline funnel chart
│ │ └── lib/
│ │ └── api-client.ts # API client utilities
│ ├── tailwind.config.js
│ └── vite.config.ts
├── tests/ # Backend test suite
├── migrations/ # Alembic migrations
├── logs/ # Application logs
├── requirements.txt
├── Makefile
├── alembic.ini
└── .env.example
The FastAPI server provides interactive API docs at:
- Swagger UI:
http://localhost:8000/docs - ReDoc:
http://localhost:8000/redoc
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/jobs |
List jobs (filterable by status, department) |
POST |
/api/jobs |
Create a new job |
GET |
/api/jobs/{id} |
Get job details |
PUT |
/api/jobs/{id} |
Update a job |
DELETE |
/api/jobs/{id} |
Delete a job |
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/candidates |
List candidates (searchable, filterable by source/stage) |
POST |
/api/candidates |
Create a new candidate |
GET |
/api/candidates/{id} |
Get candidate details |
PUT |
/api/candidates/{id} |
Update a candidate |
DELETE |
/api/candidates/{id} |
Delete a candidate |
POST |
/api/candidates/{id}/resume |
Upload a resume (file upload) |
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/interviews |
List interviews (filterable by date range) |
POST |
/api/interviews |
Schedule an interview |
GET |
/api/interviews/{id} |
Get interview details |
PUT |
/api/interviews/{id} |
Update an interview |
DELETE |
/api/interviews/{id} |
Cancel an interview |
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/dashboard |
Dashboard summary (open jobs, candidates, interviews today) |
GET |
/api/analytics/pipeline |
Pipeline funnel conversion data |
GET |
/api/analytics/time-to-hire |
Time-to-hire metrics by job |
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/health |
Health check |
POST |
/api/seed |
Seed database with sample data |
Job — Positions with title, department, location, employment type, salary range, and status (draft/open/closed/on_hold).
Candidate — Applicants with contact info, LinkedIn URL, resume, and source tracking (direct/referral/linkedin/indeed/other).
Application — Links a candidate to a job with pipeline stage tracking (applied → screening → phone_screen → interview → technical → offer → hired/rejected).
Interview — Scheduled interviews with type (phone/video/onsite/technical), status, and notes.
Scorecard — Interview evaluations with technical, communication, and culture scores (1-5) plus an overall recommendation (strong_yes/yes/neutral/no/strong_no).
make test
# or: python -m pytest tests/ -vcd frontend
npx vitest runMIT License
Copyright (c) 2025 HireFlow
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.