AI-powered recruitment platform. This monorepo holds three services that run independently, plus the shared API contract and the infra you need for local development.
Direkrut AI is split into layers so that business logic and AI logic can scale separately and neither one blocks the other.
Frontend (apps/web) is a Next.js app serving two interfaces from one
codebase: the public candidate portal and the private HRD dashboard.
Server-side rendering keeps job pages indexable, which is how most candidates
find us in the first place.
Backend is two services running side by side:
apps/api-gois a Go REST API that owns the platform's business logic: JWT auth with role-based access control, job management, the four-tier subscription flow, Xendit payment integration, and real-time notifications. We picked Go here because this layer takes the brunt of concurrent traffic.apps/ai-engineis a Python FastAPI service that owns everything AI: CV parsing and skill extraction, cosine-similarity vector search, NLP over interview transcripts, the dual-track assessment logic, and inference for the Chat AI thinking partner.
The two talk over an internal REST API, with Redis acting as cache and message queue.
Data lives in PostgreSQL with the pgvector extension, so relational rows and vector embeddings sit in the same system instead of two. CV files and short audio recordings go to object storage (MinIO locally, anything S3-compatible in production).
External AI is deliberately model-agnostic (see
apps/ai-engine/app/providers.py). Each company can pick the provider that fits
their budget: OpenAI, Gemini, Groq, or whatever comes next. Whisper handles
speech-to-text for interview answers, which matters given how much Indonesian
accents vary.
apps/web ──HTTP──▶ apps/api-go ──internal REST──▶ apps/ai-engine
(Next.js) (Golang) (FastAPI)
│ │
▼ ▼
PostgreSQL + pgvector AI Providers
Redis (OpenAI/Gemini/Groq)
MinIO (object storage) Whisper API
Request and response shapes for all three services are defined once in
packages/contracts/openapi.yaml. See API documentation
below for how to read it.
The baseline contract lives in
packages/contracts/openapi.yaml
(OpenAPI 3.0.3). Most endpoints that are not built yet are tagged [BELUM DIIMPLEMENTASI] in
its summary and return 501.
Be aware that the apps have outrun the spec: the candidate and HRD endpoints that already ship are summarized below and still need to be folded back into the OpenAPI file.
Raw YAML is painful to read, so render it locally instead (nothing gets uploaded):
npx @redocly/cli preview-docs packages/contracts/openapi.yamlBefore you commit a change to openapi.yaml, lint it. Zero errors or it
doesn't go in:
npx @redocly/cli lint packages/contracts/openapi.yamlWhat actually works today: JWT auth, jobs CRUD with cursor pagination and Redis caching, the application, prescreen and interview flow, CV parsing via Groq and Gemini, assessment scoring, interview transcription via Groq Whisper, and Chat AI. All of it has been tested against the real services and storage. Subscriptions, payments, notifications, and vector search are still stubs, and each one is flagged in the tables below.
Live deployments (pushed manually through the Heroku container registry;
CI/CD takes over automatically on merge to prod, see .github/workflows/):
| Service | URL | Health |
|---|---|---|
apps/api-go |
https://direkrut-ai-api-go-51c4e232a2fc.herokuapp.com |
/healthz, /readyz |
apps/ai-engine |
https://direkrut-ai-ai-engine-c58d5404c946.herokuapp.com |
/healthz, /readyz (public probes; /v1/* needs X-Internal-Api-Key) |
All four probes above were verified returning HTTP 200 on July 26, 2026.
Both services return the same error envelope for every 4xx and 5xx response unless a table note says otherwise:
{ "error": { "code": "validation_failed", "message": "..." } }| Method | Path | Auth | Notes |
|---|---|---|---|
| POST | /v1/auth/register |
none | Create an account. role: hrd requires companyName. |
| POST | /v1/auth/login |
none | Sign in, returns a token pair. |
| POST | /v1/auth/forgot-password |
none | Emails a reset link. Response is intentionally generic, token TTL is 1 hour, 5 minute cooldown per account. |
| POST | /v1/auth/reset-password |
none | Consumes the single-use email token, then revokes every refresh token for that user. |
| POST | /v1/auth/refresh |
none | Trade in a refresh token. Rotating, single use. |
| GET | /v1/jobs |
none | Published jobs. Cursor paginated and cached. |
| GET | /v1/jobs/{jobId} |
none | One job. Cached. |
| POST | /v1/jobs |
Bearer (hrd) | Create a job. |
| PUT | /v1/jobs/{jobId} |
Bearer (hrd, owner) | Update a job. |
| DELETE | /v1/jobs/{jobId} |
Bearer (hrd, owner) | Delete a job. Hard delete, no soft flag. |
| POST | /v1/jobs/{jobId}/cv-upload-url |
Bearer (candidate) | Presigned URL for uploading a CV straight to object storage. |
| POST | /v1/applications |
Bearer (candidate) | Submit an application. |
| GET | /v1/applications |
Bearer | Applications visible to the caller's role. |
| GET | /v1/applications/{applicationId} |
Bearer | One application, subject to access rules. |
| PATCH | /v1/applications/{applicationId}/status |
Bearer (hrd) | Move a candidate to a new status or decision. |
| POST | /v1/applications/{applicationId}/prescreen/questions |
Bearer (candidate) | Generate pre-screening questions. |
| POST | /v1/applications/{applicationId}/prescreen/submit |
Bearer (candidate) | Store answers and pre-screening results. |
| GET | /v1/applications/{applicationId}/prescreen |
Bearer | Read pre-screening status, score, and answers. |
| POST | /v1/applications/{applicationId}/interview/questions |
Bearer (candidate) | Generate AI interview questions once pre-screening passes. |
| POST | /v1/applications/{applicationId}/interview/transcribe |
Bearer (candidate) | Store the transcript of an interview answer. |
| POST | /v1/applications/{applicationId}/interview/finalize |
Bearer (candidate) | Score and close out the AI interview. |
| GET | /v1/applications/{applicationId}/interview |
Bearer | Read interview results, subject to access rules. |
| GET | /v1/subscriptions/me |
Bearer | Hardcoded {"tier":"free"}, does not hit the DB yet. |
| POST | /v1/subscriptions/upgrade |
Bearer | Not implemented. Returns 501 with a null body. |
| POST | /v1/subscriptions/cancel |
Bearer | Not implemented. Returns 501 with a null body. |
| POST | /v1/payments/invoices |
Bearer | Not implemented. Returns 501 with a null body. |
| POST | /v1/payments/webhooks/xendit |
none | |
| GET | /v1/notifications |
Bearer | Always an empty array, does not hit the DB yet. |
| POST | /v1/notifications/{id}/read |
Bearer | Not implemented. Returns 501 with a null body. |
| Method | Path | Notes |
|---|---|---|
| POST | /v1/cv-parser/parse |
PDFs go to Groq, images (jpg/png/webp) go to Gemini vision. Cached 24 hours per content hash. |
| POST | /v1/assessment/score-validation |
Score from 0 to 100 plus an authenticity read on the answers (Groq). |
| POST | /v1/assessment/transcribe-interview |
Speech-to-text via Groq Whisper, plus a summary. |
| POST | /v1/vector-search/embed |
Not implemented. Returns 501. |
| POST | /v1/vector-search/match |
Not implemented. Returns 501. |
| POST | /v1/chat/stream |
Live SSE chat with provider fallback, rate limiting, a prompt-injection guard, and HR scope enforcement. |
Only for endpoints that actually work. Full field lists and validation rules
(min/max length, enums, and so on) live in openapi.yaml.
POST /v1/auth/register
// Response 201
{
"accessToken": "eyJhbGciOiJIUzI1NiIs...", // JWT, 15 minute lifetime
"refreshToken": "89b87756dd93fb680c..." // opaque string, 7 day lifetime
}POST /v1/auth/login / POST /v1/auth/refresh
// POST /v1/auth/login request
{ "email": "hrd@contoh.com", "password": "supersecret123" }// POST /v1/auth/refresh request
{ "refreshToken": "89b87756dd93fb680c..." }// Response 200 (same shape for both)
{ "accessToken": "eyJhbGciOiJIUzI1NiIs...", "refreshToken": "010f3fbd8ccaf966..." }POST /v1/auth/forgot-password / POST /v1/auth/reset-password
// POST /v1/auth/forgot-password request
{ "email": "user@contoh.com" }// Response 200, always generic so we never leak which emails are registered
{ "status": "ok" }Reset tokens are stored hashed and expire after an hour. Asking again within five minutes reuses the existing token rather than minting a new one, so nobody can flood a user's inbox.
// POST /v1/auth/reset-password request
{
"token": "token-from-email",
"newPassword": "passwordbaru123"
}// Response 200
{ "status": "ok" }GET /v1/jobs?limit=1
// Response 200, sent with Cache-Control: public, max-age=60
{
"items": [
{
"id": "b10fb44b-2720-4bd6-939d-38582db1386f",
"companyId": "6ad5774a-29f6-4cf4-9ed3-cb09c06a3608",
"companyName": "PT Finansial Prima",
"companyIndustry": "Keuangan",
"title": "Financial Analyst",
"description": "Analisis laporan keuangan klien korporat...",
"requirements": "S1 Akuntansi/Keuangan\nMahir Excel dan financial modeling",
"location": "Jakarta Pusat",
"employmentType": "full-time",
"salaryMin": 9000000,
"salaryMax": 15000000,
"status": "published",
"publishedAt": "2026-07-17T18:14:05.052Z",
"createdAt": "2026-07-17T18:14:05.052Z"
}
],
"nextCursor": "MjAyNi0wNy0xN1QxODoxNDowNS4wNTI3OVpfMmM0MTc5NzctZTNkZC00Yjc0LTgzNDItYTgxY2NmNzY3ZjE0"
}For the next page: GET /v1/jobs?limit=1&cursor=<nextCursor>.
POST /v1/jobs (Bearer, role hrd)
// Request
{
"title": "Backend Engineer",
"description": "Bangun dan maintain layanan Go & Python...",
"requirements": "Minimal 2 tahun pengalaman Go\nPaham REST API",
"location": "Jakarta Selatan (Hybrid)",
"employmentType": "full-time",
"salaryMin": 12000000,
"salaryMax": 20000000,
"status": "published"
}// Response 201, same shape as an item in GET /v1/jobs
{ "id": "a7213f18-...", "companyId": "7a8d6652-...", "title": "Backend Engineer", "...": "..." }POST /v1/jobs/{jobId}/cv-upload-url (Bearer, role candidate)
// Response 200
{
"uploadUrl": "https://.../cv/e9f2155f-.../a7213f18-...-1784306575556814000.pdf?X-Amz-Algorithm=...",
"objectKey": "cv/e9f2155f-.../a7213f18-...-1784306575556814000.pdf"
}The browser PUTs straight to uploadUrl (valid for 10 minutes), never through
api-go. Hold on to objectKey, you'll need it for
POST /v1/cv-parser/parse on the ai-engine side.
POST /v1/cv-parser/parse (header X-Internal-Api-Key)
// Request
{ "cv_object_key": "cv/e9f2155f-.../a7213f18-...-....pdf", "application_id": "app-1" }// Response 200
{
"summary": "Software Engineer dengan 3 tahun pengalaman backend Go...",
"skills": ["Go", "PostgreSQL", "Docker"],
"work_experience_years": 3
}Returns 422 on unsupported file types, and on scanned PDFs with no extractable
text.
POST /v1/assessment/score-validation (header X-Internal-Api-Key)
// Request
{
"application_id": "app-1",
"responses": [
{ "question": "Ceritakan pengalaman lead sebuah tim", "answer": "..." }
]
}// Response 200
{
"recommendation_score": 82,
"authenticity_score": { "authentic": 70, "generic": 25, "aiGenerated": 5 }
}POST /v1/assessment/transcribe-interview (header X-Internal-Api-Key)
// Request
{ "application_id": "app-1", "audio_object_key": "interviews/app-1/rec.wav" }// Response 200
{
"transcript": "Jadi pengalaman saya di tim sebelumnya...",
"analysis_summary": "Kandidat menunjukkan pemahaman teknis yang solid dan komunikasi jelas."
}direkrut-ai/
├── apps/
│ ├── web/ Next.js, candidate portal + HRD dashboard
│ ├── api-go/ Golang REST API, business logic
│ └── ai-engine/ Python FastAPI, AI logic
├── packages/
│ └── contracts/ OpenAPI spec, the shared API contract
├── infra/
│ └── docker-compose.yml Postgres+pgvector, Redis, MinIO for local dev
└── .github/workflows/ CI per service (lint + test); api-go and ai-engine
auto-deploy to Heroku on push to `prod`, while
apps/web stays manual via Vercel
# 1. Bring up the infra dependencies (Postgres, Redis, MinIO)
yarn infra:up
# 2. Frontend
cd apps/web
yarn install
yarn dev # http://localhost:3000
# 3. Golang API (separate terminal)
cd apps/api-go
cp .env.example .env
# Forgot/reset password needs RESEND_API_KEY and EMAIL_FROM_ADDRESS.
go run ./cmd/server # http://localhost:8080
# 4. AI Engine (separate terminal)
cd apps/ai-engine
cp .env.example .env
python -m venv .venv && source .venv/bin/activate
pip install -r requirements-dev.txt
uvicorn app.main:app --reload # http://localhost:8000apps/web runs fine on its own without the other two services, falling back to
mock data in apps/web/src/services/. Set NEXT_PUBLIC_API_BASE_URL (see
apps/web/.env.local, which already points at the live api-go on Heroku) and
/candidate/jobs and /hrd/jobs will read real rows from the database
instead. A few service modules still fall back to mocks when the backend is
genuinely unreachable, but anything security-sensitive stays strict: changing
your email or password, deleting an account, forgot password, and reset
password all have to reach the real backend. Faking that state in the browser
is worse than failing loudly.
Past the boilerplate stage. In apps/api-go, auth (register with company
provisioning for HRD accounts, login, refresh-token rotation, forgot and reset
password through the mail server) and jobs (CRUD, cursor pagination, Redis
cache, presigned CV upload) are real, tested against actual Postgres+pgvector
and object storage, and live on Heroku. In apps/ai-engine, CV parsing (Groq
for text, Gemini for images) and assessment (scoring plus interview
transcription via Groq Whisper) are equally real, cached, and rate limited.
Subscriptions, payments, notifications, and vector search are still
placeholders sitting behind TODOs and 501s. The
API documentation above has the full breakdown of what
ships and what doesn't.