# ontherein/bettersearch-rules architecture

> Architecture diagram of the GitHub repository ontherein/bettersearch-rules, 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/ontherein/bettersearch-rules
- Repository: https://github.com/ontherein/bettersearch-rules

## Overview

bettersearch-rules is a community-maintained rule-list dataset for BetterSearch and uBlacklist. Its main use is that BetterSearch checks search results against the sharded known-site list, using attached names to identify brand matches; users may separately subscribe to the lookalike list. The repository also generates the known-site shards from Wikidata and Majestic Million data, and supports community reports and appeals. Generation details come from the README and build-script excerpts; consumer behavior is documented in the README, not shown in sampled consumer code.

Main entry points: [`scripts/build.mjs`](https://github.com/ontherein/bettersearch-rules/blob/main/scripts/build.mjs) (Shard generator), [`lookalike.txt`](https://github.com/ontherein/bettersearch-rules/blob/main/lookalike.txt) (Lookalike rules), [`sites`](https://github.com/ontherein/bettersearch-rules/tree/main/sites) (Site shards), [`.github/ISSUE_TEMPLATE/report.yml`](https://github.com/ontherein/bettersearch-rules/blob/main/.github/ISSUE_TEMPLATE/report.yml) (Report template)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_rules["Rule Lists"]
  node_lookalikes["Lookalike rules<br/>[lookalike.txt]"]
end

subgraph group_known["Known Sites"]
  node_site_shards[("Site shards")]
end

subgraph group_generation["Data Generation"]
  node_generator["Shard generator<br/>[build.mjs]"]
end

subgraph group_community["Community Review"]
  node_report_form["Report template<br/>[report.yml]"]
  node_appeal_form["Appeal template<br/>[appeal.yml]"]
end

node_searcher(("Search user"))
node_bettersearch["BetterSearch"]
node_ublacklist["uBlacklist"]
node_wikidata["Wikidata"]
node_majestic["Majestic Million"]
node_reporter(("Community reporter"))
node_appealer(("Site owner"))

node_searcher -->|"searches with"| node_bettersearch
node_bettersearch -->|"checks results"| node_site_shards
node_bettersearch -.->|"uses rules"| node_lookalikes
node_searcher -->|"subscribes in"| node_ublacklist
node_ublacklist -->|"reads list"| node_lookalikes
node_wikidata -->|"provides domains"| node_generator
node_majestic -->|"provides domains"| node_generator
node_generator -->|"writes shards"| node_site_shards
node_reporter -->|"submits report"| node_report_form
node_appealer -->|"submits appeal"| node_appeal_form

click node_lookalikes "https://github.com/ontherein/bettersearch-rules/blob/main/lookalike.txt"
click node_site_shards "https://github.com/ontherein/bettersearch-rules/tree/main/sites"
click node_generator "https://github.com/ontherein/bettersearch-rules/blob/main/scripts/build.mjs"
click node_report_form "https://github.com/ontherein/bettersearch-rules/blob/main/.github/ISSUE_TEMPLATE/report.yml"
click node_appeal_form "https://github.com/ontherein/bettersearch-rules/blob/main/.github/ISSUE_TEMPLATE/appeal.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_lookalikes,node_searcher toneBlue
class node_site_shards toneAmber
class node_generator toneMint
class node_report_form,node_appeal_form toneRose
class node_bettersearch,node_ublacklist,node_wikidata,node_majestic,node_reporter,node_appealer toneIndigo
```

## Components

### Rule Lists

- [Lookalike rules](https://github.com/ontherein/bettersearch-rules/blob/main/lookalike.txt): `lookalike.txt`

### Known Sites

- [Site shards](https://github.com/ontherein/bettersearch-rules/tree/main/sites): `sites`

### Data Generation

- [Shard generator](https://github.com/ontherein/bettersearch-rules/blob/main/scripts/build.mjs): `scripts/build.mjs`

### Community Review

- [Report template](https://github.com/ontherein/bettersearch-rules/blob/main/.github/ISSUE_TEMPLATE/report.yml): `.github/ISSUE_TEMPLATE/report.yml`
- [Appeal template](https://github.com/ontherein/bettersearch-rules/blob/main/.github/ISSUE_TEMPLATE/appeal.yml): `.github/ISSUE_TEMPLATE/appeal.yml`

### Other components

- **Search user**
- **BetterSearch**
- **uBlacklist**
- **Wikidata**
- **Majestic Million**
- **Community reporter**
- **Site owner**

## Connections

- Search user → BetterSearch: searches with (evidence: `README.md`)
- BetterSearch → Site shards: checks results (evidence: `README.md`)
- BetterSearch → Lookalike rules: uses rules (evidence: `README.md`)
- Search user → uBlacklist: subscribes in (evidence: `README.md`)
- uBlacklist → Lookalike rules: reads list (evidence: `README.md`)
- Wikidata → Shard generator: provides domains (evidence: `scripts/build.mjs`)
- Majestic Million → Shard generator: provides domains (evidence: `scripts/build.mjs`)
- Shard generator → Site shards: writes shards (evidence: `scripts/build.mjs`)
- Community reporter → Report template: submits report (evidence: `README.md`)
- Site owner → Appeal template: submits appeal (evidence: `README.md`)