docs/ARCHITECTURE.md
at acf072aArchitecture
System Overview
Plain text
┌─────────────────────────────────┐ │ Claude Code Agent │ │ (reads CLAUDE.md + modes/*.md) │ └──────────┬──────────────────────┘ │ ┌──────────────────┼──────────────────────┐ │ │ │ ┌──────▼──────┐ ┌──────▼──────┐ ┌───────────▼────────┐ │ Single Eval │ │ Portal Scan │ │ Batch Process │ │ (auto-pipe) │ │ (scan.md) │ │ (batch-runner) │ └──────┬──────┘ └──────┬──────┘ └───────────┬────────┘ │ │ │ │ ┌──────▼──────┐ ┌────▼─────┐ │ │ pipeline.md │ │ N workers│ │ │ (URL inbox) │ │ (claude -p) │ └─────────────┘ └────┬─────┘ │ │ ┌──────▼──────────────────────────────────────────▼──────┐ │ Output Pipeline │ │ ┌──────────┐ ┌────────────┐ ┌───────────────────┐ │ │ │ Report.md│ │ PDF (HTML │ │ Tracker TSV │ │ │ │ (A-F eval)│ │ → Puppeteer)│ │ (merge-tracker) │ │ │ └──────────┘ └────────────┘ └───────────────────┘ │ └────────────────────────────────────────────────────────┘ │ ┌──────────▼──────────┐ │ data/applications.md │ │ (canonical tracker) │ └──────────────────────┘Evaluation Flow (Single Offer)
- Input: User pastes JD text or URL
- Extract: Playwright/WebFetch extracts JD from URL
- Classify: Detect archetype (1 of 6 types)
- Evaluate: 6 blocks (A-F):
- A: Role summary
- B: CV match (gaps + mitigation)
- C: Level strategy
- D: Comp research (WebSearch)
- E: CV personalization plan
- F: Interview prep (STAR stories)
- Score: Weighted average across 10 dimensions (1-5)
- Report: Save as
reports/{num}-{company}-{date}.md - PDF: Generate ATS-optimized CV (
generate-pdf.mjs) - Track: Write TSV to
batch/tracker-additions/, auto-merged
Batch Processing
The batch system processes multiple offers in parallel:
Plain text
batch-input.tsv → batch-runner.sh → N × claude -p workers(id, url, source) (orchestrator) (self-contained prompt) │ batch-state.tsv (tracks progress)Each worker is a headless Claude instance (claude -p) that receives the full batch-prompt.md as context. Workers produce:
- Report .md
- Tracker TSV line
The orchestrator manages parallelism, state, retries, and resume.
Data Flow
Plain text
cv.md → Evaluation contextarticle-digest.md → Proof points for matchingconfig/profile.yml → Candidate identityportals.yml → Scanner configurationtemplates/states.yml → Canonical status valuestemplates/cv-template.html → PDF generation templateFile Naming Conventions
- Reports:
{###}-{company-slug}-{YYYY-MM-DD}.md(3-digit zero-padded) - PDFs:
cv-candidate-{company-slug}-{YYYY-MM-DD}.pdf - Tracker TSVs:
batch/tracker-additions/{id}.tsv
Pipeline Integrity
Scripts maintain data consistency:
| Script | Purpose |
|---|---|
merge-tracker.mjs | Merges batch TSV additions into applications.md |
verify-pipeline.mjs | Health check: statuses, duplicates, links |
dedup-tracker.mjs | Removes duplicate entries by company+role |
normalize-statuses.mjs | Maps status aliases to canonical values |
cv-sync-check.mjs | Validates setup consistency |
Dashboard TUI
The dashboard/ directory contains a standalone Go TUI application that visualizes the pipeline:
- Filter tabs: All, Evaluada, Aplicado, Entrevista, Top >=4, No Aplicar
- Sort modes: Score, Date, Company, Status
- Grouped/flat view
- Lazy-loaded report previews
- Inline status picker