# arossia94/career-ops architecture

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

- Interactive diagram: https://gitdiagram.com/arossia94/career-ops
- Repository: https://github.com/arossia94/career-ops

## Overview

1. **Overall shape**
   Career-Ops is a **local-first job search operating system**, not a hosted app. The machine running the repo is the control plane: it reads your CV/profile, talks to an AI model or CLI, automates browser work against job portals, and writes results back to local files.

2. **Primary user interface: slash-command modes**
   The core behavior is encoded in `modes/*.md`. These are the repo’s “commands” for tasks like evaluation, PDF generation, scanning, batch processing, tracker management, deep research, interview prep, and follow-up. They are designed to be reused across Claude Code, Gemini CLI, and other supported coding CLIs via the shared agent instructions in `AGENTS.md`, `CLAUDE.md`, and the provider-specific skill folders.

3. **Main orchestration flow**
   The standard pipeline is: **input a job URL or description → classify the role/archetype → evaluate fit against `cv.md` and profile data → generate a report/PDF → update the tracker**. This is the central data flow the architecture is built around, and most tools in the repo either feed this pipeline or consume its outputs.

4. **Evaluation and reasoning layer**
   The evaluation subsystem produces structured job analyses: role summary, CV match, level strategy, comp research, personalization, and interview prep. It appears to rely on prompt templates plus local source files such as the CV, profile config, proof points, and shared mode text. The important boundary here is that the AI is recommended/assistive; the repo does not auto-submit applications.

5. **Portal scanning and browser automation**
   The scanning subsystem uses **Playwright** and portal-specific configuration to discover roles from company pages and supported job boards such as Greenhouse, Ashby, Lever, Wellfound, Workable, and RemoteFront. Portal definitions live in `templates/portals.example.yml` and likely become a user-local `portals.yml`. This is the repo’s web-automation boundary: it reaches out to external sites, but keeps the results local.

6. **Artifact generation**
   Outputs are generated into separate local folders: `reports/` for markdown evaluations, `output/` for PDFs, and `data/` for tracking state. PDF generation is template-driven via `templates/cv-template.html` and `templates/cv-template.tex`, with embedded fonts in `fonts/`. The architecture treats report generation and PDF rendering as distinct steps, so the same evaluation can feed multiple output formats.

7. **Single source of truth for tracking**
   The tracking layer stores application/candidate pipeline state locally using markdown/YAML/TSV-style data and canonical status definitions in `templates/states.yml`. Utility scripts such as `merge-tracker.mjs`, `dedup-tracker.mjs`, `normalize-statuses.mjs`, and `verify-pipeline.mjs` indicate that data integrity is a first-class concern: deduplication, normalization, merge safety, and health checks are part of the system design.

8. **Batch and parallel processing**
   `batch/` is a separate execution path for high-throughput evaluation. It uses a self-contained worker prompt and a shell runner, implying fan-out to multiple AI workers/sub-agents for parallel processing of many listings. This is a throughput-oriented subsystem distinct from the interactive single-offer flow.

9. **Terminal dashboard subsystem**
   The `dashboard/` directory is a standalone Go application built with **Bubble Tea** and **Lipgloss**. It reads the same local job/pipeline data and presents it as a TUI for browsing, filtering, sorting, previewing, and changing status. Architecturally, it is a read-heavy UI over the local tracker, not a separate backend.

10. **Customization and user-owned inputs**
   The repo is intentionally user-customized through local files like `cv.md`, `config/profile.yml`, `portals.yml`, and optional reference material in `examples/`, `jds/`, `writing-samples/`, and `interview-prep/`. That means the system’s behavior is heavily shaped by user-owned content rather than hardcoded application data.

11. **Localization and role-specific modes**
   There are localized mode sets under `modes/de/` and several specialized command families such as apply, contact outreach, deep research, training, project review, and resume/PDF generation. This suggests the architecture is modular by job-search task, with language variants and role variants layered on the same shared workflow.

12. **Automation, validation, and maintenance scripts**
   The root-level `.mjs` scripts and helpers like `doctor.mjs`, `check-liveness.mjs`, `cv-sync-check.mjs`, `scan.mjs`, and `generate-pdf.mjs` form the maintenance and automation layer. These keep the local system healthy, ensure the CV/tracker stay aligned, and support repeatable execution outside the interactive CLI experience.

13. **External dependencies and boundaries**
   The main external boundaries are: AI providers/CLIs, browser automation against job portals, and job-board/company sites. The repo also depends on local tooling ecosystems: Node.js for orchestration/scripts, Go for the dashboard, Playwright for web interaction and PDF-related rendering, and GitHub Actions for CI/release checks.

14. **CI and repository governance**
   The GitHub workflows, issue templates, release automation, dependency review, SBOM, and security tooling suggest the repo is maintained like a productized open-source tool. That infrastructure supports code quality and releases, but the runtime architecture remains local and user-operated rather than server-hosted.

Main entry points: [`gemini-eval.mjs`](https://github.com/arossia94/career-ops/blob/main/gemini-eval.mjs) (Eval engine), [`templates/states.yml`](https://github.com/arossia94/career-ops/blob/main/templates/states.yml) (Tracker core), [`modes/_shared.md`](https://github.com/arossia94/career-ops/blob/main/modes/_shared.md) (Shared modes), [`modes/apply.md`](https://github.com/arossia94/career-ops/blob/main/modes/apply.md) (Apply flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_cli["CLI Modes"]
  node_agents_skill["Agent skill<br/>cli skill<br/>[SKILL.md]"]
  node_claude_skill["Claude skill<br/>cli skill<br/>[SKILL.md]"]
  node_qwen_skill["Qwen skill<br/>cli skill<br/>[SKILL.md]"]
  node_shared_modes["Shared modes<br/>mode text<br/>[_shared.md]"]
  node_apply_mode["Apply flow<br/>mode<br/>[apply.md]"]
  node_pipeline_mode["Pipeline flow<br/>mode<br/>[pipeline.md]"]
  node_scan_mode["Scan flow<br/>mode<br/>[scan.md]"]
  node_batch_mode["Batch flow<br/>mode<br/>[batch.md]"]
end

subgraph group_group_core["Core Pipeline"]
  node_eval_engine["Eval engine<br/>reasoning<br/>[gemini-eval.mjs]"]
  node_role_patterns["Role patterns<br/>classification<br/>[patterns.md]"]
  node_tracker_core[("Tracker core<br/>state store<br/>[states.yml]")]
  node_tracker_tools["Tracker tools<br/>data ops<br/>[merge-tracker.mjs]"]
  node_scan_runner["Scanner<br/>browser automation<br/>[scan.mjs]"]
  node_portal_templates["Portal config<br/>portal defs"]
  node_batch_runner["Batch runner<br/>worker pipeline<br/>[batch-runner.sh]"]
end

subgraph group_group_ui["User Interfaces"]
  node_dashboard_app["Dashboard<br/>tui app<br/>[main.go]"]
  node_dashboard_data["Dashboard data<br/>read model<br/>[career.go]"]
end

subgraph group_group_artifacts["Artifacts & Templates"]
  node_cv_source["CV source<br/>profile input<br/>[cv-example.md]"]
  node_profile_cfg["Profile cfg<br/>user config"]
  node_report_template["Report template<br/>[sample-report.md]"]
  node_pdf_templates["PDF templates<br/>render template<br/>[cv-template.html]"]
  node_pdf_writer["PDF writer<br/>render pipeline<br/>[generate-pdf.mjs]"]
end

subgraph group_group_ops["Automation & Maintenance"]
  node_doctor["Health checks<br/>maintenance<br/>[doctor.mjs]"]
  node_sync_checks["Sync checks<br/>validation<br/>[cv-sync-check.mjs]"]
end

subgraph group_group_meta["Repo Governance"]
  node_docs["Docs<br/>guide set<br/>[ARCHITECTURE.md]"]
  node_github_actions["GitHub Actions<br/>ci/release<br/>[test.yml]"]
end

node_agents_skill -->|"shares"| node_shared_modes
node_claude_skill -->|"shares"| node_shared_modes
node_qwen_skill -->|"shares"| node_shared_modes
node_apply_mode -->|"uses"| node_eval_engine
node_apply_mode -->|"reads"| node_cv_source
node_apply_mode -->|"updates"| node_tracker_core
node_pipeline_mode -->|"classifies"| node_role_patterns
node_pipeline_mode -->|"drives"| node_eval_engine
node_pipeline_mode -->|"persists"| node_tracker_core
node_scan_mode -->|"orchestrates"| node_scan_runner
node_scan_runner -->|"configures"| node_portal_templates
node_scan_runner -->|"feeds"| node_tracker_core
node_batch_mode -->|"executes"| node_batch_runner
node_batch_runner -->|"fans out"| node_eval_engine
node_eval_engine -->|"reads"| node_cv_source
node_eval_engine -->|"reads"| node_profile_cfg
node_eval_engine -->|"formats"| node_report_template
node_pdf_writer -->|"renders"| node_pdf_templates
node_pdf_writer -->|"consumes"| node_report_template
node_tracker_tools -->|"maintains"| node_tracker_core
node_dashboard_app -->|"reads"| node_dashboard_data
node_dashboard_data -->|"queries"| node_tracker_core
node_doctor -->|"invokes"| node_sync_checks
node_sync_checks -->|"validates"| node_tracker_core
node_docs -->|"documents"| node_shared_modes
node_github_actions -->|"runs"| node_doctor
node_github_actions -->|"runs"| node_sync_checks
node_github_actions -->|"guards"| node_tracker_tools

click node_agents_skill "https://github.com/arossia94/career-ops/blob/main/.agents/skills/career-ops/SKILL.md"
click node_claude_skill "https://github.com/arossia94/career-ops/blob/main/.claude/skills/career-ops/SKILL.md"
click node_qwen_skill "https://github.com/arossia94/career-ops/blob/main/.qwen/skills/career-ops/SKILL.md"
click node_shared_modes "https://github.com/arossia94/career-ops/blob/main/modes/_shared.md"
click node_apply_mode "https://github.com/arossia94/career-ops/blob/main/modes/apply.md"
click node_pipeline_mode "https://github.com/arossia94/career-ops/blob/main/modes/pipeline.md"
click node_scan_mode "https://github.com/arossia94/career-ops/blob/main/modes/scan.md"
click node_batch_mode "https://github.com/arossia94/career-ops/blob/main/modes/batch.md"
click node_eval_engine "https://github.com/arossia94/career-ops/blob/main/gemini-eval.mjs"
click node_role_patterns "https://github.com/arossia94/career-ops/blob/main/modes/patterns.md"
click node_tracker_core "https://github.com/arossia94/career-ops/blob/main/templates/states.yml"
click node_tracker_tools "https://github.com/arossia94/career-ops/blob/main/merge-tracker.mjs"
click node_dashboard_app "https://github.com/arossia94/career-ops/blob/main/dashboard/main.go"
click node_dashboard_data "https://github.com/arossia94/career-ops/blob/main/dashboard/internal/data/career.go"
click node_scan_runner "https://github.com/arossia94/career-ops/blob/main/scan.mjs"
click node_portal_templates "https://github.com/arossia94/career-ops/blob/main/templates/portals.example.yml"
click node_cv_source "https://github.com/arossia94/career-ops/blob/main/examples/cv-example.md"
click node_profile_cfg "https://github.com/arossia94/career-ops/blob/main/config/profile.example.yml"
click node_report_template "https://github.com/arossia94/career-ops/blob/main/examples/sample-report.md"
click node_pdf_templates "https://github.com/arossia94/career-ops/blob/main/templates/cv-template.html"
click node_pdf_writer "https://github.com/arossia94/career-ops/blob/main/generate-pdf.mjs"
click node_batch_runner "https://github.com/arossia94/career-ops/blob/main/batch/batch-runner.sh"
click node_doctor "https://github.com/arossia94/career-ops/blob/main/doctor.mjs"
click node_sync_checks "https://github.com/arossia94/career-ops/blob/main/cv-sync-check.mjs"
click node_docs "https://github.com/arossia94/career-ops/blob/main/docs/ARCHITECTURE.md"
click node_github_actions "https://github.com/arossia94/career-ops/blob/main/.github/workflows/test.yml"

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_agents_skill,node_claude_skill,node_qwen_skill,node_shared_modes,node_apply_mode,node_pipeline_mode,node_scan_mode,node_batch_mode toneBlue
class node_eval_engine,node_role_patterns,node_tracker_core,node_tracker_tools,node_scan_runner,node_portal_templates,node_batch_runner toneAmber
class node_dashboard_app,node_dashboard_data toneMint
class node_cv_source,node_profile_cfg,node_report_template,node_pdf_templates,node_pdf_writer toneRose
class node_doctor,node_sync_checks toneIndigo
class node_docs,node_github_actions toneTeal
```

## Components

### CLI Modes

Shared command-mode layer used by supported AI CLIs and local prompts

- [Agent skill](https://github.com/arossia94/career-ops/blob/main/.agents/skills/career-ops/SKILL.md): cli skill · Shared instruction package for external AI CLIs · `.agents/skills/career-ops/SKILL.md`
- [Claude skill](https://github.com/arossia94/career-ops/blob/main/.claude/skills/career-ops/SKILL.md): cli skill · Provider-specific skill entrypoint · `.claude/skills/career-ops/SKILL.md`
- [Qwen skill](https://github.com/arossia94/career-ops/blob/main/.qwen/skills/career-ops/SKILL.md): cli skill · Provider-specific skill entrypoint · `.qwen/skills/career-ops/SKILL.md`
- [Shared modes](https://github.com/arossia94/career-ops/blob/main/modes/_shared.md): mode text · Common instructions reused across task modes · `modes/_shared.md`
- [Apply flow](https://github.com/arossia94/career-ops/blob/main/modes/apply.md): mode · Job fit evaluation and application workflow · `modes/apply.md`
- [Pipeline flow](https://github.com/arossia94/career-ops/blob/main/modes/pipeline.md): mode · Main job intake to tracker update workflow · `modes/pipeline.md`
- [Scan flow](https://github.com/arossia94/career-ops/blob/main/modes/scan.md): mode · Portal discovery and job scanning workflow · `modes/scan.md`
- [Batch flow](https://github.com/arossia94/career-ops/blob/main/modes/batch.md): mode · High-throughput multi-listing processing workflow · `modes/batch.md`

### Core Pipeline

Main local-first job search workflow from job intake to evaluation and tracking

- [Eval engine](https://github.com/arossia94/career-ops/blob/main/gemini-eval.mjs): reasoning · Structured job analysis and fit assessment · `gemini-eval.mjs`
- [Role patterns](https://github.com/arossia94/career-ops/blob/main/modes/patterns.md): classification · Archetype and pattern extraction for jobs · `modes/patterns.md`
- [Tracker core](https://github.com/arossia94/career-ops/blob/main/templates/states.yml): state store · Canonical local pipeline and application state · `templates/states.yml`
- [Tracker tools](https://github.com/arossia94/career-ops/blob/main/merge-tracker.mjs): data ops · Merge, dedupe, normalize, and verify tracker data · `merge-tracker.mjs`
- [Scanner](https://github.com/arossia94/career-ops/blob/main/scan.mjs): browser automation · Playwright-driven discovery of roles on portals · `scan.mjs`
- [Portal config](https://github.com/arossia94/career-ops/blob/main/templates/portals.example.yml): portal defs · Supported portal and company-page configurations · `templates/portals.example.yml`
- [Batch runner](https://github.com/arossia94/career-ops/blob/main/batch/batch-runner.sh): worker pipeline · Shell-based fan-out execution for batch processing · `batch/batch-runner.sh`

### User Interfaces

Interactive interfaces over local job and pipeline data

- [Dashboard](https://github.com/arossia94/career-ops/blob/main/dashboard/main.go): tui app · Go TUI for browsing and updating pipeline state · `dashboard/main.go`
- [Dashboard data](https://github.com/arossia94/career-ops/blob/main/dashboard/internal/data/career.go): read model · Data access layer for tracker-backed views · `dashboard/internal/data/career.go`

### Artifacts & Templates

Local source files and templates used to generate reports and PDFs

- [CV source](https://github.com/arossia94/career-ops/blob/main/examples/cv-example.md): profile input · Primary resume and profile content used for evaluation · `examples/cv-example.md`
- [Profile cfg](https://github.com/arossia94/career-ops/blob/main/config/profile.example.yml): user config · User-owned profile configuration and defaults · `config/profile.example.yml`
- [Report template](https://github.com/arossia94/career-ops/blob/main/examples/sample-report.md): report template · Markdown/report shaping for evaluations · `examples/sample-report.md`
- [PDF templates](https://github.com/arossia94/career-ops/blob/main/templates/cv-template.html): render template · HTML and LaTeX templates for PDF generation · `templates/cv-template.html`
- [PDF writer](https://github.com/arossia94/career-ops/blob/main/generate-pdf.mjs): render pipeline · Generates local PDF artifacts from report inputs · `generate-pdf.mjs`

### Automation & Maintenance

Validation, synchronization, and repo health scripts

- [Health checks](https://github.com/arossia94/career-ops/blob/main/doctor.mjs): maintenance · Repository health and liveness validation scripts · `doctor.mjs`
- [Sync checks](https://github.com/arossia94/career-ops/blob/main/cv-sync-check.mjs): validation · CV and pipeline alignment verification scripts · `cv-sync-check.mjs`

### Repo Governance

Docs, guides, and release governance around the tool

- [Docs](https://github.com/arossia94/career-ops/blob/main/docs/ARCHITECTURE.md): guide set · Architecture, setup, customization, and script documentation · `docs/ARCHITECTURE.md`
- [GitHub Actions](https://github.com/arossia94/career-ops/blob/main/.github/workflows/test.yml): ci/release · CI, dependency review, SBOM, and release workflows · `.github/workflows/test.yml`

## Connections

- Agent skill → Shared modes: shares · Shared instructions define common command behavior
- Claude skill → Shared modes: shares · Claude-specific skill reuses shared mode logic
- Qwen skill → Shared modes: shares · Qwen-specific skill reuses shared mode logic
- Apply flow → Eval engine: uses · Application flow depends on structured job analysis
- Apply flow → CV source: reads · Evaluates fit against CV and profile content
- Apply flow → Tracker core: updates · Writes outcomes back to local tracking state
- Pipeline flow → Role patterns: classifies · Pipeline flow classifies job archetype before analysis
- Pipeline flow → Eval engine: drives · Main orchestration hands jobs to the evaluation engine
- Pipeline flow → Tracker core: persists · Canonical workflow ends by updating tracker state
- Scan flow → Scanner: orchestrates · Scan mode triggers browser-based discovery
- Scanner → Portal config: configures · Portal definitions control supported site scraping
- Scanner → Tracker core: feeds · Discovered listings are stored in local tracking data
- Batch flow → Batch runner: executes · Batch mode delegates fan-out processing to the runner
- Batch runner → Eval engine: fans out · Parallel workers invoke the evaluation pipeline
- Eval engine → CV source: reads · Structured analysis uses resume and profile inputs
- Eval engine → Profile cfg: reads · Analysis incorporates user-specific configuration
- Eval engine → Report template: formats · Evaluation output is shaped into report text
- PDF writer → PDF templates: renders · PDF generation uses HTML and LaTeX templates
- PDF writer → Report template: consumes · Reports feed PDF generation
- Tracker tools → Tracker core: maintains · Merge, dedupe, and normalize operations protect tracker integrity
- Dashboard → Dashboard data: reads · TUI renders views through the data layer
- Dashboard data → Tracker core: queries · Dashboard is a read-heavy interface over local state
- Health checks → Sync checks: invokes · Health scripts include pipeline and consistency checks
- Sync checks → Tracker core: validates · Validation ensures tracker and CV data remain aligned
- Docs → Shared modes: documents · Repository docs explain the command and mode system
- GitHub Actions → Health checks: runs · CI exercises health and validation scripts
- GitHub Actions → Sync checks: runs · CI verifies data integrity and pipeline consistency
- GitHub Actions → Tracker tools: guards · Automation helps catch tracker regressions