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_userreturns 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 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.