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.
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 UserProfilematch_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 table002_add_cursor_pagination_index.py—(scraped_at, id)index for keyset pagination003_add_owner_id_to_jobs.py— addsowner_id, backfills the single-user UUID, swaps the unique constraint to(owner_id, platform, platform_job_id)