Hirevine — engineering guide

This repository (hirevine-meta) is the umbrella checkout for the Hirevine stack. It does not ship application code itself; it pins three services as Git submodules so you can clone one workspace, align versions, and onboard engineers from a single document.

Service	Submodule	Responsibility
API	hirevine-v2-be	Express API, MongoDB, JWT (httpOnly cookie), orgs/jobs/applications, resume uploads (Vercel Blob), OpenAPI + Swagger UI, pipeline execution via Inngest
Product app	hirevine-v2-web	Next.js app for recruiters and candidates: jobs, applications, pipeline UI; talks to the API with NEXT_PUBLIC_API_URL
Marketing	hirevine-marketing-website	Next.js marketing site; CTAs deep-link to the product app (NEXT_PUBLIC_APP_URL)

Prerequisites everywhere: Node.js 20+, MongoDB (local or Atlas) for the API. Each submodule has its own package.json and .env.example (or .env.example → .env.local for Next apps).

---

Clone this workspace

git clone --recurse-submodules https://github.com/deagleSC/hirevine-meta.git
cd hirevine-meta

Already cloned without submodules:

git submodule update --init --recursive

Editor: open hirevine.code-workspace in VS Code or Cursor for a multi-root workspace over all three submodules.

---

System architecture

Traffic is split by role: marketing is mostly static/SSR pages plus links into the product; the product owns authenticated flows and direct API access. The API owns persistence, blob storage for resumes, and background pipeline work through Inngest.

flowchart TB
  subgraph clients["Clients"]
    U[("Users")]
  end

  subgraph browser["Browser"]
    MW["Marketing\nNext.js"]
    PW["Product app\nNext.js"]
  end

  subgraph servers["Application tier"]
    API["API\nExpress + TypeScript"]
    DB[("MongoDB")]
    Blob[("Vercel Blob")]
    ING["Inngest\npipeline runs"]
  end

  U --> MW
  U --> PW
  MW -->|"NEXT_PUBLIC_APP_URL"| PW
  PW -->|"NEXT_PUBLIC_API_URL\nREST, credentials"| API
  API --> DB
  API --> Blob
  API --> ING

Loading

Engineering implications

• Marketing and product are different origins in production; the API’s CORS_ORIGIN must list origins that send credentialed requests (typically the product app). Marketing does not need to call the API for core flows.
• NEXT_PUBLIC_* on both Next apps is inlined at build time; changing Vercel env vars requires a redeploy of that frontend.
• Session auth uses a JWT in an httpOnly cookie (AUTH_COOKIE_NAME, default hirevine_session); see hirevine-v2-be for production cookie and CORS requirements.

---

Authentication and cross-origin behavior

Topic	Detail
Session	JWT in an httpOnly cookie; JSON responses may also expose the token for Bearer use where supported
Browser → API	Product client uses credentialed requests (withCredentials / credentials: "include")
CORS	CORS_ORIGIN must list the exact frontend origin(s) (scheme + host + port). Comma-separated, no spaces after commas
Production secrets	JWT_SECRET is required when NODE_ENV=production; configure Inngest, Blob, and any LLM keys per hirevine-v2-be

---

HTTP API surface (hirevine-v2-be)

Interactive docs: Swagger UI when the server is running (see hirevine-v2-be README). OpenAPI is served from the API (e.g. /openapi.json).

Area	Notes
Auth	Register, login, logout, session / me
Organizations & jobs	Recruiter/admin flows; public job listing where applicable
Applications	Apply with resume URL, candidate and recruiter views, quiz stages, pipeline results
Uploads	Resume multipart upload to Vercel Blob
System	Health, Inngest endpoint (/api/inngest), metadata

For request/response shapes and codes, rely on the OpenAPI description in the backend repo.

---

Environment variables

Copy each submodule’s .env.example → .env (API) or .env.local (Next apps). Authoritative comments live in those files; below is a concise reference.

API — hirevine-v2-be

Variable	Production	Purpose
NODE_ENV	Set production	Runtime mode
PORT	Optional	HTTP port; default 8000 locally
MONGODB_URI	Required for real data	Mongo connection string
CORS_ORIGIN	Required for credentialed SPA	Allowed browser origins
JWT_SECRET	Required	JWT signing key
JWT_EXPIRES_SEC	Optional	Session length
AUTH_COOKIE_NAME	Optional	Cookie name (default hirevine_session)
AUTH_COOKIE_SECURE, AUTH_COOKIE_SAMESITE	As needed	Cookie behavior for your deployment
Blob / Inngest / LLM	Per .env.example	Resume storage and pipeline execution

Product app — hirevine-v2-web

Variable	Notes
NEXT_PUBLIC_API_URL	API base URL, no trailing slash; must match a CORS_ORIGIN entry
NEXT_PUBLIC_SITE_URL	Canonical URL for metadata / OG; Vercel can infer via VERCEL_URL if unset

Marketing — hirevine-marketing-website

Variable	Notes
NEXT_PUBLIC_SITE_URL	Canonical marketing site URL (no trailing slash)
NEXT_PUBLIC_APP_URL	Product app URL for CTAs (no trailing slash)

---

Local development

Default ports

Service	Default port	Override
API	8000	PORT in .env
Product (Next)	3000	next dev -p …
Marketing (Next)	3000	Run as npm run dev -- -p 3001 if product already uses 3000

Recommended order

1. Start MongoDB (local default often mongodb://127.0.0.1:27017/hirevine if MONGODB_URI unset — confirm in hirevine-v2-be env docs).
2. API: cd hirevine-v2-be && npm install && cp .env.example .env → edit → npm run dev. Verify health (and OpenAPI) per backend README.
3. Product: cd hirevine-v2-web && npm install && cp .env.example .env.local → set NEXT_PUBLIC_API_URL to the API → ensure API CORS_ORIGIN includes the product dev origin → npm run dev.
4. Marketing (optional): cd hirevine-marketing-website && npm install && cp .env.example .env.local → set NEXT_PUBLIC_APP_URL to the product dev URL → npm run dev -- -p 3001.

---

Tech stack (summary)

Layer	Technologies
API	Express, TypeScript, MongoDB/Mongoose, JWT, cookie-parser, OpenAPI/Swagger, Inngest, Vercel Blob
Product	Next.js (App Router), React, TypeScript, Tailwind
Marketing	Next.js, React, TypeScript

---

Build, quality, and formatting

Location	Common commands
hirevine-v2-be	npm run build; npm run dev; npm start; npm run typecheck; see submodule package.json for tests
hirevine-v2-web	npm run build; npm run dev; npm run lint
hirevine-marketing-website	npm run build; npm run dev; npm run lint

---

Deployment (typical: Vercel / cloud)

1. Separate deployables: API, product, and marketing usually each have their own Git repository and CI/CD (unless you use a monorepo-specific pipeline).
2. API: set production variables from the API table and submodule docs; confirm CORS_ORIGIN includes the deployed product URL exactly.
3. Product: set NEXT_PUBLIC_API_URL to the deployed API origin; set NEXT_PUBLIC_SITE_URL to the deployed app URL where needed.
4. Marketing: set NEXT_PUBLIC_SITE_URL and NEXT_PUBLIC_APP_URL to deployed marketing and product URLs.
5. After changing any NEXT_PUBLIC_* variable, redeploy that Next.js project.

---

Git: submodules and pinning

• Application history lives in each submodule’s remote. Commit and push inside hirevine-v2-be, hirevine-v2-web, or hirevine-marketing-website on the appropriate branch.

• This meta repo records which commit each submodule points to. After updating submodules, commit here if you want the team to share the same SHAs:

  cd hirevine-v2-web   # example
  git pull origin main
  cd ..
  git add hirevine-v2-web
  git commit -m "chore: bump hirevine-v2-web"

• Pull latest submodule commits from their remotes (use with care; review diffs):

  git submodule update --remote --merge

---

Production checklist (short)

• JWT_SECRET set and rotation policy defined
• MONGODB_URI points to production cluster
• CORS_ORIGIN matches deployed product origin(s)
• Cookie / AUTH_COOKIE_* behavior validated for your domains
• Inngest, Vercel Blob, and LLM-related keys configured per backend
• All NEXT_PUBLIC_* values correct and frontends redeployed after changes

For deeper detail per service, see each submodule’s README.md and .env.example.