# roni-clei-santos/ai-company-prospector architecture

> Architecture diagram of the GitHub repository roni-clei-santos/ai-company-prospector, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/roni-clei-santos/ai-company-prospector
- Repository: https://github.com/roni-clei-santos/ai-company-prospector

## Overview

AI Company Prospector is a Claude Code agent and companion scripts for researching companies that use a candidate’s technology, tracking outreach, and preparing drafts for the candidate to review and send. The main workflow builds a sourced company spreadsheet, processes companies in batches with memory, and presents pending drafts and follow-ups in a dashboard. The README also describes a browser-only spreadsheet mode and optional read-only LinkedIn research. Edges are based on README workflow statements or shown script imports and behavior; skill-to-script runtime wiring is not established by the excerpts.

Main entry points: [`skills/next-companies/SKILL.md`](https://github.com/roni-clei-santos/ai-company-prospector/blob/main/skills/next-companies/SKILL.md) (Next companies skill), [`scripts/gerar_painel.py`](https://github.com/roni-clei-santos/ai-company-prospector/blob/main/scripts/gerar_painel.py) (Panel data builder), [`skills/build-company-list/SKILL.md`](https://github.com/roni-clei-santos/ai-company-prospector/blob/main/skills/build-company-list/SKILL.md) (Company list skill), [`docs/web/PROMPT-planilha.md`](https://github.com/roni-clei-santos/ai-company-prospector/blob/main/docs/web/PROMPT-planilha.md) (Browser-only mode)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_research["Research workflow"]
  node_build_skill["Company list skill<br/>[SKILL.md]"]
  node_web_mode["Browser-only mode<br/>[PROMPT-planilha.md]"]
  node_spreadsheet[("Company spreadsheet<br/>[montar_planilha.py]")]
  node_next_skill["Next companies skill<br/>[SKILL.md]"]
end

subgraph group_tracking["Outreach tracking"]
  node_round_reports["Round reports<br/>[gerar_painel.py]"]
  node_progress[("Progress and decisions<br/>[registrar.py]")]
  node_drafts["Outreach drafts"]
  node_contact_checks["Contact safeguards"]
  node_note_checks["Invite-note checks<br/>[checar_notas.py]"]
  node_common_helpers["Project and status helpers<br/>[common.py]"]
end

subgraph group_dashboard["Dashboard"]
  node_panel_skill["Panel skill<br/>[SKILL.md]"]
  node_panel_builder["Panel data builder<br/>[gerar_painel.py]"]
  node_panel_server["Local panel server<br/>[servidor_painel.py]"]
  node_panel_ui["Panel UI<br/>[index.html]"]
  node_report_renderer["Report renderer<br/>[relatorio_html.py]"]
end

subgraph group_candidate["Candidate materials"]
  node_profile["Candidate profile<br/>[perfil.example.md]"]
  node_tailored_cv["Tailored CV PDF<br/>[gerar_cv.py]"]
end

node_candidate_user(("Candidate"))
node_claude_code{{"Claude Code agent"}}
node_public_sources[("Public sources")]
node_chrome_linkedin{{"Chrome / LinkedIn"}}

node_candidate_user -->|"requests research"| node_claude_code
node_claude_code -->|"runs skill"| node_build_skill
node_build_skill -->|"researches companies"| node_public_sources
node_build_skill -->|"builds list"| node_spreadsheet
node_candidate_user -->|"pastes prompt"| node_web_mode
node_web_mode -->|"researches companies"| node_public_sources
node_web_mode -->|"returns workbook"| node_spreadsheet
node_claude_code -->|"runs batches"| node_next_skill
node_candidate_user -->|"starts round"| node_next_skill
node_next_skill -->|"processes companies"| node_spreadsheet
node_next_skill -->|"uses candidate facts"| node_profile
node_next_skill -->|"reads LinkedIn"| node_chrome_linkedin
node_next_skill -->|"records round"| node_round_reports
node_next_skill -->|"prepares drafts"| node_drafts
node_next_skill -->|"creates tailored CV"| node_tailored_cv
node_candidate_user -->|"reviews and sends"| node_drafts
node_round_reports -->|"tracks across rounds"| node_progress
node_panel_skill -->|"opens dashboard"| node_panel_builder
node_panel_builder -->|"builds dashboard data"| node_panel_ui
node_panel_builder -->|"reads reports"| node_round_reports
node_panel_builder -->|"reads drafts"| node_drafts
node_panel_builder -->|"reads progress"| node_progress
node_panel_server -->|"refreshes panel"| node_panel_builder
node_panel_server -->|"records decisions"| node_progress
node_panel_builder -->|"renders reports"| node_report_renderer
node_contact_checks -->|"uses safeguards"| node_common_helpers
node_note_checks -->|"loads profile rules"| node_common_helpers

click node_build_skill "https://github.com/roni-clei-santos/ai-company-prospector/blob/main/skills/build-company-list/SKILL.md"
click node_web_mode "https://github.com/roni-clei-santos/ai-company-prospector/blob/main/docs/web/PROMPT-planilha.md"
click node_spreadsheet "https://github.com/roni-clei-santos/ai-company-prospector/blob/main/scripts/montar_planilha.py"
click node_next_skill "https://github.com/roni-clei-santos/ai-company-prospector/blob/main/skills/next-companies/SKILL.md"
click node_profile "https://github.com/roni-clei-santos/ai-company-prospector/blob/main/perfil.example.md"
click node_round_reports "https://github.com/roni-clei-santos/ai-company-prospector/blob/main/scripts/gerar_painel.py"
click node_progress "https://github.com/roni-clei-santos/ai-company-prospector/blob/main/scripts/registrar.py"
click node_drafts "https://github.com/roni-clei-santos/ai-company-prospector/blob/main/scripts/checar_nao_contatar.py"
click node_tailored_cv "https://github.com/roni-clei-santos/ai-company-prospector/blob/main/scripts/gerar_cv.py"
click node_contact_checks "https://github.com/roni-clei-santos/ai-company-prospector/blob/main/scripts/checar_nao_contatar.py"
click node_note_checks "https://github.com/roni-clei-santos/ai-company-prospector/blob/main/scripts/checar_notas.py"
click node_common_helpers "https://github.com/roni-clei-santos/ai-company-prospector/blob/main/scripts/common.py"
click node_panel_skill "https://github.com/roni-clei-santos/ai-company-prospector/blob/main/skills/painel/SKILL.md"
click node_panel_builder "https://github.com/roni-clei-santos/ai-company-prospector/blob/main/scripts/gerar_painel.py"
click node_panel_server "https://github.com/roni-clei-santos/ai-company-prospector/blob/main/scripts/servidor_painel.py"
click node_panel_ui "https://github.com/roni-clei-santos/ai-company-prospector/blob/main/painel/index.html"
click node_report_renderer "https://github.com/roni-clei-santos/ai-company-prospector/blob/main/scripts/relatorio_html.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_build_skill,node_web_mode,node_spreadsheet,node_next_skill toneBlue
class node_round_reports,node_progress,node_drafts,node_contact_checks,node_note_checks,node_common_helpers,node_public_sources toneAmber
class node_panel_skill,node_panel_builder,node_panel_server,node_panel_ui,node_report_renderer toneMint
class node_profile,node_tailored_cv toneRose
class node_candidate_user,node_claude_code,node_chrome_linkedin toneIndigo
```

## Components

### Research workflow

- [Company list skill](https://github.com/roni-clei-santos/ai-company-prospector/blob/main/skills/build-company-list/SKILL.md): `skills/build-company-list/SKILL.md`
- [Browser-only mode](https://github.com/roni-clei-santos/ai-company-prospector/blob/main/docs/web/PROMPT-planilha.md): `docs/web/PROMPT-planilha.md`
- [Company spreadsheet](https://github.com/roni-clei-santos/ai-company-prospector/blob/main/scripts/montar_planilha.py): `scripts/montar_planilha.py`
- [Next companies skill](https://github.com/roni-clei-santos/ai-company-prospector/blob/main/skills/next-companies/SKILL.md): `skills/next-companies/SKILL.md`

### Outreach tracking

- [Round reports](https://github.com/roni-clei-santos/ai-company-prospector/blob/main/scripts/gerar_painel.py): `scripts/gerar_painel.py`
- [Progress and decisions](https://github.com/roni-clei-santos/ai-company-prospector/blob/main/scripts/registrar.py): `scripts/registrar.py`
- [Outreach drafts](https://github.com/roni-clei-santos/ai-company-prospector/blob/main/scripts/checar_nao_contatar.py): `scripts/checar_nao_contatar.py`
- [Contact safeguards](https://github.com/roni-clei-santos/ai-company-prospector/blob/main/scripts/checar_nao_contatar.py): `scripts/checar_nao_contatar.py`
- [Invite-note checks](https://github.com/roni-clei-santos/ai-company-prospector/blob/main/scripts/checar_notas.py): `scripts/checar_notas.py`
- [Project and status helpers](https://github.com/roni-clei-santos/ai-company-prospector/blob/main/scripts/common.py): `scripts/common.py`

### Dashboard

- [Panel skill](https://github.com/roni-clei-santos/ai-company-prospector/blob/main/skills/painel/SKILL.md): `skills/painel/SKILL.md`
- [Panel data builder](https://github.com/roni-clei-santos/ai-company-prospector/blob/main/scripts/gerar_painel.py): `scripts/gerar_painel.py`
- [Local panel server](https://github.com/roni-clei-santos/ai-company-prospector/blob/main/scripts/servidor_painel.py): `scripts/servidor_painel.py`
- [Panel UI](https://github.com/roni-clei-santos/ai-company-prospector/blob/main/painel/index.html): `painel/index.html`
- [Report renderer](https://github.com/roni-clei-santos/ai-company-prospector/blob/main/scripts/relatorio_html.py): `scripts/relatorio_html.py`

### Candidate materials

- [Candidate profile](https://github.com/roni-clei-santos/ai-company-prospector/blob/main/perfil.example.md): `perfil.example.md`
- [Tailored CV PDF](https://github.com/roni-clei-santos/ai-company-prospector/blob/main/scripts/gerar_cv.py): `scripts/gerar_cv.py`

### Other components

- **Candidate**
- **Claude Code agent**
- **Public sources**
- **Chrome / LinkedIn**

## Connections

- Candidate → Claude Code agent: requests research (evidence: `README.md`)
- Claude Code agent → Company list skill: runs skill (evidence: `README.md`)
- Company list skill → Public sources: researches companies (evidence: `README.md`)
- Company list skill → Company spreadsheet: builds list (evidence: `README.md`)
- Candidate → Browser-only mode: pastes prompt (evidence: `README.md`)
- Browser-only mode → Public sources: researches companies (evidence: `README.md`)
- Browser-only mode → Company spreadsheet: returns workbook (evidence: `README.md`)
- Claude Code agent → Next companies skill: runs batches (evidence: `README.md`)
- Candidate → Next companies skill: starts round (evidence: `README.md`)
- Next companies skill → Company spreadsheet: processes companies (evidence: `README.md`)
- Next companies skill → Candidate profile: uses candidate facts (evidence: `README.md`)
- Next companies skill → Chrome / LinkedIn: reads LinkedIn (evidence: `README.md`)
- Next companies skill → Round reports: records round (evidence: `README.md`)
- Next companies skill → Outreach drafts: prepares drafts (evidence: `README.md`)
- Next companies skill → Tailored CV PDF: creates tailored CV (evidence: `README.md`)
- Candidate → Outreach drafts: reviews and sends (evidence: `README.md`)
- Round reports → Progress and decisions: tracks across rounds (evidence: `README.md`)
- Panel skill → Panel data builder: opens dashboard (evidence: `README.md`)
- Panel data builder → Panel UI: builds dashboard data (evidence: `scripts/gerar_painel.py`)
- Panel data builder → Round reports: reads reports (evidence: `scripts/gerar_painel.py`)
- Panel data builder → Outreach drafts: reads drafts (evidence: `scripts/gerar_painel.py`)
- Panel data builder → Progress and decisions: reads progress (evidence: `scripts/gerar_painel.py`)
- Local panel server → Panel data builder: refreshes panel (evidence: `scripts/servidor_painel.py`)
- Local panel server → Progress and decisions: records decisions (evidence: `scripts/servidor_painel.py`)
- Panel data builder → Report renderer: renders reports (evidence: `scripts/gerar_painel.py`)
- Contact safeguards → Project and status helpers: uses safeguards (evidence: `scripts/checar_nao_contatar.py`)
- Invite-note checks → Project and status helpers: loads profile rules (evidence: `scripts/checar_notas.py`)