Skip to content

Implementation Roadmap

Status: Phases 1–6 and the Settings slice have shipped, and the Phase 8 web views (search, job detail with JD analysis and tailoring, applications tracker, resume form, settings) are live. The job-search vertical uses Adzuna as the default source (Seek and LinkedIn adapters are opt-in), the FastAPI server at /api/v1/, and the CLI. The LLM layer (kairos.llm), pandoc rendering (kairos.render) and the keyring secret store (kairos.secrets) are in place, as is kairos.report, the Telegram channel that reports the API's single job pipeline (alerts and a daily digest). Phase 6 Indeed stays deferred (Cloudflare ban risk — Adzuna covers the same listings); Phase 7 polish is ongoing. The API has no authentication and must stay on 127.0.0.1.

Phase Overview

gantt
    title Kairos Implementation Phases
    dateFormat YYYY-MM-DD
    axisFormat %b %d

    section Phase 1 Skeleton + API
    Project setup + Docker Compose       :done, p1a, 2026-04-01, 2d
    Domain entities + interfaces (core)  :done, p1b, after p1a, 2d
    PostgreSQL models + migrations       :done, p1c, after p1b, 1d
    FastAPI server + core routes         :done, p1d, after p1b, 2d

    section Phase 2 Seek Search
    SeekClient + parser                  :done, p2a, after p1d, 3d
    PostgreSQL job repository            :done, p2b, after p1c, 1d
    Job search + list API endpoints      :done, p2c, after p2a, 1d

    section Phase 3 LLM Analysis
    LiteLLM client setup                 :done, p3a, after p2c, 2d
    JD analysis + match scoring          :done, p3b, after p3a, 2d
    Analysis API endpoints               :done, p3c, after p3b, 1d

    section Phase 4 Resume Tailoring
    Resume parser + import               :done, p4a, after p3c, 2d
    Tailoring prompts + validation       :done, p4b, after p4a, 3d
    Resume API endpoints + WebSocket     :done, p4c, after p4b, 1d

    section Phase 5 CLI
    Typer commands (httpx to the API)    :done, p5a, after p1d, 3d
    Rich output formatting               :done, p5b, after p5a, 1d

    section Settings + Secrets
    Keyring secret store                 :done, psa, after p4c, 1d
    LLM key + settings API               :done, psb, after psa, 1d
    Settings + Resume form UI            :done, psc, after psb, 2d

    section Phase 6 Apply + Track
    Apply workflow + browser open        :done, p6a, after psc, 1d
    Application tracking                 :done, p6b, after p6a, 2d
    Indeed adapter (deferred)            :p6c, after p6a, 3d

    section Phase 7 Polish
    Error handling + edge cases          :p7a, after p6c, 2d
    CLI UX polish                        :p7b, after p7a, 2d

    section Phase 8 Web Frontend
    React project setup                  :done, p8a, after p1d, 2d
    Core views (search + resume + settings) :done, p8b, after p8a, 5d
    Job detail + JD analysis + tracker UI :done, p8c, after p8b, 3d

Phase Details

Phase 1: Skeleton + API ✅ Shipped

Goal: Working project with a running FastAPI server and PostgreSQL.

  • Init Python project with uv init, configure pyproject.toml
  • Docker Compose: PostgreSQL 18 + FastAPI (hot reload)
  • Define all entities in kairos.core (Pydantic models)
  • Define all interfaces (ABCs for Repository + Service)
  • Define exception hierarchy per module
  • Config loading via pydantic-settings (TOML + env vars)
  • PostgreSQL setup + Alembic migrations (001 initial jobs, 002 cursor index, 003 owner_id; later 004–008 add resumes, skills, JD analyses, tailored resumes and apply tracking)
  • FastAPI server with health check, RFC 9457 problem+json errors (no envelope), middleware stack

Verify: docker compose up -d succeeds. curl localhost:8880/api/v1/health/ returns 200.

Phase 2: Job Search ✅ Shipped

Goal: Search jobs across multiple platforms via API.

  • AdzunaSearchService (HTTP API, default source — free, structured JSON, no scraping)
  • SeekClient + LinkedInClient with httpx + beautifulsoup4, opt-in via [search] platforms (scraping may breach those sites' terms; the user's responsibility)
  • Rate limiter with randomized delays for scrapers
  • PostgreSQL job repository (SQLAlchemy, owner-scoped)
  • API endpoints: POST /api/v1/jobs/search, GET /api/v1/jobs (cursor-paginated), GET /api/v1/jobs/{id}, POST /api/v1/jobs/{id}/fetch-details, DELETE /api/v1/jobs/{id}
  • Backend pytest suite locks the contract

Verify: curl -X POST localhost:8880/api/v1/jobs/search -d '{"keywords":"rust","country":"AU","location":"Perth"}' returns results.

Phase 3: LLM Analysis ✅ Shipped

Goal: Analyze JDs with an LLM via API.

  • LiteLLM async client (LiteLlmClient, multi-provider) with mapped error hierarchy
  • JD analysis + skill-extraction prompt templates
  • Analyzer + SkillExtractor with Pydantic structured output and match scoring
  • API endpoints: POST /api/v1/jobs/{id}/analyze, GET /api/v1/jobs/{id}/analysis, plus the /api/v1/skills Skill Profile CRUD
  • JdAnalysis persisted (migration 006)

Verify: POST /api/v1/jobs/{id}/analyze returns analysis with match score.

Phase 4: Resume Tailoring ✅ Shipped

Goal: Import resume, tailor per JD via API, with WebSocket streaming.

  • Resume section parser + import flow, PostgreSQL resume repository (migration 004)
  • Tailor with anti-hallucination prompts + a validation pass (validation.py)
  • API endpoints: resume CRUD under /api/v1/resumes (incl. set-base and per-section patch), POST /api/v1/jobs/{id}/tailor, GET /api/v1/jobs/{id}/tailored-resume, POST /api/v1/tailored-resumes/{id}/approve, POST /api/v1/tailored-resumes/{id}/export
  • WebSocket streaming of TailorEvents at WS /api/v1/jobs/{id}/tailor/stream (kairos.llm.streaming + kairos.api.ws.tailor)
  • Pandoc-based rendering in kairos.render (migration 007 stores tailored resumes)

Verify: Full resume flow works via API: import → tailor → approve → export.

Phase 5: CLI ✅ Shipped

Goal: Lightweight command-line client for scripting and daily use.

  • Typer-based command structure; each command calls the API directly with httpx
  • Commands: jobs search/list/view, resumes import/list/delete/tailor/export, skills extract/list, plus config and init
  • Rich output formatting (tables)

Verify: kairos jobs search "rust" --location perth returns results.

Settings + Secrets ✅ Shipped

Goal: Manage LLM provider keys and settings safely, from the API and the web UI.

  • Keyring-backed secret store (kairos.secrets.secret_store) + env injection on startup
  • LLM key + settings API: GET/PATCH /api/v1/config/llm, GET /api/v1/config/llm/models, POST /api/v1/config/llm/key, DELETE /api/v1/config/llm/key/{env_var}
  • Frontend Settings view (LLM key + model UI) and ResumeForm view, wired via the useSettings / useResumeForm hooks, with Sidebar/Topbar nav

Verify: Set an LLM key in the Settings view → POST /api/v1/jobs/{id}/analyze succeeds.

Phase 6: Apply + Track ✅ Shipped

Goal: Complete semi-automatic workflow.

  • Apply action (open browser with application URL)
  • Application tracking API endpoints (migration 008)
  • ~~Indeed adapter (playwright)~~ — deferred, Cloudflare ban risk
  • ~~LinkedIn adapter~~ ✅ shipped in Phase 2 (public guest API, httpx + bs4)

Verify: Full flow: search → analyze → tailor → apply → track.

Phase 7: Polish

Goal: Production-quality UX.

  • Graceful error handling across API and CLI
  • CLI: colorized output, progress spinners, help text
  • Resume export (PDF/LaTeX)
  • API rate limits, retries, and edge case handling

Phase 8: Web Frontend (React) ◐ Core views shipped

Goal: Browser-based access to all Kairos features.

  • ✅ React 19 + Vite+ + TypeScript scaffold with token-based design system (Phase 8a)
  • ✅ Core search view: filter panel matching all CLI flags, cursor pagination, per-platform error surfacing (Phase 8b)
  • ✅ ResumeForm and Settings views (resume import/edit + LLM key/model), Sidebar/Topbar nav
  • ✅ Job detail view + JD analysis surface (Phase 8c)
  • ✅ Tailoring panel consuming WS /api/v1/jobs/{id}/tailor/stream (useTailorStream)
  • ✅ Applications tracker view (Phase 8e)
  • Resume tailor diff viewer (planned, Phase 8d)
  • Responsive design polish for mobile access (planned)

Verify: Open browser → search → analyze → tailor → track — full workflow.

Definition of Done

  • All tests pass with pytest
  • ruff check and ruff format pass with no issues
  • Core workflow works end-to-end (search → analyze → tailor → apply → track)
  • The Adzuna adapter is fully functional
  • Resume tailoring produces valid LaTeX output
  • API server handles all core operations via REST + WebSocket
  • CLI can perform the full workflow via API
  • All frontends produce consistent behavior through the unified API
  • API keys and JWT secrets handled securely (env var or config, never logged)
  • docker compose up -d brings up the full stack