# romek-rozen/intent-labeler architecture

> Architecture diagram of the GitHub repository romek-rozen/intent-labeler, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/romek-rozen/intent-labeler
- Repository: https://github.com/romek-rozen/intent-labeler

## Overview

Intent Labeler turns a Google SERP or supplied pages into intent labels, measured coverage and traffic shares, and a recommended content form. The main flow gathers and enriches page data, asks an LLM to group results, computes metrics in code, decides the expected form, and renders JSON or reports. The API and CLI are product entry points; the browser playground is also documented. Source excerpts establish the API and pipeline calls; some unsampled module relationships are omitted where the available evidence does not establish the invocation.

Main entry points: [`src/intent_labeler/api/app.py`](https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/api/app.py) (HTTP API), [`src/intent_labeler/pipeline.py`](https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/pipeline.py) (Analysis orchestration), [`src/intent_labeler/features/serp_source/dataforseo.py`](https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/features/serp_source/dataforseo.py) (SERP retrieval), [`src/intent_labeler/features/intent_labeling/labeler.py`](https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/features/intent_labeling/labeler.py) (Intent labeling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_cli["Command-line interface<br/>[cli.py]"]
  node_http["HTTP API<br/>[app.py]"]
  node_playground["Browser playground<br/>[app.js]"]
end

subgraph group_inputs["Inputs and enrichment"]
  node_serp["SERP retrieval<br/>[dataforseo.py]"]
  node_normalize["SERP normalization<br/>[normalize.py]"]
  node_pagefetch["Page fetching<br/>[fetch.py]"]
  node_extract["Page extraction<br/>[extract.py]"]
  node_volume["Search demand<br/>[dataforseo.py]"]
  node_seasonality["Seasonality<br/>[seasonality.py]"]
  node_traffic["Traffic estimates<br/>[dataforseo.py]"]
end

subgraph group_analysis["Intent analysis"]
  node_pipeline["Analysis orchestration<br/>[pipeline.py]"]
  node_labeler["Intent labeling<br/>[labeler.py]"]
  node_contract["Label contract<br/>[contract.py]"]
  node_metrics["Code-based metrics<br/>[measure.py]"]
  node_form["Content-form decision<br/>[decide.py]"]
end

subgraph group_presentation["Results and reports"]
  node_htmlreport["HTML report<br/>[html.py]"]
  node_markdown["Markdown report<br/>[markdown.py]"]
  node_charts["SVG charts<br/>[charts.py]"]
  node_palette["Report palette<br/>[palette.py]"]
end

subgraph group_shared["Shared runtime"]
  node_llm["LLM client and cache<br/>[llm.py]"]
  node_types["Snapshot and result types<br/>[types.py]"]
  node_config["LLM configuration<br/>[config.py]"]
end

node_analyst(("Analyst"))
node_dataforseo["DataForSEO"]
node_model["OpenAI-compatible model"]

node_analyst -->|"runs analysis"| node_cli
node_analyst -.->|"submits requests"| node_http
node_analyst -->|"uses playground"| node_playground
node_cli -.->|"runs pipeline"| node_pipeline
node_http -->|"fetches results"| node_serp
node_serp -.->|"queries SERP"| node_dataforseo
node_http -->|"adds demand"| node_volume
node_volume -.->|"queries volume"| node_dataforseo
node_http -->|"adds estimates"| node_traffic
node_traffic -.->|"queries traffic"| node_dataforseo
node_serp -->|"normalizes response"| node_normalize
node_http -->|"runs analysis"| node_pipeline
node_http -->|"builds page snapshot"| node_pagefetch
node_pipeline -->|"enriches pages"| node_pagefetch
node_pagefetch -->|"extracts page data"| node_extract
node_pipeline -->|"labels results"| node_labeler
node_labeler -->|"validates labels"| node_contract
node_labeler -->|"requests JSON labels"| node_llm
node_llm -->|"uses settings"| node_config
node_llm -->|"sends chat request"| node_model
node_pipeline -->|"measures results"| node_metrics
node_pipeline -->|"decides content form"| node_form
node_pipeline -->|"computes seasonality"| node_seasonality
node_pipeline -->|"accepts snapshot"| node_types
node_http -->|"renders HTML"| node_htmlreport
node_http -->|"renders Markdown"| node_markdown
node_htmlreport -->|"embeds charts"| node_charts
node_htmlreport -->|"uses colors"| node_palette
node_charts -->|"uses palette"| node_palette

click node_cli "https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/cli.py"
click node_http "https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/api/app.py"
click node_playground "https://github.com/romek-rozen/intent-labeler/blob/main/site/app.js"
click node_serp "https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/features/serp_source/dataforseo.py"
click node_normalize "https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/features/serp_source/normalize.py"
click node_pagefetch "https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/features/page_source/fetch.py"
click node_extract "https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/features/page_source/extract.py"
click node_volume "https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/features/search_volume/dataforseo.py"
click node_seasonality "https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/features/search_volume/seasonality.py"
click node_traffic "https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/features/traffic/dataforseo.py"
click node_pipeline "https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/pipeline.py"
click node_labeler "https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/features/intent_labeling/labeler.py"
click node_contract "https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/features/intent_labeling/contract.py"
click node_llm "https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/core/llm.py"
click node_metrics "https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/features/metrics/measure.py"
click node_form "https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/features/form_decision/decide.py"
click node_types "https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/core/types.py"
click node_config "https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/core/config.py"
click node_htmlreport "https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/features/report/html.py"
click node_markdown "https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/features/report/markdown.py"
click node_charts "https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/features/report/charts.py"
click node_palette "https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/features/report/palette.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_cli,node_http,node_playground toneBlue
class node_serp,node_normalize,node_pagefetch,node_extract,node_volume,node_seasonality,node_traffic toneAmber
class node_pipeline,node_labeler,node_contract,node_metrics,node_form toneMint
class node_htmlreport,node_markdown,node_charts,node_palette toneRose
class node_llm,node_types,node_config,node_analyst,node_dataforseo,node_model toneIndigo
```

## Components

### Entry points

- [Command-line interface](https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/cli.py): `src/intent_labeler/cli.py`
- [HTTP API](https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/api/app.py): `src/intent_labeler/api/app.py`
- [Browser playground](https://github.com/romek-rozen/intent-labeler/blob/main/site/app.js): `site/app.js`

### Inputs and enrichment

- [SERP retrieval](https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/features/serp_source/dataforseo.py): `src/intent_labeler/features/serp_source/dataforseo.py`
- [SERP normalization](https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/features/serp_source/normalize.py): `src/intent_labeler/features/serp_source/normalize.py`
- [Page fetching](https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/features/page_source/fetch.py): `src/intent_labeler/features/page_source/fetch.py`
- [Page extraction](https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/features/page_source/extract.py): `src/intent_labeler/features/page_source/extract.py`
- [Search demand](https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/features/search_volume/dataforseo.py): `src/intent_labeler/features/search_volume/dataforseo.py`
- [Seasonality](https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/features/search_volume/seasonality.py): `src/intent_labeler/features/search_volume/seasonality.py`
- [Traffic estimates](https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/features/traffic/dataforseo.py): `src/intent_labeler/features/traffic/dataforseo.py`

### Intent analysis

- [Analysis orchestration](https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/pipeline.py): `src/intent_labeler/pipeline.py`
- [Intent labeling](https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/features/intent_labeling/labeler.py): `src/intent_labeler/features/intent_labeling/labeler.py`
- [Label contract](https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/features/intent_labeling/contract.py): `src/intent_labeler/features/intent_labeling/contract.py`
- [Code-based metrics](https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/features/metrics/measure.py): `src/intent_labeler/features/metrics/measure.py`
- [Content-form decision](https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/features/form_decision/decide.py): `src/intent_labeler/features/form_decision/decide.py`

### Results and reports

- [HTML report](https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/features/report/html.py): `src/intent_labeler/features/report/html.py`
- [Markdown report](https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/features/report/markdown.py): `src/intent_labeler/features/report/markdown.py`
- [SVG charts](https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/features/report/charts.py): `src/intent_labeler/features/report/charts.py`
- [Report palette](https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/features/report/palette.py): `src/intent_labeler/features/report/palette.py`

### Shared runtime

- [LLM client and cache](https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/core/llm.py): `src/intent_labeler/core/llm.py`
- [Snapshot and result types](https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/core/types.py): `src/intent_labeler/core/types.py`
- [LLM configuration](https://github.com/romek-rozen/intent-labeler/blob/main/src/intent_labeler/core/config.py): `src/intent_labeler/core/config.py`

### Other components

- **Analyst**
- **DataForSEO**
- **OpenAI-compatible model**

## Connections

- Analyst → Command-line interface: runs analysis (evidence: `README.md`)
- Analyst → HTTP API: submits requests
- Analyst → Browser playground: uses playground (evidence: `README.md`)
- Command-line interface → Analysis orchestration: runs pipeline (evidence: `src/intent_labeler/cli.py`)
- HTTP API → SERP retrieval: fetches results (evidence: `src/intent_labeler/api/app.py`)
- SERP retrieval → DataForSEO: queries SERP
- HTTP API → Search demand: adds demand (evidence: `src/intent_labeler/api/app.py`)
- Search demand → DataForSEO: queries volume
- HTTP API → Traffic estimates: adds estimates (evidence: `src/intent_labeler/api/app.py`)
- Traffic estimates → DataForSEO: queries traffic
- SERP retrieval → SERP normalization: normalizes response (evidence: `src/intent_labeler/features/serp_source/dataforseo.py`)
- HTTP API → Analysis orchestration: runs analysis (evidence: `src/intent_labeler/api/app.py`)
- HTTP API → Page fetching: builds page snapshot (evidence: `src/intent_labeler/api/app.py`)
- Analysis orchestration → Page fetching: enriches pages (evidence: `src/intent_labeler/pipeline.py`)
- Page fetching → Page extraction: extracts page data (evidence: `src/intent_labeler/features/page_source/fetch.py`)
- Analysis orchestration → Intent labeling: labels results (evidence: `src/intent_labeler/pipeline.py`)
- Intent labeling → Label contract: validates labels (evidence: `src/intent_labeler/features/intent_labeling/labeler.py`)
- Intent labeling → LLM client and cache: requests JSON labels (evidence: `src/intent_labeler/features/intent_labeling/labeler.py`)
- LLM client and cache → LLM configuration: uses settings (evidence: `src/intent_labeler/core/llm.py`)
- LLM client and cache → OpenAI-compatible model: sends chat request (evidence: `src/intent_labeler/core/llm.py`)
- Analysis orchestration → Code-based metrics: measures results (evidence: `src/intent_labeler/pipeline.py`)
- Analysis orchestration → Content-form decision: decides content form (evidence: `src/intent_labeler/pipeline.py`)
- Analysis orchestration → Seasonality: computes seasonality (evidence: `src/intent_labeler/pipeline.py`)
- Analysis orchestration → Snapshot and result types: accepts snapshot (evidence: `src/intent_labeler/pipeline.py`)
- HTTP API → HTML report: renders HTML (evidence: `src/intent_labeler/api/app.py`)
- HTTP API → Markdown report: renders Markdown (evidence: `src/intent_labeler/api/app.py`)
- HTML report → SVG charts: embeds charts (evidence: `src/intent_labeler/features/report/html.py`)
- HTML report → Report palette: uses colors (evidence: `src/intent_labeler/features/report/html.py`)
- SVG charts → Report palette: uses palette (evidence: `src/intent_labeler/features/report/charts.py`)