Skip to content

Project Structure

This page describes the repository as it is today. Run git ls-files src frontend/src tests alembic for the authoritative list.

Repository Layout

kairos/
+-- pyproject.toml, uv.lock             # Project config and lockfile (uv)
+-- docker-compose.yml, Dockerfile      # PostgreSQL + FastAPI (+ frontend)
+-- alembic.ini, alembic/               # Migrations (env.py, versions/001 .. 008)
+-- Makefile                            # Canonical dev entry point (`make help`)
+-- mkdocs.yml, docs/                   # Documentation site (MkDocs Material)
|
+-- src/kairos/
|   +-- core/                           # Domain layer, no infrastructure deps
|   |   +-- entities/                   # Job, Resume, Skill, JdAnalysis, TailoredResume,
|   |   |                               #   SearchCriteria, Location, User, TailorEvent, LLM results
|   |   +-- interfaces/                 # ABCs: repositories + job search, JD analysis,
|   |   |                               #   tailoring, skill extraction, LLM client, renderer
|   |   +-- rendering/                  # Resume markdown assembly (header, merge, artifacts)
|   |   +-- config.py, errors.py        # TOML/env config loading, DomainError hierarchy
|   |   +-- resume_parser.py, section_mapping.py, llm_models.py
|   |
|   +-- api/                            # FastAPI app (prefix /api/v1/)
|   |   +-- main.py, config.py, deps.py # App factory, settings, DI + transactions
|   |   +-- auth.py                     # Single-user stub (no real authentication)
|   |   +-- errors.py, pagination.py    # RFC 9457 handlers, cursor pagination
|   |   +-- routes/                     # jobs, analysis, resumes, skills, tailoring, config, health
|   |   +-- services/                   # tailor_orchestrator
|   |   +-- ws/                         # WebSocket tailor stream
|   |
|   +-- db/                             # SQLAlchemy models, async session, repositories/
|   +-- platform/                       # Job sources: adzuna/, seek/, linkedin/, ats/,
|   |                                   #   shared http_client + rate_limiter
|   +-- llm/                            # Claude CLI + LiteLLM clients, analyzer, matching, skill extractor,
|   |                                   #   tailor, validation, streaming, retry, prompts/
|   +-- render/                         # html_renderer + themes/ (designed PDF/HTML), pandoc_renderer (LaTeX)
|   +-- secrets/                        # Keyring secret store + env injection
|   +-- cli/                            # Typer app (`kairos`): commands/, output.py
|   +-- report/                         # Telegram report channel (alerts, daily digest)
|
+-- frontend/src/                       # React 19 + Vite+ SPA
|   +-- api/                            # Typed fetch client for /api/v1/
|   +-- components/                     # Primitives, Icon, Sidebar, Topbar
|   +-- hooks/                          # useJobSearch, useJobDetail, useApplications,
|   |                                   #   useResumeForm, useSettings, useTailorStream
|   +-- lib/                            # Pure helpers (resume markdown, description cleanup)
|   +-- styles/                         # tokens.css, base.css
|   +-- views/                          # JobSearch, JobDetail, Applications, ResumeForm,
|                                       #   Settings, TailorPanel, SearchFilters
|
+-- tests/                              # pytest, one test_* package per source module
    +-- test_core/ test_api/ test_db/ test_llm/ test_platform/
    +-- test_render/ test_secrets/ test_cli/ test_report/ test_packaging.py

Module Dependency Graph

graph TD
    API[kairos.api] --> Core[kairos.core]
    API --> Platform[kairos.platform]
    API --> LLM[kairos.llm]
    API --> DB[kairos.db]
    API --> Render[kairos.render]
    API --> Secrets[kairos.secrets]

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

    CLI[kairos.cli] -.->|HTTP| API
    Web[frontend/] -.->|HTTP / WebSocket| API

    API --> Report[kairos.report]
    Report -->|alerts, digest| Telegram[(Telegram)]

The CLI has no client library: each command in src/kairos/cli/commands/ opens an httpx.AsyncClient against the API address from the config file ([api] host/port, with 0.0.0.0 mapped to 127.0.0.1). It imports kairos.core only for shared types.

kairos.report

kairos.report is the Telegram report channel, the one adapter of the ReportChannel port in kairos.core.interfaces.report_channel. It reports what the API's background pipeline did and never decides what the pipeline does.

  • The pipeline (kairos.api.background): harvest the boards every [jobs] harvest_hours, plus the company career boards in [jobs] ats_boards (Greenhouse, Lever and Ashby, filtered by ats_title_keywords and ats_locations), then score up to [jobs] fit_scoring_batch new postings, then send alerts. Availability re-checks every open posting within [jobs] availability_max_age_days (default 7), at most availability_batch per run.
  • Alerts: after each harvest, new postings scoring at least [report] alert_min_score (75) are sent once; jobs.notified_at records it.
  • Daily digest: at [report] digest_hour in [report] timezone, the postings scoring at least digest_min_score (60), then pipeline health: failed boards, unscored postings, overdue availability checks, archived postings and LLM spend.
  • Commands: kairos report digest sends the digest now (POST /api/v1/reports/digest); kairos report chat-id lists the chats that messaged the bot.
  • Bot: KAIROS_TELEGRAM_BOT_TOKEN and KAIROS_TELEGRAM_CHAT_ID from the environment; without them nothing is reported.

Security Notes

  • The API has no authentication. src/kairos/api/auth.py 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 of service and is the user's responsibility. Adzuna is the official API default.

Design Principles

  1. kairos.core has zero infrastructure dependencies — only stdlib + Pydantic
  2. One concept per file — each file owns one class/ABC
  3. Interfaces in core, implementations in infrastructure — ports-and-adapters pattern
  4. All I/O is async — via asyncio (FastAPI, httpx, asyncpg)
  5. Error types per module — each module defines its own exception hierarchy

Entry Points

Defined in pyproject.toml:

[project.scripts]
kairos = "kairos.cli.main:app"
kairos-server = "kairos.api.main:run"