jobhunt-platform/docs/user-guide.md

User Guide

A practical guide for getting started with Jobhunt Platform. Written for first-time users who want to land a job quickly.

Installation

Prerequisites

• Docker and Docker Compose installed on your machine
• Node.js 22 (for the web frontend, only needed if running the dev server on the host)

Quick start

1. Clone the repository and enter the project directory.
2. Copy the environment template: cp .env.example .env
3. Start the database and run the API tests:

docker compose run --rm api-test

4. Start the API server:

docker rm -f jobhunt-api 2>/dev/null
docker compose run -d --name jobhunt-api \
  --entrypoint "uvicorn app.main:app --host 0.0.0.0 --port 8000" api-test

5. In a separate terminal, start the web frontend:

cd apps/web
npm install
VITE_API_BASE=http://localhost:8000/api npm run dev

6. Open the web app in your browser (typically http://localhost:5173).

You do NOT need any LLM API keys. The system runs in mock mode by default, which produces deterministic outputs. Add a key to .env only when you want real AI responses.

First run: the onboarding wizard

When you open the app for the first time, the onboarding wizard appears at /welcome. It has four steps:

1. Welcome - a short introduction to the platform.
2. Import CV - upload a PDF, DOCX, or plain text file of your existing CV. The system extracts sections (experience, education, skills, projects) for you to review. You can edit them before confirming. If you do not have a CV file handy, you can skip this step and add sections manually later in the CV tab.
3. Fetch Postings - search for job postings from the Arbetsformedlingen connector. Enter a search query (for example "python developer") and optionally a region. New postings are added to your applications as "discovered". You can skip this step too.
4. Done - you are ready to go. Click "Go to Today" to see your dashboard.

The Today page

The Today page (/today) is your daily dashboard. It shows three things:

• Top Matches - ranked job postings scored against your profile. Click a card to open the application detail page.
• Follow-up Nudges - applications you sent more than 7 days ago with no reply. Each nudge includes a suggested follow-up message. Click "Copy follow-up draft" to copy the text to your clipboard, then paste it into your email client.
• Pending Approvals - a count of outgoing actions (emails, submissions) waiting for your confirmation.

At the bottom of the Today page, the Cost Summary shows total tokens used (input and output) and the total cost if pricing is configured. This helps you track your LLM spending.

CV editor

The CV tab lets you manage your profile and CV sections. You can:

• Edit your name, email, phone, location, headline, and summary.
• Add, edit, and delete sections (experience, education, skills, projects, other).
• Use AI Assist to get suggestions for improving bullet points.
• Render your CV to a PDF for download.

Research

The Research tab has two ways to find job postings:

1. Fetch from Arbetsformedlingen - enter a search query and optional region to pull postings from the official Swedish public employment service. New postings are created automatically.
2. Add by URL - paste any job posting URL to add it manually.

The postings table includes a Scam column. If the scoring system detects red flags (such as unpaid trial periods or requests for personal financial data), a warning symbol appears with a tooltip listing the specific concerns.

Click "Score" on any posting to run the scoring rubric against your profile. The score appears as a green badge.

Applications (kanban)

The Applications tab shows all your job applications as cards on a kanban board, organized by state:

• discovered, scored, approved, drafting, sent, interviewing, offer, closed, rejected, expired

You can drag cards between columns to change their state. The board enforces valid transitions (some moves are not allowed and will be rejected).

Two visual indicators appear on cards:

• Red flag badge (warning symbol) - the scoring system detected potential scam or fraud indicators. Hover over the symbol to see the specific red flags.
• Nudge dot (orange dot) - this application has a follow-up nudge, meaning you sent it more than 7 days ago without a reply. Visit the Today page for the suggested follow-up message.

Application detail

Click any application card to open its detail page. Here you can:

• View the posting information, current state, and score.
• Interview Prep - click "Open Interview Prep" to generate likely interview questions with suggested answers based on your profile and the job posting. The content is saved as an artifact. You can edit the text and save a new version, or regenerate it.
• View all artifacts (cover letters, CVs, interview prep, etc.).
• Write and save a cover letter. The system provides an AI critique with severity-tagged suggestions.
• Request approval, confirm it, and send. The approval gate ensures nothing is sent without your explicit confirmation. The system verifies the artifact hash before sending.

Costs

Every LLM call (scoring, extraction, critique, interview prep) is tracked. The Cost Summary on the Today page shows:

• Total tokens consumed (input and output)
• Total cost (if pricing is configured)
• Number of task runs

This transparency helps you make informed decisions about when to use AI features, especially if you are counting kronor.

Tips

• Run without API keys first to explore the platform with mock data. Use POST /concierge/seed-demo (via curl or the API) to populate demo data instantly.
• Check the Today page daily for new nudges and digest items.
• Always review AI-generated content before sending. The system assists you, but you are the decision maker.
• Use the scam/red-flag indicators to avoid suspicious postings.