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 byats_title_keywordsandats_locations), then score up to[jobs] fit_scoring_batchnew postings, then send alerts. Availability re-checks every open posting within[jobs] availability_max_age_days(default 7), at mostavailability_batchper run. - Alerts: after each harvest, new postings scoring at least
[report] alert_min_score(75) are sent once;jobs.notified_atrecords it. - Daily digest: at
[report] digest_hourin[report] timezone, the postings scoring at leastdigest_min_score(60), then pipeline health: failed boards, unscored postings, overdue availability checks, archived postings and LLM spend. - Commands:
kairos report digestsends the digest now (POST /api/v1/reports/digest);kairos report chat-idlists the chats that messaged the bot. - Bot:
KAIROS_TELEGRAM_BOT_TOKENandKAIROS_TELEGRAM_CHAT_IDfrom the environment; without them nothing is reported.
Security Notes¶
- The API has no authentication.
src/kairos/api/auth.pyreturns a fixed single-user stub. It binds to127.0.0.1by default and must not be exposed to a network. - Seek and LinkedIn adapters are opt-in (
[search] platformsdefaults 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¶
kairos.corehas zero infrastructure dependencies — only stdlib + Pydantic- One concept per file — each file owns one class/ABC
- Interfaces in core, implementations in infrastructure — ports-and-adapters pattern
- All I/O is async — via asyncio (FastAPI, httpx, asyncpg)
- Error types per module — each module defines its own exception hierarchy
Entry Points¶
Defined in pyproject.toml: