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.

v1.1: email radar, dedupe, tailor CV

Three new features help you move faster without missing anything.

Email radar on the Today page

The Today page now has two extra strips above the digest:

• Deadlines This Week shows upcoming application deadlines as cards. Cards turn red when the deadline is within two days. Click a card to jump to the application.
• Inbox Insights lists classified email suggestions (interview invite, rejection, question, noise) pulled from your inbox monitoring. Each card has Accept and Dismiss buttons. Accepted suggestions stay on file; dismissed ones disappear. A Recent Notifications mini-log at the bottom shows the last five system events so you can see what happened recently.

Dedupe in Research

The Research table now groups duplicate postings by cluster. When the same role appears through multiple agencies or sources, the cluster header shows "also via N more." Click the header to expand the alternates list and see all sources side by side with their scores. This saves you from applying to the same job three times.

Tailor CV

On any application detail page, click Tailor My CV to generate a CV variant tuned to that specific posting. The panel shows:

• A keyword coverage bar indicating how well your CV matches the posting description.
• A change log listing every modification (reordered sections, rephrased bullets). No facts are invented; only rephrased and reordered.
• A download link for the tailored CV as a PDF.

The tailored CV appears in the artifacts list for that application, ready to use in the approval and send flow.

Cost breakdown by provider

The Cost Summary on the Today page now includes a per-model breakdown table showing tokens in, tokens out, cost, and run count for each LLM model used. This helps you compare spending across providers at a glance.