Skip to content

Architecture Overview

Kairos follows Clean Architecture with a Python package separating concerns into independent modules. Two frontends (CLI, Web) share a single FastAPI backend. The API's background loops run one job pipeline (harvest, score, re-check) and report it to Telegram through kairos.report.

High-Level Architecture

graph TB
    subgraph Frontend Layer
        CLI["kairos.cli\ntyper + httpx"]
        Web["Web App\nReact 19 + Vite+"]
    end

    subgraph API Layer
        API["kairos.api\nFastAPI + uvicorn"]
    end

    subgraph Application Layer
        Core["kairos.core\nEntities + Interfaces"]
    end

    subgraph Infrastructure Layer
        Platform["kairos.platform\nAdzuna (default) / Seek / LinkedIn (opt-in)"]
        LLM["kairos.llm\nClaude Code or LiteLLM"]
        DB["kairos.db\nSQLAlchemy + PostgreSQL"]
        Render["kairos.render\npandoc"]
    end

    CLI --> API
    Web --> API

    API --> Core
    Platform --> Core
    LLM --> Core
    DB --> Core
    Render --> Core

Dependency Flow

kairos.api (FastAPI server — the unified backend)
  +-- kairos.core (domain: entities, interfaces, errors)
  +-- kairos.platform (implements JobSearchService)
  +-- kairos.llm (implements JdAnalysisService, ResumeTailorService, SkillExtractorService)
  +-- kairos.db (implements *Repository ABCs)
  +-- kairos.render (implements ResumeRenderer)
  +-- kairos.secrets (keyring-backed API key storage)
  +-- kairos.report (implements ReportChannel: Telegram alerts and digest)

kairos.cli (HTTP client — httpx calls straight to the API)
  +-- kairos.core (shared types and config only)

Rule: Infrastructure modules depend on kairos.core for interface definitions. kairos.core depends on nothing external — it's the innermost layer. The CLI and the web app reach the data only through kairos.api.

Module Responsibilities

Module Responsibility Key Interface
kairos.core Domain entities, service ABCs, error types, config All ABC definitions
kairos.api FastAPI HTTP server, routes, WebSocket — (entry point)
kairos.cli Command-line HTTP client (httpx per command) — (entry point)
kairos.platform Job data from the Adzuna API; opt-in Seek/LinkedIn scrapers JobSearchService
kairos.llm Fit scoring, JD analysis, skill extraction, resume tailoring via Claude Code or LiteLLM ([llm] backend) JdAnalysisService, ResumeTailorService, SkillExtractorService
kairos.db PostgreSQL persistence via SQLAlchemy JobRepository, ResumeRepository, SkillRepository, JdAnalysisRepository, TailoredResumeRepository
kairos.render Resume export via pandoc ResumeRenderer
kairos.secrets Keyring secret store, env injection — (library)
kairos.report Telegram report channel: alerts for new high-fit postings and a daily digest with pipeline health ReportChannel

Security Model

  • The API has no authentication: kairos.api.auth.get_current_user returns a fixed single-user stub. It binds to 127.0.0.1 by default and must not be exposed to a network.
  • Seek and LinkedIn adapters are opt-in ([search] platforms defaults to ["adzuna"]). Scraping them may breach those sites' terms and is the user's responsibility. Adzuna is the official API.

Async Architecture

flowchart LR
    subgraph API Server
        Routes[FastAPI Routes]
        Tailor["Tailor Resume\nstreamed events"]
    end

    Clients["CLI / Web"] --> |HTTP| Routes
    Routes --> Tailor
    Tailor --> |WebSocket| Clients

All I/O is async. Resume tailoring streams TailorEvents to the client over WS /api/v1/jobs/{id}/tailor/stream; other endpoints are plain request/response.