Status: Draft (hackathon build, March 2026) Last updated: 2026-03-08 Base URL (local):
http://localhost:3000Base URL (production):https://workforce-pulse.vercel.app
All responses are JSON unless noted. Server-side API keys are never exposed to the client.
The project has two layers working together:
| Layer | Location | Framework | Role |
|---|---|---|---|
| Frontend + API routes | src/app/api/ |
Next.js App Router | UI, public endpoints, AI routes |
| Backend server | backend/ |
Node.js + MongoDB | Data ingestion, job storage, aggregation |
The Next.js frontend consumes its own /api/* routes. The backend/ Node.js server handles data ingestion from JobAps, USAJOBS, and Bright Data, storing results in MongoDB. The frontend API routes read from MongoDB (via the backend) or fall back to src/data/mock-*.ts fixtures during development.
The shared data contract between layers is the JobPosting type defined in src/data/mock-jobs.ts. Both layers must produce and consume this shape.
Backend integration status (as of 2026-03-08): MongoDB connection is actively being integrated. If the backend is unavailable, all endpoints fall back to mock data automatically.
| Variable | Required | Used by |
|---|---|---|
USAJOBS_API_KEY |
Yes (for USAJOBS) | /api/jobs/aggregate |
USAJOBS_USER_AGENT |
Yes (for USAJOBS, use your email) | /api/jobs/aggregate |
GEMINI_API_KEY |
Yes (for AI features) | /api/ai/chat, /api/ai/learning-path |
MONGODB_URI |
Yes (for backend) | backend/ Node.js server |
BRIGHT_DATA_BROWSER_WSS |
Optional | /api/jobs/scrape |
BRIGHT_DATA_API_KEY |
Optional | /api/crawl/* |
JOBAPS_RSS_URL |
Optional (has default) | /api/jobs/aggregate |
NEXT_PUBLIC_ARCGIS_* |
Optional | ArcGIS feature layers |
Returns a list of job postings accessible without authentication. Intended for the public-facing job board — visible to any Montgomery resident without signing in. Supports keyword search and basic filtering.
Query Parameters
| Param | Type | Default | Description |
|---|---|---|---|
q |
string | — | Keyword search (title, org, skills) |
sector |
string | all | Filter by sector slug, e.g. public-safety |
source |
string | all | Filter by source: jobaps, usajobs, indeed |
limit |
number | 20 | Max results to return |
offset |
number | 0 | Pagination offset |
Response 200 OK
{
"jobs": [
{
"id": "string",
"title": "Firefighter I",
"source": "jobaps | usajobs | indeed",
"sector": "public-safety",
"org": "City of Montgomery Fire Department",
"location": "Montgomery, AL",
"postedAt": "2026-03-01T00:00:00Z",
"skills": ["CPR", "Hazmat", "Emergency Response"],
"critical": true,
"url": "https://..."
}
],
"meta": {
"total": 142,
"query": "firefighter",
"sources": ["jobaps", "usajobs"]
}
}Note: This endpoint returns a safe subset of job data — no internal analytics, Impact Scores, or mission data. Those remain behind authentication.
All endpoints below require a valid session. Unauthenticated requests return 401.
Fetches and merges job listings from all configured sources. Results refreshed daily at midnight UTC via Vercel Cron. Returns full job objects including critical flag and sector metadata.
Query Parameters
| Param | Type | Default | Description |
|---|---|---|---|
sector |
string | all | Filter by sector slug |
refresh |
boolean | false | Force a fresh fetch, bypassing cache |
Response 200 OK — same job shape as /api/jobs/public plus:
{
"jobs": [ /* full JobPosting shape */ ],
"meta": {
"total": 142,
"lastRefreshed": "2026-03-08T00:00:00Z",
"sources": ["jobaps", "usajobs"],
"backendConnected": true
}
}Error Responses
| Status | Meaning |
|---|---|
401 |
Not authenticated |
500 |
One or more sources failed; partial results returned |
503 |
All sources unavailable — falls back to mock data |
Triggers a live Indeed scrape via Bright Data Scraping Browser. Returns 503 if account is suspended — fall back gracefully to JobAps + USAJOBS.
Request Body
{
"keyword": "firefighter",
"location": "Montgomery, AL",
"limit": 20
}Response 200 OK
{
"scraped": 18,
"jobs": [ /* same shape as aggregate response */ ]
}Initiates a Bright Data dataset crawl for LinkedIn or Glassdoor enrichment.
Request Body
{
"datasetId": "string",
"urls": ["https://www.linkedin.com/jobs/..."]
}Response 202 Accepted
{
"snapshotId": "snap_abc123",
"status": "pending",
"pollUrl": "/api/crawl/status/snap_abc123"
}Response 200 OK
{
"snapshotId": "snap_abc123",
"status": "pending | ready | failed",
"resultUrl": "https://..."
}Returns hiring trend signals — rising skills, sector pressure, critical roles. Falls back to src/data/mock-pulse.ts if analytics layer not yet built.
Query Parameters
| Param | Type | Default | Description |
|---|---|---|---|
sector |
string | all | Sector slug |
window |
string | 30d |
7d, 30d, 90d |
Response 200 OK
{
"risingSkills": [
{ "skill": "Crisis Intervention", "growthPct": 42, "sector": "public-safety" }
],
"criticalRoles": [
{ "role": "Police Officer", "openings": 31, "urgency": "high" }
],
"sectorPressure": [
{ "sector": "public-safety", "impactScore": 87 }
]
}Conversational endpoint powered by Gemini API, grounded in current Montgomery job data.
Request Body
{
"messages": [
{ "role": "user", "content": "What skills do I need to become a firefighter in Montgomery?" }
],
"context": { "sector": "public-safety" }
}Response 200 OK
{
"reply": "To qualify for a Firefighter I role in Montgomery...",
"suggestedJobs": [ /* optional */ ]
}Generates a personalised career roadmap for a given target role.
Request Body
{
"currentSkills": ["Logistics Coordinator", "Basic SQL"],
"targetRole": "Senior Logistics Analyst",
"sector": "technology"
}Response 200 OK
{
"estimatedMonths": 4.5,
"progressPct": 35,
"milestones": [
{ "step": 1, "label": "Current Skills", "status": "verified" },
{ "step": 2, "label": "Skill Gap Analysis", "status": "in-progress" },
{ "step": 3, "label": "AI Specialization", "status": "recommended" },
{ "step": 4, "label": "Target Role Reached", "status": "goal" }
],
"topRecommendations": [
{ "title": "Advanced SQL for Data Analytics", "provider": "Coursera", "durationHours": 12, "free": true }
]
}Error Responses (both AI endpoints)
| Status | Meaning |
|---|---|
400 |
Empty or malformed messages array |
503 |
GEMINI_API_KEY not configured |
{
"missions": [
{
"id": "mission_001",
"title": "Boost Firefighter Recruitment Q2 2026",
"sector": "public-safety",
"tasks": [
{ "id": "t1", "label": "Post on JobAps", "done": true },
{ "id": "t2", "label": "Partner with AIDT training", "done": false }
],
"progress": 0.5
}
]
}{ "taskId": "t2" }{
"playbooks": [
{ "id": "pb_001", "title": "Public Safety Hiring Sprint", "likes": 4, "saved": true, "steps": ["string"] }
]
}Called by Vercel Cron once daily at midnight UTC. Protected via CRON_SECRET header.
| File | Powers |
|---|---|
src/data/mock-jobs.ts |
All job listing endpoints |
src/data/mock-pulse.ts |
Trends, sectors, missions, playbooks, daily pulse |
- Public job board (
/api/jobs/public) requires no auth — safe to call from any page including the landing page. - All analytics, missions, and playbooks endpoints require authentication.
- MongoDB URI must be set in both
.env.local(frontend) andbackend/.env(Node.js server). - All AI endpoints require
GEMINI_API_KEY. Free key at Google AI Studio. - Bright Data returns
503if account is suspended — always fall back to JobAps + USAJOBS gracefully.