SearchOps is a portfolio-grade job platform demo for SEO-ready public job pages, job search APIs, conversion tracking, A/B testing, observability, and automated verification.

Job marketplaces need crawlable job detail pages, reliable search/filter APIs, measurable apply funnels, and basic operational signals. This project demonstrates those concerns end to end with a TypeScript backend, a Next.js frontend, PostgreSQL data, Docker Compose, CI, Swagger/OpenAPI documentation, and Playwright E2E coverage.

Live demo: not deployed yet. Local Docker Compose is the supported demo path for now.

flowchart LR
  browser[Browser or crawler] --> frontend[Next.js App Router frontend<br/>localhost:3000]
  frontend --> api[Express TypeScript API<br/>localhost:5000]
  api --> db[(PostgreSQL 15)]
  api --> logs[Pino JSON logs]
  api --> metrics[/GET /metrics/]
  api --> docs[/GET /api-docs/]
  ci[GitHub Actions CI] --> api
  ci --> frontend
  ci --> e2e[Playwright E2E]

Backend APIs:

• GET /health
• GET /metrics
• GET /api/jobs with search, filters, sorting, and pagination
• GET /api/jobs/:slug
• POST /api/events
• GET /api/analytics/summary
• POST /api/experiments/apply-cta-assignment

SEO:

• Server-rendered /jobs listing and /jobs/[slug] detail pages
• JobPosting JSON-LD
• Canonical and Open Graph metadata
• sitemap.xml and robots.txt

Analytics and A/B testing:

• Job view, apply click, search, and filter event recording
• Stable anonymous apply CTA assignment
• Variant A: Apply now
• Variant B: Start your application
• Lightweight analytics summary and variant conversion calculation

Observability:

• Pino JSON request logs with request IDs and duration
• Prometheus-style /metrics
• HTTP request/error/duration metrics
• Local-only search latency simulation guarded by environment flags

Testing:

• Backend unit and integration tests
• Frontend rendering/SEO tests
• Playwright E2E journey from job listing to detail to apply CTA click
• GitHub Actions CI with PostgreSQL service container

Docker Compose is the supported local app demo path.

docker compose down -v
docker compose up -d postgres
docker compose build backend frontend
docker compose run --rm backend sh -lc "npx prisma generate && npx prisma migrate deploy && npx prisma db seed"
docker compose up --build

Open:

• Frontend: http://localhost:3000/jobs
• API health: http://localhost:5000/health
• Metrics: http://localhost:5000/metrics
• Swagger UI: http://localhost:5000/api-docs

docker compose up -d postgres
docker compose run --rm backend sh -lc "npx prisma generate && npx prisma migrate deploy && npx prisma db seed"
docker compose run --rm backend sh -lc "npm run lint && npm test && npm run build"
docker compose run --rm frontend sh -lc "npm run lint && npm test && npm run build"

Recommended Docker E2E workflow:

docker compose up -d postgres
docker compose run --rm backend sh -lc "npx prisma generate && npx prisma migrate deploy && npx prisma db seed"
docker compose up -d backend frontend
docker compose build frontend-e2e
docker compose run --rm frontend-e2e

Or run the E2E script explicitly inside the Playwright container:

docker compose run --rm frontend-e2e sh -lc "npm run test:e2e"

Do not run Playwright E2E inside the normal Alpine frontend service. The dedicated frontend-e2e service uses Microsoft’s Playwright image with the required browser runtime.

Optional host-machine workflow, when Node 20 and Playwright dependencies are available locally:

cd frontend
npm ci
npx playwright install chromium
PLAYWRIGHT_BASE_URL=http://localhost:3000 npm run test:e2e

PowerShell equivalent for the final command:

$env:PLAYWRIGHT_BASE_URL="http://localhost:3000"; npm run test:e2e

A local curl smoke-check log is included as evidence:

• docs/screenshots/API-check.txt

It verifies:

• GET /health
• GET /api/jobs?limit=3
• GET /api/jobs?q=backend&limit=3
• GET /api/jobs/backend-software-engineer-melbourne-seek
• POST /api/experiments/apply-cta-assignment
• POST /api/events for JOB_VIEW
• POST /api/events for APPLY_CLICK
• GET /api/analytics/summary

The captured run ends with:

===== API SMOKE CHECK PASSED =====

Recommended command if re-running locally:

./scripts/api-smoke-check.sh

If the script is not present, the same checks can be reproduced with curl against http://localhost:5000.

GitHub Actions workflow: .github/workflows/ci.yml

It runs on pull requests and pushes to main with a clean PostgreSQL service container. The job performs:

backend npm ci
backend prisma generate
backend prisma migrate deploy
backend prisma db seed
backend lint
backend tests
backend build
frontend npm ci
frontend lint
frontend tests
frontend build
Playwright E2E

No passing CI result is claimed here until GitHub Actions has actually run on the repository.

Source contract: docs/openapi.yaml

When the backend is running:

• Swagger UI: http://localhost:5000/api-docs
• Raw YAML through backend: http://localhost:5000/api-docs/openapi.yaml

/api-docs is developer documentation only, not a product API endpoint.

Screenshot and verification evidence is stored under docs/screenshots/.

Evidence checklist: docs/screenshots/README.md

Only real screenshots or real command outputs from a local run, CI run, or deployed environment should be committed. Generated placeholders, fake CI results, and fake deployment screenshots are intentionally excluded.

Postman collection: docs/postman/SearchOps.postman_collection.json

Postman is optional and is not part of CI. The committed curl smoke-check output is the current API verification evidence.

Backend:

• PORT default 5000
• DATABASE_URL PostgreSQL connection string
• NODE_ENV
• LOG_LEVEL
• SLOW_REQUEST_THRESHOLD_MS
• ENABLE_INCIDENT_SIMULATION

Frontend:

• BACKEND_API_URL default http://localhost:5000
• FRONTEND_SITE_URL default http://localhost:3000
• NEXT_TELEMETRY_DISABLED

E2E:

• PLAYWRIGHT_BASE_URL default http://localhost:3000, or http://frontend:3000 inside Docker Compose

• No production deployment yet
• No authentication, authorization, admin dashboard, or content management UI
• No real application submission flow; apply click shows a demo status message
• No full-text search index or relevance ranking
• No production monitoring stack, alerting, tracing, log aggregation, or dashboards
• A/B testing is deterministic and local-friendly, not a full experimentation platform
• GitHub Actions passing screenshot is not included until a real PR/run passes on GitHub
• No fake benchmark results, deployment URLs, or CI results are included

• Deploy frontend, backend, and PostgreSQL to a real hosting target
• Add secret management and production environment variables
• Run migrations through a controlled deployment job
• Add rate limiting, CORS policy, authentication, and admin workflows
• Add managed logs, metrics scraping, dashboards, alerts, and tracing
• Add search indexing and relevance ranking
• Add analytics warehouse/event pipeline and experiment analysis
• Add backup/restore, disaster recovery, and operational runbooks

• Architecture
• API Contract
• OpenAPI
• Testing Strategy
• SEO Strategy
• Observability
• Incident Response
• Experiment Plan
• Screenshot Checklist