# qwikchoice/career-os architecture

> Architecture diagram of the GitHub repository qwikchoice/career-os, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/qwikchoice/career-os
- Repository: https://github.com/qwikchoice/career-os

## Overview

Career OS is a local-first job-search system of record. Users enter roles and free-text updates through the CLI or localhost web UI; the service layer classifies and resolves them, records application, referral, interview and evidence activity, and presents actions, pipeline, dossier and dashboard results. SQLite and retained raw sources underpin those stages. The graph preserves the README’s major capabilities; some links rely on README or source-index references rather than inspected implementations, so unsampled connections are omitted.

Main entry points: [`cli.py`](https://github.com/qwikchoice/career-os/blob/main/cli.py) (CLI), [`src/career_os/services/dossier.py`](https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/dossier.py) (Role dossier), [`src/career_os/services/roles.py`](https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/roles.py) (Role intake), [`server.py`](https://github.com/qwikchoice/career-os/blob/main/server.py) (Local web server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_web["Local web server<br/>[server.py]"]
  node_ui["Web interface<br/>[index.html]"]
end

subgraph group_workflow["Search workflow"]
  node_roles["Role intake<br/>[roles.py]"]
  node_classify["Role classifier<br/>[classify.py]"]
  node_heuristics["Offline heuristics<br/>[heuristics.py]"]
  node_applications["Applications<br/>[applications.py]"]
  node_contacts["Contacts<br/>[contacts.py]"]
  node_referrals["Referrals<br/>[referrals.py]"]
  node_interviews["Interviews<br/>[interviews.py]"]
  node_interactions["Interactions<br/>[interactions.py]"]
  node_job_sources["Job sources<br/>[job_sources.py]"]
  node_claims["Inference claims<br/>[claims.py]"]
  node_problem_shape["Problem shape<br/>[problem_shape.py]"]
  node_skills["Career skills<br/>[skills.py]"]
  node_evidence["Career evidence<br/>[evidence.py]"]
end

subgraph group_insight["Planning and insight"]
  node_learning["Learning plans<br/>[learning.py]"]
  node_pipeline["Pipeline view<br/>[pipeline.py]"]
  node_actions["Action center<br/>[actions.py]"]
  node_metrics["Dashboard metrics<br/>[metrics.py]"]
  node_review["Weekly review<br/>[review.py]"]
  node_dossier["Role dossier<br/>[dossier.py]"]
  node_export["Data export<br/>[export.py]"]
end

subgraph group_storage["Local records"]
  node_sources["Raw sources<br/>[sources.py]"]
  node_database[("SQLite database<br/>[db.py]")]
end

node_user(("Job seeker"))

node_user -->|"runs commands"| node_cli
node_user -->|"uses browser"| node_ui
node_ui -->|"sends updates"| node_web
node_web -->|"computes metrics"| node_metrics
node_web -->|"loads dossier"| node_dossier
node_web -->|"opens connection"| node_database
node_web -.-> node_cli
node_cli -->|"adds roles"| node_roles
node_cli -->|"updates status"| node_applications
node_cli -->|"lists actions"| node_actions
node_cli -->|"shows pipeline"| node_pipeline
node_cli -->|"shows metrics"| node_metrics
node_cli -->|"shows dossier"| node_dossier
node_cli -->|"exports data"| node_export
node_cli -->|"manages learning"| node_learning
node_roles -->|"classifies roles"| node_classify
node_classify -->|"uses fallback"| node_heuristics
node_roles -->|"resolves source"| node_job_sources
node_roles -->|"retains posting"| node_sources
node_roles -.->|"creates application"| node_applications
node_problem_shape -->|"records inferences"| node_claims
node_problem_shape -->|"uses skills"| node_skills
node_evidence -->|"links evidence"| node_skills
node_learning -->|"uses analysis"| node_problem_shape
node_learning -->|"reads role"| node_roles
node_learning -->|"checks coverage"| node_skills
node_referrals -->|"resolves contacts"| node_contacts
node_referrals -->|"updates application"| node_applications
node_referrals -->|"logs interaction"| node_interactions
node_pipeline -->|"queries records"| node_database
node_metrics -->|"uses role facts"| node_pipeline
node_actions -->|"uses metrics"| node_metrics
node_actions -->|"checks pipeline"| node_pipeline
node_dossier -->|"reads application"| node_applications
node_dossier -->|"reads claims"| node_claims
node_dossier -->|"reads activity"| node_interactions
node_dossier -->|"reads interviews"| node_interviews
node_dossier -->|"reads analysis"| node_problem_shape
node_dossier -->|"reads role"| node_roles
node_dossier -->|"reads skills"| node_skills
node_export -->|"uses metrics"| node_metrics
node_export -->|"uses pipeline"| node_pipeline
node_export -->|"reads roles"| node_roles
node_cli -->|"initializes store"| node_database
node_sources -->|"stores source records"| node_database

click node_cli "https://github.com/qwikchoice/career-os/blob/main/cli.py"
click node_web "https://github.com/qwikchoice/career-os/blob/main/server.py"
click node_ui "https://github.com/qwikchoice/career-os/blob/main/static/index.html"
click node_roles "https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/roles.py"
click node_classify "https://github.com/qwikchoice/career-os/blob/main/src/career_os/classify.py"
click node_heuristics "https://github.com/qwikchoice/career-os/blob/main/src/career_os/heuristics.py"
click node_applications "https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/applications.py"
click node_contacts "https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/contacts.py"
click node_referrals "https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/referrals.py"
click node_interviews "https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/interviews.py"
click node_interactions "https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/interactions.py"
click node_job_sources "https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/job_sources.py"
click node_sources "https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/sources.py"
click node_claims "https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/claims.py"
click node_problem_shape "https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/problem_shape.py"
click node_skills "https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/skills.py"
click node_evidence "https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/evidence.py"
click node_learning "https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/learning.py"
click node_pipeline "https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/pipeline.py"
click node_actions "https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/actions.py"
click node_metrics "https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/metrics.py"
click node_review "https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/review.py"
click node_dossier "https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/dossier.py"
click node_export "https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/export.py"
click node_database "https://github.com/qwikchoice/career-os/blob/main/src/career_os/db.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_web,node_ui toneBlue
class node_roles,node_classify,node_heuristics,node_applications,node_contacts,node_referrals,node_interviews,node_interactions,node_job_sources,node_claims,node_problem_shape,node_skills,node_evidence toneAmber
class node_learning,node_pipeline,node_actions,node_metrics,node_review,node_dossier,node_export toneMint
class node_sources,node_database toneRose
class node_user toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/qwikchoice/career-os/blob/main/cli.py): `cli.py`
- [Local web server](https://github.com/qwikchoice/career-os/blob/main/server.py): `server.py`
- [Web interface](https://github.com/qwikchoice/career-os/blob/main/static/index.html): `static/index.html`

### Search workflow

- [Role intake](https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/roles.py): `src/career_os/services/roles.py`
- [Role classifier](https://github.com/qwikchoice/career-os/blob/main/src/career_os/classify.py): `src/career_os/classify.py`
- [Offline heuristics](https://github.com/qwikchoice/career-os/blob/main/src/career_os/heuristics.py): `src/career_os/heuristics.py`
- [Applications](https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/applications.py): `src/career_os/services/applications.py`
- [Contacts](https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/contacts.py): `src/career_os/services/contacts.py`
- [Referrals](https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/referrals.py): `src/career_os/services/referrals.py`
- [Interviews](https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/interviews.py): `src/career_os/services/interviews.py`
- [Interactions](https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/interactions.py): `src/career_os/services/interactions.py`
- [Job sources](https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/job_sources.py): `src/career_os/services/job_sources.py`
- [Inference claims](https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/claims.py): `src/career_os/services/claims.py`
- [Problem shape](https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/problem_shape.py): `src/career_os/services/problem_shape.py`
- [Career skills](https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/skills.py): `src/career_os/services/skills.py`
- [Career evidence](https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/evidence.py): `src/career_os/services/evidence.py`

### Planning and insight

- [Learning plans](https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/learning.py): `src/career_os/services/learning.py`
- [Pipeline view](https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/pipeline.py): `src/career_os/services/pipeline.py`
- [Action center](https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/actions.py): `src/career_os/services/actions.py`
- [Dashboard metrics](https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/metrics.py): `src/career_os/services/metrics.py`
- [Weekly review](https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/review.py): `src/career_os/services/review.py`
- [Role dossier](https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/dossier.py): `src/career_os/services/dossier.py`
- [Data export](https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/export.py): `src/career_os/services/export.py`

### Local records

- [Raw sources](https://github.com/qwikchoice/career-os/blob/main/src/career_os/services/sources.py): `src/career_os/services/sources.py`
- [SQLite database](https://github.com/qwikchoice/career-os/blob/main/src/career_os/db.py): `src/career_os/db.py`

### Other components

- **Job seeker**

## Connections

- Job seeker → CLI: runs commands (evidence: `README.md`)
- Job seeker → Web interface: uses browser (evidence: `README.md`)
- Web interface → Local web server: sends updates (evidence: `README.md`)
- Local web server → Dashboard metrics: computes metrics (evidence: `server.py`)
- Local web server → Role dossier: loads dossier (evidence: `server.py`)
- Local web server → SQLite database: opens connection (evidence: `server.py`)
- Local web server → CLI (evidence: `cli.py`)
- CLI → Role intake: adds roles (evidence: `README.md`)
- CLI → Applications: updates status (evidence: `README.md`)
- CLI → Action center: lists actions (evidence: `cli.py`)
- CLI → Pipeline view: shows pipeline (evidence: `cli.py`)
- CLI → Dashboard metrics: shows metrics (evidence: `cli.py`)
- CLI → Role dossier: shows dossier (evidence: `cli.py`)
- CLI → Data export: exports data (evidence: `cli.py`)
- CLI → Learning plans: manages learning (evidence: `cli.py`)
- Role intake → Role classifier: classifies roles (evidence: `src/career_os/services/roles.py`)
- Role classifier → Offline heuristics: uses fallback (evidence: `src/career_os/classify.py`)
- Role intake → Job sources: resolves source (evidence: `src/career_os/services/roles.py`)
- Role intake → Raw sources: retains posting (evidence: `src/career_os/services/roles.py`)
- Role intake → Applications: creates application (evidence: `src/career_os/services/roles.py`)
- Problem shape → Inference claims: records inferences (evidence: `src/career_os/services/problem_shape.py`)
- Problem shape → Career skills: uses skills (evidence: `src/career_os/services/problem_shape.py`)
- Career evidence → Career skills: links evidence (evidence: `src/career_os/services/evidence.py`)
- Learning plans → Problem shape: uses analysis (evidence: `src/career_os/services/learning.py`)
- Learning plans → Role intake: reads role (evidence: `src/career_os/services/learning.py`)
- Learning plans → Career skills: checks coverage (evidence: `src/career_os/services/learning.py`)
- Referrals → Contacts: resolves contacts (evidence: `src/career_os/services/referrals.py`)
- Referrals → Applications: updates application (evidence: `src/career_os/services/referrals.py`)
- Referrals → Interactions: logs interaction (evidence: `README.md`)
- Pipeline view → SQLite database: queries records (evidence: `src/career_os/services/pipeline.py`)
- Dashboard metrics → Pipeline view: uses role facts (evidence: `src/career_os/services/metrics.py`)
- Action center → Dashboard metrics: uses metrics (evidence: `src/career_os/services/actions.py`)
- Action center → Pipeline view: checks pipeline (evidence: `src/career_os/services/actions.py`)
- Role dossier → Applications: reads application (evidence: `src/career_os/services/dossier.py`)
- Role dossier → Inference claims: reads claims (evidence: `src/career_os/services/dossier.py`)
- Role dossier → Interactions: reads activity (evidence: `src/career_os/services/dossier.py`)
- Role dossier → Interviews: reads interviews (evidence: `src/career_os/services/dossier.py`)
- Role dossier → Problem shape: reads analysis (evidence: `src/career_os/services/dossier.py`)
- Role dossier → Role intake: reads role (evidence: `src/career_os/services/dossier.py`)
- Role dossier → Career skills: reads skills (evidence: `src/career_os/services/dossier.py`)
- Data export → Dashboard metrics: uses metrics (evidence: `src/career_os/services/export.py`)
- Data export → Pipeline view: uses pipeline (evidence: `src/career_os/services/export.py`)
- Data export → Role intake: reads roles (evidence: `src/career_os/services/export.py`)
- CLI → SQLite database: initializes store (evidence: `README.md`)
- Raw sources → SQLite database: stores source records (evidence: `src/career_os/services/sources.py`)