Multi-Frontend Strategy¶
Kairos supports two frontends — the CLI and the Web App (React) — both powered by a single FastAPI backend.
Why a Unified API?¶
Both clients go through one HTTP API:
graph TD
CLI["kairos CLI\n(typer + httpx)"]
Web["Web App\n(React 19 + Vite+)"]
API["kairos.api\n(FastAPI server, /api/v1/)"]
CLI -->|HTTP| API
Web -->|HTTP / WS| API
API --> Core["kairos.core"]
API --> Platform["kairos.platform"]
API --> LLM["kairos.llm"]
API --> DB["kairos.db"]
Benefits¶
| Benefit | Explanation |
|---|---|
| Single source of truth | Business logic lives in one place — the API layer |
| Behavioral consistency | All frontends produce identical results |
| Easier maintenance | Fix a bug once, all clients benefit |
| Testable | API endpoints can be tested independently of any frontend |
Trade-offs¶
| Concern | Mitigation |
|---|---|
| CLI needs a running server | Start it with kairos-server or make backend |
| Network overhead | Localhost HTTP adds < 1ms; LLM/scraping calls are seconds |
No authentication
The API has no authentication (a single-user stub lives in src/kairos/api/auth.py) and binds to 127.0.0.1 by default. Do not expose it to a network.
So that a web page you visit cannot drive it, kairos.api.request_guard refuses:
- a request under a host name other than loopback,
*.localhost, a tailnet name (*.ts.net),backendor one in[api] public_hosts(DNS rebinding); - a request that changes data without the
X-Kairos-Clientheader, which the CLI and the web app send and another site cannot add without a CORS preflight the API never answers; - a WebSocket whose
Originnames any other host.
Tailnet names need no setting: they resolve only inside your own tailnet. Reaching the API under any other name, such as a LAN host, means adding it to [api] public_hosts.
Prior Art¶
This is a well-established pattern:
- Docker CLI → Docker daemon REST API
- GitHub CLI (
gh) → GitHub REST/GraphQL API - Kubernetes
kubectl→ kube-apiserver - Terraform CLI → Terraform Cloud API
How the CLI Talks to the API¶
There is no shared client library. Each command in src/kairos/cli/commands/ opens an httpx.AsyncClient and calls the API directly. The base URL comes from the config file ([api] host and port; a bind address of 0.0.0.0 is mapped to 127.0.0.1).
The Web App calls the same endpoints through the typed fetch wrapper in frontend/src/api/client.ts, and consumes the tailoring stream over WebSocket.
Frontend Summary¶
| Frontend | Technology | Connection | Status |
|---|---|---|---|
| CLI | typer + httpx | HTTP to API | Shipped |
| Web App | React 19 + Vite+ + TypeScript | HTTP + WebSocket to API (/api/v1/) |
Shipped: search, job detail, applications, resume form, settings, tailoring |
Telegram is not a frontend either: kairos.report only sends alerts and a daily digest from the API's background pipeline, and takes no commands (see Project Structure).