Architecture Overview¶

Kairos follows Clean Architecture with a Python package separating concerns into independent modules. Multiple frontends (CLI, Web) share a single FastAPI backend.

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 + Services"]
    end

    subgraph Infrastructure Layer
        Platform["kairos.platform\nAdzuna / Seek / LinkedIn"]
        LLM["kairos.llm\nLiteLLM + Claude/GPT/Gemini"]
        DB["kairos.db\nSQLAlchemy + PostgreSQL"]
    end

    CLI --> API
    Web --> API

    API --> Core
    Platform --> Core
    LLM --> Core
    DB --> Core

Dependency Flow¶

kairos.api (FastAPI server — the unified backend)
  +-- kairos.core (domain: entities, interfaces, errors)
  +-- kairos.platform (implements JobSearchService)
  |     +-- kairos.core
  +-- kairos.llm (implements JdAnalysisService, ResumeTailorService)
  |     +-- kairos.core
  +-- kairos.db (implements *Repository ABCs)
        +-- kairos.core

kairos.client (shared HTTP client library)
  +-- kairos.core (shared types for deserialization)

kairos.cli (HTTP client via kairos.client)
  +-- kairos.core
  +-- kairos.client

Rule: Infrastructure modules depend on kairos.core for interface definitions. kairos.core depends on nothing external — it's the innermost layer. All frontends go through kairos.api — no exceptions.

Module Responsibilities¶

Module	Responsibility	Key Interface
kairos.core	Domain entities, service ABCs, error types	All ABC definitions
kairos.api	FastAPI HTTP server, routes, auth, WebSocket	— (entry point)
kairos.client	Shared HTTP client library for CLI (and future frontends)	— (library)
kairos.cli	Command-line HTTP client	— (entry point)
kairos.platform	Job data from Adzuna API, Seek/LinkedIn scrapers	`JobSearchService`
kairos.llm	JD analysis + resume tailoring via Claude	`JdAnalysisService`, `ResumeTailorService`
kairos.db	PostgreSQL persistence via SQLAlchemy	`JobRepository`, `ResumeRepository`, `ApplicationRepository`

Async Architecture¶

flowchart LR
    subgraph API Server
        Routes[FastAPI Routes]
        Scrape["Scrape Jobs\nasyncio.create_task"]
        Analyze["Analyze JD\nasyncio.create_task"]
        Tailor["Tailor Resume\nasyncio.create_task"]
    end

    Clients["CLI / Web"] --> |HTTP/WS| Routes
    Routes --> Scrape
    Routes --> Analyze
    Routes --> Tailor
    Scrape --> |WebSocket| Clients
    Analyze --> |WebSocket| Clients
    Tailor --> |WebSocket| Clients

All I/O-heavy operations (scraping, LLM calls) run as background tasks in the FastAPI server. Frontends receive progress updates via WebSocket.