Introduction
JobStar is a multi-tenant, white-label job portal and recruitment platform. It is delivered as a source-available application composed of a NestJS API, a Next.js website and admin panel, native Candidate and Recruiter apps for iOS & Android, and a plugin-based adapter framework for payments, SMS/WhatsApp, AI providers, storage and notifications.
This guide covers a self-hosted deployment. Managed hosting customers can skip the Quick Start and Deployment sections — your environment is provisioned for you.
Architecture at a glance
- API — NestJS + TypeScript, PostgreSQL, Redis for caching/queues.
- Web — Next.js marketing website, admin panel and candidate & recruiter portals.
- Mobile — Flutter Candidate and Recruiter apps for iOS & Android.
- Adapters — pluggable providers for payments, SMS/WhatsApp, AI, storage and notifications.
System Requirements
- Docker 24+ and Docker Compose (recommended), or Node.js 20+ and PostgreSQL 15+.
- Redis 7+ for caching and background jobs.
- 2 vCPU / 4 GB RAM minimum for evaluation; 4 vCPU / 8 GB+ for production.
- S3-compatible object storage for résumés and company documents.
- Outbound HTTPS access to your chosen provider APIs (payments, SMS/WhatsApp, AI).
Quick Start (Docker)
Clone the repository, copy the environment template and start the stack with Docker Compose.
# 1. Clone & configure
git clone https://your-repo/jobstar.git
cd jobstar
cp .env.example .env
# 2. Launch the full stack
docker compose --profile app up --build
The API becomes available at http://localhost:4000/api and the website + admin panel at http://localhost:3000.
Deployment
JobStar ships production Docker images and a CI pipeline. Deploy to any container platform — a single VM, AWS ECS, Azure Container Apps, Google Cloud Run, or a Kubernetes cluster.
# Apply migrations, then start in production mode
npm run migration:run
node dist/main.js
For high availability, run multiple API replicas behind a load balancer with a managed PostgreSQL and Redis. Static assets, résumés and documents are served from S3-compatible storage.
Configuration
All configuration is environment-driven. Key variables:
DATABASE_URL=postgresql://user:pass@host:5432/jobstar
JWT_SECRET=change-me
ENCRYPTION_KEY=32-byte-secret # AES-256 at rest
REDIS_URL=redis://localhost:6379
S3_ENDPOINT=... S3_BUCKET=...
# Payments
RAZORPAY_KEY_ID=... RAZORPAY_KEY_SECRET=...
STRIPE_SECRET_KEY=sk_live_...
# SMS / WhatsApp OTP & alerts
MSG91_AUTH_KEY=... TWILIO_ACCOUNT_SID=... TWILIO_AUTH_TOKEN=...
# AI (résumé analysis, matching, assistants)
OPENAI_API_KEY=... ANTHROPIC_API_KEY=...
# Provider adapters can also be configured per-tenant in the Admin Panel
Payment, SMS/WhatsApp, AI and notification credentials can be set per-tenant from the Admin Control Center rather than in .env — so each employer can use its own providers.
First Login
After seeding, sign in with the bootstrap super-admin. Send the tenant via the x-tenant-id header (or subdomain) and a bearer token from the login endpoint.
POST /api/auth/login
x-tenant-id: demo
{ "email": "admin@yourdomain.com", "password": "••••••" }
Enable 2FA immediately and create scoped roles before inviting your team.
Creating a Company
From the Admin Panel, create a Company (employer). This provisions the system roles, enables the selected modules and, optionally, an initial admin user. Each company is an isolated tenant with its own branding, users and data.
- Admin → Companies → New Company.
- Set legal name, edition/plan and modules.
- Assign an owner and invite recruiters.
Posting Jobs
Open Jobs → Create. Choose a category, define the role, location, salary range, employment type and required skills, then publish. No-code admin setup means recruiters post listings without touching configuration files.
Every job moves through DRAFT → PENDING REVIEW → PUBLISHED. Once published, a listing can be featured, paused, closed or reopened from the job page, and appears instantly on the website and native apps.
POST /api/jobs
Authorization: Bearer <token>
{ "title": "Senior Backend Engineer", "categoryId": "cat_eng", "location": "Remote", "type": "full_time", "salaryMin": 90000, "salaryMax": 130000 }
Candidate Registration
Candidates self-register on your branded portal or the mobile apps, creating a user and a candidate profile. They confirm their phone/email with an OTP, then complete profile details and upload a résumé before applying. You can also bulk-import candidates via the API.
POST /api/auth/register # create candidate account
POST /api/auth/otp/verify # confirm phone/email via OTP
Profile & Résumé Verification
Candidate accounts are verified with an OTP, and uploaded résumés are parsed to auto-fill profile fields (experience, education, skills). Recruiters and moderators review profiles in a single queue and approve, flag or request more information — every decision is logged.
POST /api/candidate/resume/upload # upload & auto-parse résumé
POST /api/company/candidates/:id/verify # mark a profile verified
Job Board
Publish job listings and manage them on a searchable job board. Configure categories, filters, featured slots and whether a listing is highlighted. Search, location and skill filters are applied automatically so candidates find the right roles fast.
Applications
Candidates apply to jobs or save them for later, with one-tap apply on web and mobile. Applications are validated against the recruiter's requirements, then flow into the applicant pipeline where recruiters can shortlist, schedule interviews and extend offers.
POST /api/applications
Authorization: Bearer <token>
{ "jobId": "job_123", "resumeId": "res_456", "coverNote": "..." }
Subscriptions & Payments
Recruiters pay via the payment adapter — subscriptions, packages or pay-per-post. Razorpay and Stripe are supported with GST invoicing built in. On successful payment, the plan's posting credits and premium features are activated; failed or expired payments release any held credits.
POST /api/billing/checkout
{ "plan": "pro", "provider": "stripe", "billing": "annual" }
Candidate & Recruiter Apps
JobStar ships native Flutter apps for iOS & Android. The Candidate app offers profile, résumé upload with auto-fill, one-tap apply, saved jobs, job alerts and application tracking. The Recruiter app covers job posting, applicant review, interviews and messaging — all sharing the same REST API as the web portals.
Reports & Analytics
Generate hiring reports, invoices and pipeline snapshots, and export data for your own systems. Recruiter and admin analytics dashboards summarize job views, applications, who-viewed-your-profile activity, conversion and revenue.
Notifications & Job Alerts
The notification service dispatches by channel — email, SMS, WhatsApp, push, Slack and Teams — wired to events such as new applications, interview invites, job alerts and payments. Candidates subscribe to job alerts by category and location; configure providers per tenant.
Admin Settings
The Admin Control Center manages tenants, subscription plans, module enablement, provider configs and feature flags. Provider secrets are encrypted at rest and masked in responses.
White Label Setup
Use the Theme Builder to set logo, colors, fonts and a custom domain with live preview. Configure localization (languages, currency, formats) per tenant. Each company presents a fully branded website and app experience.
Security
- JWT auth with rotating refresh tokens and per-device sessions.
- Argon2id password hashing; TOTP 2FA; SSO.
- RBAC with a granular permission catalog.
- AES-256-GCM encryption for provider secrets at rest.
- Audit logs, IP allowlisting and tenant isolation enforced at the request layer.
API Integration
Every capability is available over REST. Authenticate with a bearer token and pass the tenant header.
GET /api/jobs?category=engineering&location=remote
Authorization: Bearer <token>
x-tenant-id: your-tenant
Subscribe to webhooks for new applications, interviews and payments to keep external systems (ATS, HRMS, Slack/Teams) in sync.
{ "event": "application.created", "jobId": "job_123", "candidateId": "cand_456", "at": "2026-01-01T00:00:00Z" }
Troubleshooting
- Cannot connect to database — verify
DATABASE_URL and that PostgreSQL is reachable. - OTP not delivered — check the MSG91/Twilio credentials, sender ID and account balance.
- Résumé not parsing — confirm the AI provider key (OpenAI/Anthropic) and that the file is a supported PDF/DOCX.
- Payment not confirmed — verify the Razorpay/Stripe keys and the webhook URL.
- 401 on API calls — ensure the bearer token and
x-tenant-id match.
Best Practices
- Use least-privilege roles; reserve super-admin for platform operators.
- Rotate
JWT_SECRET and provider keys regularly. - Run migrations in a maintenance window; back up before upgrades.
- Test payment and OTP flows in sandbox mode before going live.
- Enable 2FA for every admin and recruiter user.
Glossary
- Job / Listing — a role published by a recruiter on the job board.
- Tenant / Company — an isolated employer instance on the platform.
- Applicant Pipeline — the stages an application moves through from applied to offer.
- Candidate / Recruiter — job seekers who apply, and employers who post and hire.
- OTP Verification — one-time-passcode confirmation of a candidate's phone or email.
Need a hand?
Our team can help with setup, migration and integrations.