# moreganooooo/career-ops architecture

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

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

## Overview

Career-Ops is a local, file-driven job-search system, not a hosted web service. The architecture centers on AI CLI agents that read and rewrite repository files, with Node.js scripts and a Go TUI providing the operational tooling around them.

1. **Primary interaction boundary: AI CLI + repo instructions**
   The system is designed to be driven by Claude Code, Gemini CLI, OpenCode, Codex, Qwen, etc. The behavioral contract lives in `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and the `modes/` files. Those mode documents define the “commands” and prompt context the agent uses for scanning, evaluating, PDF generation, tracking, batch work, and writing tasks.

2. **Main workflow: paste a URL or JD, then fan out**
   The central pipeline starts from a job URL or description and moves through classification, fit evaluation, report generation, PDF creation, and tracker updates. The README’s flow is accurate: input is normalized, an archetype is inferred, an A-F evaluation is produced, and outputs are written into reports / PDFs / tracker files.

3. **Node.js orchestration layer**
   Most automation lives in the top-level `.mjs` scripts: `scan.mjs`, `analyze-patterns.mjs`, `generate-pdf.mjs`, `prepare-batch.mjs`, `populate-batch.mjs`, `verify-pipeline.mjs`, `normalize-statuses.mjs`, `merge-tracker.mjs`, and others. These scripts are the glue that transforms scraped listings and user inputs into consistent artifacts and keeps the pipeline clean.

4. **Provider adapter layer for job sources**
   `providers/` is the ingestion boundary. Each file there is a source-specific adapter for a job board or ATS such as Greenhouse, Lever, Ashby, Workday, SmartRecruiters, Recruitee, Workable, RemoteOK, Remotive, Wellfound, and web search. Shared helpers like `_http.mjs`, `_rss.mjs`, `_recognition.mjs`, and `_guessing.mjs` suggest a common adapter pattern with source detection and fetch/parse normalization.

5. **Discovery vs verification**
   Scanning is intentionally split into two phases. First, the scanner pulls jobs from ATS feeds and search sources. Optionally, `--verify` triggers Playwright-based liveness checks so expired postings are filtered before they enter the pipeline. This means the architecture distinguishes cheap broad discovery from narrower browser verification.

6. **Evaluation and personalization layer**
   The `modes/` set and the markdown assets in `data/`, `article-digest.md`, `interview-prep/`, and `writing-samples/` provide the semantic inputs for evaluation. The system compares the posting to the user’s CV, profile, proof points, and story bank, then produces tailored content such as role fit, gaps, STAR stories, and negotiation guidance. This is a reasoning-heavy layer rather than a rules engine.

7. **PDF generation subsystem**
   PDF output is generated from HTML/LaTeX templates in `templates/` and rendered using browser tooling from Node. The repository includes `cv-template.html`, `cv-template.tex`, and font assets, indicating a templated, ATS-oriented document pipeline rather than a generic document editor. Generated PDFs are stored under `output/`.

8. **Batch processing as a parallel worker pipeline**
   The `batch/` directory contains the self-contained batch prompt, shell runner, and TSV state files. Batch mode is a parallel fan-out of the single-job pipeline, using worker agents to process multiple offers concurrently while preserving progress and results in tabular state files. This is a separate operational mode from the interactive single-job flow.

9. **Single source of truth for tracking data**
   Persistent state is mostly file-based: markdown, TSV, CSV, and YAML under `data/`, `batch/`, `templates/`, and generated `reports/`. The repo emphasizes integrity with deduplication, status normalization, merge utilities, and contract docs like `DATA_CONTRACT.md`. That makes the data boundary explicit and reviewable in git.

10. **Go TUI dashboard as a read-mostly viewer**
   `dashboard/` is a separate Go module that builds a terminal UI using Bubble Tea and related UI libraries. It reads the repository’s pipeline data and provides browsing, filtering, sorting, previews, and inline status changes. Architecturally, it is the human operations console for the same file-based system, not a backend service.

11. **Validation and health tooling**
   Utilities like `check-liveness.mjs`, `liveness-core.mjs`, `liveness-browser.mjs`, `cv-sync-check.mjs`, `doctor.mjs`, `test-all.mjs`, and `confirm-remote-queue.txt` show that the project treats consistency as a first-class concern. These scripts verify that the pipeline, data, and generated artifacts stay synchronized over time.

12. **Automation and release boundary**
   GitHub Actions handle test execution, dependency review, CodeQL, SBOM generation, stale issue management, and releases. There is also release automation via release-please config and manifest files. The repo is thus packaged as a distributable local tool with CI guarding correctness, security, and publication.

13. **Configuration and customization layer**
   `templates/portals.example.yml`, `templates/states.yml`, `modes/_shared.md`, and the profile/config docs define the main customization boundaries. Users adapt the system by editing repository files rather than configuring a server. That “config-as-content” approach is central to the architecture.

14. **Key external dependencies**
   The only materially important external services are the AI model providers and the job portals themselves. Playwright is used to interact with browser-rendered pages and to generate PDFs; GitHub is used for CI/release distribution; the rest of the system is intentionally local and portable.

Overall, the architecture is a local agentic workflow engine: source adapters ingest job data, prompt/mode files steer evaluation, templated generators produce reports and PDFs, file-based state tracks everything, and a Go TUI provides the operator’s view over the same underlying pipeline.

Main entry points: [`analyze-patterns.mjs`](https://github.com/moreganooooo/career-ops/blob/main/analyze-patterns.mjs) (Core scripts), [`providers/greenhouse.mjs`](https://github.com/moreganooooo/career-ops/blob/main/providers/greenhouse.mjs) (Providers), [`doctor.mjs`](https://github.com/moreganooooo/career-ops/blob/main/doctor.mjs) (Checks), [`DATA_CONTRACT.md`](https://github.com/moreganooooo/career-ops/blob/main/DATA_CONTRACT.md) (State files)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_agents["AI CLI boundary"]
  node_agents_docs["Agent docs<br/>instructions<br/>[AGENTS.md]"]
  node_modes["Modes<br/>prompt packs<br/>[scan.md]"]
end

subgraph group_group_pipeline["Node pipeline"]
  node_scan_script(("Scan<br/>orchestrator<br/>[scan.mjs]"))
  node_pipeline_tools["Core scripts<br/>workflow scripts"]
end

subgraph group_group_providers["Source adapters"]
  node_providers_pkg[("Providers<br/>adapters<br/>[greenhouse.mjs]")]
  node_provider_helpers["Shared parse<br/>adapter helpers<br/>[_http.mjs]"]
end

subgraph group_group_content["Content inputs"]
  node_content_inputs["Profile assets<br/>content set<br/>[bullet-bank.md]"]
  node_templates["Templates<br/>[cv-template.html]"]
  node_evaluation_modes["Eval modes<br/>reasoning prompts<br/>[pipeline.md]"]
end

subgraph group_group_output["Artifacts"]
  node_reports["Reports<br/>job artifacts<br/>[.gitkeep]"]
  node_pdfs["PDF output<br/>document rendering<br/>[.gitkeep]"]
end

subgraph group_group_batch["Batch mode"]
  node_batch_mode["Batch mode<br/>parallel workflow<br/>[batch-prompt.md]"]
  node_batch_scripts(("Batch runners<br/>worker scripts<br/>[prepare-batch.mjs]"))
end

subgraph group_group_dashboard["TUI dashboard"]
  node_dashboard_app["Dashboard<br/>Go TUI<br/>[main.go]"]
  node_dashboard_data(("Dashboard data<br/>view model<br/>[career.go]"))
end

subgraph group_group_state["Persistent state"]
  node_repo_state[("State files<br/>file-based state<br/>[DATA_CONTRACT.md]")]
  node_config_layer["Config layer<br/>customization"]
end

subgraph group_group_validation["Validation and CI"]
  node_validation_tools(("Checks<br/>health tooling<br/>[doctor.mjs]"))
  node_ci["GitHub Actions<br/>ci/release<br/>[test.yml]"]
end

node_agents_docs -->|"directs"| node_scan_script
node_modes -->|"steers"| node_pipeline_tools
node_scan_script -->|"pulls jobs"| node_providers_pkg
node_providers_pkg -->|"uses"| node_provider_helpers
node_providers_pkg -->|"writes raw data"| node_repo_state
node_scan_script -->|"verifies"| node_validation_tools
node_pipeline_tools -->|"uses"| node_evaluation_modes
node_evaluation_modes -->|"reads"| node_content_inputs
node_pipeline_tools -->|"renders with"| node_templates
node_pipeline_tools -->|"produces"| node_reports
node_pipeline_tools -->|"generates"| node_pdfs
node_batch_mode -->|"runs with"| node_batch_scripts
node_batch_scripts -->|"fans out"| node_providers_pkg
node_batch_scripts -->|"reuses"| node_pipeline_tools
node_dashboard_app -->|"uses"| node_dashboard_data
node_dashboard_data -->|"reads"| node_repo_state
node_validation_tools -->|"checks"| node_repo_state
node_validation_tools -->|"guards"| node_pipeline_tools
node_ci -->|"runs"| node_validation_tools
node_config_layer -->|"customizes"| node_modes
node_config_layer -->|"defines contract"| node_repo_state

click node_agents_docs "https://github.com/moreganooooo/career-ops/blob/main/AGENTS.md"
click node_modes "https://github.com/moreganooooo/career-ops/blob/main/modes/scan.md"
click node_scan_script "https://github.com/moreganooooo/career-ops/blob/main/scan.mjs"
click node_pipeline_tools "https://github.com/moreganooooo/career-ops/blob/main/analyze-patterns.mjs"
click node_providers_pkg "https://github.com/moreganooooo/career-ops/blob/main/providers/greenhouse.mjs"
click node_provider_helpers "https://github.com/moreganooooo/career-ops/blob/main/providers/_http.mjs"
click node_content_inputs "https://github.com/moreganooooo/career-ops/blob/main/data/bullet-bank.md"
click node_templates "https://github.com/moreganooooo/career-ops/blob/main/templates/cv-template.html"
click node_evaluation_modes "https://github.com/moreganooooo/career-ops/blob/main/modes/pipeline.md"
click node_reports "https://github.com/moreganooooo/career-ops/blob/main/reports/.gitkeep"
click node_pdfs "https://github.com/moreganooooo/career-ops/blob/main/output/.gitkeep"
click node_batch_mode "https://github.com/moreganooooo/career-ops/blob/main/batch/batch-prompt.md"
click node_batch_scripts "https://github.com/moreganooooo/career-ops/blob/main/prepare-batch.mjs"
click node_dashboard_app "https://github.com/moreganooooo/career-ops/blob/main/dashboard/main.go"
click node_dashboard_data "https://github.com/moreganooooo/career-ops/blob/main/dashboard/internal/data/career.go"
click node_repo_state "https://github.com/moreganooooo/career-ops/blob/main/DATA_CONTRACT.md"
click node_validation_tools "https://github.com/moreganooooo/career-ops/blob/main/doctor.mjs"
click node_ci "https://github.com/moreganooooo/career-ops/blob/main/.github/workflows/test.yml"
click node_config_layer "https://github.com/moreganooooo/career-ops/blob/main/templates/portals.example.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_docs,node_modes,node_dashboard_app,node_dashboard_data toneBlue
class node_scan_script,node_pipeline_tools,node_repo_state,node_config_layer toneAmber
class node_providers_pkg,node_provider_helpers,node_validation_tools,node_ci toneMint
class node_content_inputs,node_templates,node_evaluation_modes toneRose
class node_reports,node_pdfs toneIndigo
class node_batch_mode,node_batch_scripts toneTeal
```

## Components

### AI CLI boundary

Agent instructions and mode files that define how the repository is operated.

- [Agent docs](https://github.com/moreganooooo/career-ops/blob/main/AGENTS.md): instructions · AGENTS.md, CLAUDE.md, GEMINI.md, and similar files that define operational behavior for CLI agents. · `AGENTS.md`
- [Modes](https://github.com/moreganooooo/career-ops/blob/main/modes/scan.md): prompt packs · Mode markdown files that steer scan, pipeline, PDF, tracker, interview, and writing workflows. · `modes/scan.md`

### Node pipeline

Top-level scripts that scan, evaluate, generate, and maintain repository state.

- [Scan](https://github.com/moreganooooo/career-ops/blob/main/scan.mjs): orchestrator · Primary single-job entry point that normalizes inputs and drives discovery. · `scan.mjs`
- [Core scripts](https://github.com/moreganooooo/career-ops/blob/main/analyze-patterns.mjs): workflow scripts · Main Node.js automation for analysis, PDF generation, batch prep, tracker merge, and status normalization. · `analyze-patterns.mjs`

### Source adapters

Job source connectors and shared parsing helpers.

- [Providers](https://github.com/moreganooooo/career-ops/blob/main/providers/greenhouse.mjs): adapters · Source-specific job ingestion adapters plus shared fetch, recognition, and guessing helpers. · `providers/greenhouse.mjs`
- [Shared parse](https://github.com/moreganooooo/career-ops/blob/main/providers/_http.mjs): adapter helpers · Common HTTP, RSS, recognition, and guessing helpers used across source adapters. · `providers/_http.mjs`

### Content inputs

User profile, proof points, and prompt assets used for evaluation and writing.

- [Profile assets](https://github.com/moreganooooo/career-ops/blob/main/data/bullet-bank.md): content set · Markdown and CSV inputs such as interview prep, article digest, bullet bank, and evidence files used for evaluation and writing. · `data/bullet-bank.md`
- [Templates](https://github.com/moreganooooo/career-ops/blob/main/templates/cv-template.html): render templates · HTML, LaTeX, and YAML templates used for CV, cover letter, and state configuration. · `templates/cv-template.html`
- [Eval modes](https://github.com/moreganooooo/career-ops/blob/main/modes/pipeline.md): reasoning prompts · Modes for fit evaluation, patterns, interview prep, offers, follow-up, and writing style. · `modes/pipeline.md`

### Artifacts

Generated reports, PDFs, and other produced outputs.

- [Reports](https://github.com/moreganooooo/career-ops/blob/main/reports/.gitkeep): job artifacts · Generated reports and written outputs for job analysis and personalization. · `reports/.gitkeep`
- [PDF output](https://github.com/moreganooooo/career-ops/blob/main/output/.gitkeep): document rendering · Rendered PDF artifacts produced from HTML/LaTeX templates and browser tooling. · `output/.gitkeep`

### Batch mode

Parallel processing workflow for multiple jobs.

- [Batch mode](https://github.com/moreganooooo/career-ops/blob/main/batch/batch-prompt.md): parallel workflow · Batch prompt, runner scripts, and TSV state for concurrent multi-job processing. · `batch/batch-prompt.md`
- [Batch runners](https://github.com/moreganooooo/career-ops/blob/main/prepare-batch.mjs): worker scripts · Shell and Node helpers that prepare, populate, filter, and run batch jobs. · `prepare-batch.mjs`

### TUI dashboard

Go-based terminal interface for browsing and managing pipeline data.

- [Dashboard](https://github.com/moreganooooo/career-ops/blob/main/dashboard/main.go): Go TUI · Bubble Tea-based terminal application for browsing pipeline data and changing statuses. · `dashboard/main.go`
- [Dashboard data](https://github.com/moreganooooo/career-ops/blob/main/dashboard/internal/data/career.go): view model · Dashboard data derivation and career modeling used to present repository state. · `dashboard/internal/data/career.go`

### Persistent state

File-based datasets and contracts that act as the system of record.

- [State files](https://github.com/moreganooooo/career-ops/blob/main/DATA_CONTRACT.md): file-based state · Persistent markdown, TSV, CSV, and YAML data that track applications, claims, skills, and tracker state. · `DATA_CONTRACT.md`
- [Config layer](https://github.com/moreganooooo/career-ops/blob/main/templates/portals.example.yml): customization · Repository-local customization files for portals, states, profile templates, and release configuration. · `templates/portals.example.yml`

### Validation and CI

Health checks, consistency tools, and GitHub automation.

- [Checks](https://github.com/moreganooooo/career-ops/blob/main/doctor.mjs): health tooling · Liveness, sync, doctor, verification, and pipeline test scripts that enforce consistency. · `doctor.mjs`
- [GitHub Actions](https://github.com/moreganooooo/career-ops/blob/main/.github/workflows/test.yml): ci/release · Workflow automation for testing, security, dependency review, SBOM, stale issues, and releases. · `.github/workflows/test.yml`

## Connections

- Agent docs → Scan: directs · Agent instructions define how the main scan workflow is run.
- Modes → Core scripts: steers · Mode files supply prompts and operational context to the automation scripts.
- Scan → Providers: pulls jobs · The scanner queries source adapters to discover job postings.
- Providers → Shared parse: uses · Adapters share common fetch, recognition, and parse helpers.
- Providers → State files: writes raw data · Ingested listings are normalized into repository-backed state and artifacts.
- Scan → Checks: verifies · Optional liveness checks and pipeline validation can gate scanned items.
- Core scripts → Eval modes: uses · Core scripts call into evaluation and writing-oriented mode prompts.
- Eval modes → Profile assets: reads · Evaluation and personalization rely on profile, proof-point, and story-bank content.
- Core scripts → Templates: renders with · Generation scripts use HTML, LaTeX, and YAML templates for outputs and configuration.
- Core scripts → Reports: produces · Analysis and tracking scripts write report artifacts.
- Core scripts → PDF output: generates · PDF generation scripts emit final document artifacts.
- Batch mode → Batch runners: runs with · Batch mode is executed by runner scripts and worker helpers.
- Batch runners → Providers: fans out · Batch processing reuses the same ingestion adapters as single-job flow.
- Batch runners → Core scripts: reuses · Batch workers reuse the core orchestration and tracking logic.
- Dashboard → Dashboard data: uses · The Go TUI builds its screens from derived career and pipeline models.
- Dashboard data → State files: reads · Dashboard views are derived from the same file-based repository state.
- Checks → State files: checks · Consistency tools validate trackers, claims, sync, and generated artifacts.
- Checks → Core scripts: guards · Health checks verify the main automation pipeline end to end.
- GitHub Actions → Checks: runs · CI executes tests, security checks, and release automation around the local toolchain.
- Config layer → Modes: customizes · Local templates and config files shape operational modes and defaults.
- Config layer → State files: defines contract · Configuration files establish repository-local data and state boundaries.