_private/qwestly-docs/Engineering/main-applications.md

Table of Contents

Main applications and APIs

This page summarizes Qwestly’s primary product and web repos—their roles, where APIs belong, and links to GitHub—with typical local clones sitting beside qwestly-docs in the same workspace.

Primary repositories

Application Typical repo folder Role
Candidate app candidate Candidate-facing product surface (app.qwestly.com).
Hire app qwestly-hire Hiring-side product surface (hire.qwestly.com).
Public site public-site Marketing site (www.qwestly.com), Next.js (qwestly-public-site).
Python API api-python Shared or internal backends that are not owned by a single Next.js app.

Repositories

Source for each surface is on GitHub; clone beside qwestly-docs in your workspace when developing locally.

  • candidate — Qwestly Candidate Portal (Next.js): candidate-facing app for onboarding, profile, interviews (Vapi), and related Candidate-owned Next.js APIs.
  • qwestly-hire — Qwestly Hire (Next.js): hiring platform where companies manage job postings, organizations, and candidate matches, with both public-facing and admin workflows.
  • public-site — Qwestly public / marketing site (Next.js package qwestly-public-site): qwestly.com and related marketing pages; may include Next.js routes for that surface only.
  • api-python — Qwestly API (Python / FastAPI): shared HTTP services—including document parsing and RAG, auth flows, storage, SendGrid email webhooks, and other cross-app or internal endpoints (see Internal and shared services in api-python).

Where APIs live

  • Candidate, Hire, and Public site (Next.js): Each Next.js repo includes its own backend/API where needed (Route Handlers and related server code). Prefer keeping endpoints with the codebase that owns that UX and auth context.

  • api-python: Use this for internal, cross-cutting, or general HTTP services that are not tied to one app’s surface—shared jobs, internal tools, or APIs that multiple clients call without being “the Candidate API” or “the Hire API” by definition. Conventions for internal routes, referrer checks, and the qwestly_internal database are in Internal and shared services in api-python.

When you add a new endpoint, choose the repo by who owns the contract and who calls it: app-scoped behavior usually stays in that app’s Next.js API; otherwise consider api-python.

Document owner: Engineering
Last updated: May 1, 2026