Skip to content

Data Model

Entity Relationship

erDiagram
    User ||--o{ Job : owns
    User ||--o{ Resume : owns
    User ||--o{ ApplicationEvent : owns
    Job ||--o| JdAnalysis : analyzed
    Job ||--o{ ApplicationEvent : "status timeline"
    Resume ||--o{ TailoredResume : tailored
    Resume ||--|{ ResumeSection : contains
    Resume ||--o{ SkillEntry : "generates profile"
    TailoredResume ||--|{ TailoredSection : contains
    TailoredResume }o--|| Job : for

    User {
        uuid id PK
        string email
    }

    Job {
        uuid id PK
        uuid owner_id FK
        string platform
        string platform_job_id
        string title
        string company
        string location
        int salary_min
        int salary_max
        string url
        text description_raw
        bool pr_required "nullable"
        bool citizenship_required "nullable"
        bool visa_sponsorship "nullable"
        string status
        datetime applied_at "nullable"
        datetime status_changed_at "nullable"
        datetime scraped_at
    }

    JdAnalysis {
        uuid job_id FK
        jsonb required_skills
        jsonb preferred_skills
        int years_experience
        jsonb keywords
        float match_score
        text match_reasoning
    }

    Resume {
        uuid id PK
        bool is_base
        string format
    }

    ResumeSection {
        uuid id PK
        uuid resume_id FK
        string section_type
        text content
        bool tailorable
    }

    TailoredResume {
        uuid id PK
        uuid base_resume_id FK
        uuid job_id FK
        text diff_summary
        bool approved
    }

    ApplicationEvent {
        uuid id PK
        uuid owner_id
        uuid job_id FK
        string from_status "nullable"
        string to_status
        datetime occurred_at
        datetime recorded_at
        string source
        string interview_kind "nullable"
        uuid reverts "nullable"
        text note "nullable"
    }

    SkillEntry {
        uuid id PK
        string name
        string category
        int proficiency "1-10"
        float years
        jsonb evidence
        string source
    }

Key Entities

User

The owner of every Job, Resume, and Application. Single-user mode today (one fixed User with id 00000000-0000-0000-0000-000000000001, see kairos.api.auth.SINGLE_USER_ID); the schema is multi-tenant-ready so the SaaS migration is a no-op at this layer.

class User(BaseModel):
    id: UUID
    email: str

Job

The central entity. Tracks a job posting from discovery through application. Every query is scoped by owner_id; the unique constraint is (owner_id, platform, platform_job_id) so two users can independently track the same listing without collision.

class Platform(StrEnum):
    SEEK = "seek"
    LINKEDIN = "linkedin"
    INDEED = "indeed"
    ADZUNA = "adzuna"

class JobStatus(StrEnum):
    NEW = "new"                # Just scraped
    ANALYZED = "analyzed"      # JD analyzed by LLM
    MATCHED = "matched"        # User marked as interesting
    SKIPPED = "skipped"        # User passed
    APPLIED = "applied"        # Submitted
    IN_REVIEW = "in_review"    # Company is looking at it
    ASSESSMENT = "assessment"  # Test or take-home
    INTERVIEW = "interview"    # An interview round (kind on the event)
    OFFER = "offer"            # Received offer
    REJECTED = "rejected"      # Got rejection
    WITHDRAWN = "withdrawn"    # User pulled out

JdAnalysis

LLM-generated analysis attached 1:1 to a Job. Key fields:

  • required_skills / preferred_skills — extracted from JD (JSONB)
  • keywords — ATS keywords to include in resume (JSONB)
  • match_score — 0.0 to 1.0, computed against UserProfile
  • match_reasoning — human-readable explanation

Resume & TailoredResume

Base resume imported once and split into sections. Each section marked tailorable: True/False.

Tailored resumes only store modified sections — unchanged sections inherit from base at render time.

class SectionType(str, Enum):
    SUMMARY = "summary"                    # tailorable
    EDUCATION = "education"                # protected
    WORK_EXPERIENCE = "work_experience"    # tailorable (bullets only)
    INTERNSHIP = "internship"              # tailorable (bullets only)
    PROJECTS = "projects"                  # tailorable
    TECHNOLOGIES = "technologies"          # tailorable
    EXTRACURRICULAR = "extracurricular"    # protected
    REFERENCES = "references"              # protected

ApplicationEvent

One status change of a job, appended by kairos.api.services.application_tracker and never edited (decision 0006). jobs.status, status_changed_at and applied_at are a cache of the latest event, written in the same transaction. An undo is a new event whose reverts names the event it undoes. source is manual, agent or email. applied_at is set while the job is in an application status (applied through withdrawn) and cleared when it leaves them.

MailSuggestion

One job-related email and what it suggests (decision 0006), in mail_suggestions. It holds the message's sender, subject, time and a 300-character snippet, never the body: Kioku keeps the body. It also holds the LLM's label, confidence, reason and matched job_id, and a state: - pending: matched to a job; - orphan: job-related, but no job matched; - accepted or ignored.

Mail labelled other is stored as ignored, so it is never classified twice. mail_sync_cursors holds each mailbox's watermark. An event accepted from a suggestion points back to it through application_events.mail_suggestion_id.

EmployerSize

How big one employer is, in employer_sizes (migration 026, decision 0017): one row per owner, region and company name exactly as postings write it. size is large, medium, small, recruiter or unknown, with a one-line reason and the model that judged it. Only employers in the regions in [profile.fit] needs_sponsorship_in are judged, once each, after each harvest. Job responses carry it as employer_size.

Skill Profile

A structured representation of the user's technical abilities, auto-generated from resume analysis and adjustable manually. Used by JD Analysis to compute precise match scores.

class SkillCategory(str, Enum):
    LANGUAGE = "language"        # Rust, Python, TypeScript
    FRAMEWORK = "framework"      # Django, React, FastAPI
    DATABASE = "database"        # PostgreSQL, SQL Server
    TOOL = "tool"                # Docker, Git, CI/CD
    CLOUD = "cloud"              # AWS, GCP, Azure
    CONCEPT = "concept"          # System Design, Async, REST API

class SkillSource(str, Enum):
    RESUME_ANALYSIS = "resume_analysis"  # Auto-extracted from resume by LLM
    MANUAL = "manual"                    # User-provided
    BOTH = "both"                        # Auto-extracted then user-adjusted

Each SkillEntry includes: - proficiency — 1-10 scale (1 = awareness, 5 = working proficiency, 8 = expert, 10 = authority) - years — years of experience with this skill - evidence — specific projects/roles that demonstrate this skill (e.g. "Efision ERP — async/tokio/axum") - source — whether it was auto-extracted, manually added, or both

PostgreSQL Schema

JSONB columns for structured data (skills, keywords, evidence). UUIDs as native uuid type. Timestamps as timestamptz.

Migrations live at alembic/versions/:

  • 001_initial_jobs.py — initial Job table
  • 002_add_cursor_pagination_index.py — (scraped_at, id) index for keyset pagination
  • 003_add_owner_id_to_jobs.py — adds owner_id, backfills the single-user UUID, swaps the unique constraint to (owner_id, platform, platform_job_id)