moreganooooo/career-ops

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.