Skip to content

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), backend or one in [api] public_hosts (DNS rebinding);
  • a request that changes data without the X-Kairos-Client header, which the CLI and the web app send and another site cannot add without a CORS preflight the API never answers;
  • a WebSocket whose Origin names 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).