# coreinch/namernut architecture

> Architecture diagram of the GitHub repository coreinch/namernut, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/coreinch/namernut
- Repository: https://github.com/coreinch/namernut

## Overview

Namernut generates business-name candidates from a dictionary and optional AI or spelling variants, checks domains and social handles, filters name quality, and can score real-world brand competition. The principal flow runs from the browser through the discovery API and discovery engine, then streams findings back to saved results and controls. The graph also preserves the documented favorites/archive and brandability capabilities. Relationships for unsampled integrations are included only where the README or source index supports them; some internal availability-check details are not excerpted.

Main entry points: [`src/app/api/discover/route.ts`](https://github.com/coreinch/namernut/blob/main/src/app/api/discover/route.ts) (Discovery endpoint), [`src/app/page.tsx`](https://github.com/coreinch/namernut/blob/main/src/app/page.tsx) (App workspace), [`src/hooks/useDiscoveryRun.ts`](https://github.com/coreinch/namernut/blob/main/src/hooks/useDiscoveryRun.ts) (Run controller), [`src/lib/discovery.ts`](https://github.com/coreinch/namernut/blob/main/src/lib/discovery.ts) (Discovery engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User experience"]
  node_page["App workspace<br/>[page.tsx]"]
  node_searchbar["Search controls<br/>[SearchBar.tsx]"]
  node_settings["Search settings<br/>[SettingsPanel.tsx]"]
  node_runhook["Run controller<br/>[useDiscoveryRun.ts]"]
  node_resultcard["Name result card<br/>[ResultCard.tsx]"]
end

subgraph group_generation["Name generation"]
  node_discoverapi["Discovery endpoint<br/>[route.ts]"]
  node_dictionary[("Word dictionary<br/>[dictionary.ts]")]
  node_candidate["Candidate builder<br/>[candidates.ts]"]
  node_suggestions["AI name variants<br/>[suggestNames.ts]"]
  node_synonyms["Synonym suggestions<br/>[synonyms.ts]"]
  node_invented["Invented names<br/>[inventedNames.ts]"]
  node_spellings["Alternate spellings"]
  node_engine["Discovery engine<br/>[discovery.ts]"]
  node_quality["Name quality filters<br/>[discovery.ts]"]
end

subgraph group_checks["Availability checks"]
  node_checks["Availability checks<br/>[discoveryChecks.ts]"]
  node_social["Social handle checks<br/>[socialStatus.ts]"]
  node_registries["Domain and platform services<br/>[rdap.ts]"]
end

subgraph group_brand["Brandability analysis"]
  node_brandapi["Brandability endpoint<br/>[route.ts]"]
  node_brandability["Competition scoring<br/>[brandability.ts]"]
  node_searchprovider["Search fallback<br/>[searchProvider.ts]"]
  node_serper["Serper search<br/>[serperSearch.ts]"]
  node_twocaptcha["2captcha search"]
  node_serpent["Serpent search<br/>[serpentSearch.ts]"]
  node_kilocode["LLM service<br/>[kilocode.ts]"]
end

subgraph group_state["Results and state"]
  node_persist["Local state"]
  node_results["Result lists<br/>[useResultLists.ts]"]
  node_history[("Favorites and archive")]
end

node_user(("Name seeker"))

node_user -->|"uses"| node_page
node_page -->|"renders"| node_searchbar
node_page -->|"renders"| node_settings
node_page -->|"starts runs"| node_runhook
node_page -->|"loads state"| node_persist
node_runhook -.->|"requests stream"| node_discoverapi
node_discoverapi -->|"loads words"| node_dictionary
node_discoverapi -->|"requests variants"| node_suggestions
node_discoverapi -->|"requests synonyms"| node_synonyms
node_discoverapi -->|"requests names"| node_invented
node_discoverapi -->|"uses variants"| node_spellings
node_discoverapi -->|"runs discovery"| node_engine
node_engine -->|"builds space"| node_candidate
node_candidate -->|"uses word pool"| node_dictionary
node_engine -->|"filters candidates"| node_quality
node_engine -->|"checks domains"| node_checks
node_checks -.->|"checks handles"| node_social
node_checks -.->|"checks domains"| node_registries
node_runhook -.->|"checks found names"| node_brandapi
node_brandapi -->|"scores names"| node_brandability
node_brandability -->|"searches competition"| node_searchprovider
node_searchprovider -->|"dispatches search"| node_serper
node_searchprovider -->|"dispatches fallback"| node_twocaptcha
node_searchprovider -->|"dispatches fallback"| node_serpent
node_brandability -->|"generates summary"| node_kilocode
node_runhook -->|"updates results"| node_persist
node_page -.->|"shows lists"| node_results
node_results -->|"renders entries"| node_resultcard
node_resultcard -.->|"supports actions"| node_history
node_persist -->|"stores locally"| node_history

click node_page "https://github.com/coreinch/namernut/blob/main/src/app/page.tsx"
click node_searchbar "https://github.com/coreinch/namernut/blob/main/src/components/SearchBar.tsx"
click node_settings "https://github.com/coreinch/namernut/blob/main/src/components/SettingsPanel.tsx"
click node_runhook "https://github.com/coreinch/namernut/blob/main/src/hooks/useDiscoveryRun.ts"
click node_persist "https://github.com/coreinch/namernut/blob/main/src/hooks/usePersistedAppState.ts"
click node_discoverapi "https://github.com/coreinch/namernut/blob/main/src/app/api/discover/route.ts"
click node_dictionary "https://github.com/coreinch/namernut/blob/main/src/lib/dictionary.ts"
click node_candidate "https://github.com/coreinch/namernut/blob/main/src/lib/candidates.ts"
click node_suggestions "https://github.com/coreinch/namernut/blob/main/src/lib/suggestNames.ts"
click node_synonyms "https://github.com/coreinch/namernut/blob/main/src/lib/synonyms.ts"
click node_invented "https://github.com/coreinch/namernut/blob/main/src/lib/inventedNames.ts"
click node_spellings "https://github.com/coreinch/namernut/blob/main/src/lib/alternateSpelling.ts"
click node_engine "https://github.com/coreinch/namernut/blob/main/src/lib/discovery.ts"
click node_quality "https://github.com/coreinch/namernut/blob/main/src/lib/discovery.ts"
click node_checks "https://github.com/coreinch/namernut/blob/main/src/lib/discoveryChecks.ts"
click node_social "https://github.com/coreinch/namernut/blob/main/src/lib/socialStatus.ts"
click node_registries "https://github.com/coreinch/namernut/blob/main/src/lib/rdap.ts"
click node_brandapi "https://github.com/coreinch/namernut/blob/main/src/app/api/brandability/route.ts"
click node_brandability "https://github.com/coreinch/namernut/blob/main/src/lib/brandability.ts"
click node_searchprovider "https://github.com/coreinch/namernut/blob/main/src/lib/searchProvider.ts"
click node_serper "https://github.com/coreinch/namernut/blob/main/src/lib/serperSearch.ts"
click node_twocaptcha "https://github.com/coreinch/namernut/blob/main/src/lib/twocaptchaSearch.ts"
click node_serpent "https://github.com/coreinch/namernut/blob/main/src/lib/serpentSearch.ts"
click node_kilocode "https://github.com/coreinch/namernut/blob/main/src/lib/kilocode.ts"
click node_results "https://github.com/coreinch/namernut/blob/main/src/hooks/useResultLists.ts"
click node_resultcard "https://github.com/coreinch/namernut/blob/main/src/components/ResultCard.tsx"
click node_history "https://github.com/coreinch/namernut/blob/main/src/hooks/usePersistedAppState.ts"

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_page,node_searchbar,node_settings,node_runhook,node_resultcard toneBlue
class node_discoverapi,node_dictionary,node_candidate,node_suggestions,node_synonyms,node_invented,node_spellings,node_engine,node_quality toneAmber
class node_checks,node_social,node_registries toneMint
class node_brandapi,node_brandability,node_searchprovider,node_serper,node_twocaptcha,node_serpent,node_kilocode toneRose
class node_persist,node_results,node_history,node_user toneIndigo
```

## Components

### User experience

- [App workspace](https://github.com/coreinch/namernut/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [Search controls](https://github.com/coreinch/namernut/blob/main/src/components/SearchBar.tsx): `src/components/SearchBar.tsx`
- [Search settings](https://github.com/coreinch/namernut/blob/main/src/components/SettingsPanel.tsx): `src/components/SettingsPanel.tsx`
- [Run controller](https://github.com/coreinch/namernut/blob/main/src/hooks/useDiscoveryRun.ts): `src/hooks/useDiscoveryRun.ts`
- [Name result card](https://github.com/coreinch/namernut/blob/main/src/components/ResultCard.tsx): `src/components/ResultCard.tsx`

### Name generation

- [Discovery endpoint](https://github.com/coreinch/namernut/blob/main/src/app/api/discover/route.ts): `src/app/api/discover/route.ts`
- [Word dictionary](https://github.com/coreinch/namernut/blob/main/src/lib/dictionary.ts): `src/lib/dictionary.ts`
- [Candidate builder](https://github.com/coreinch/namernut/blob/main/src/lib/candidates.ts): `src/lib/candidates.ts`
- [AI name variants](https://github.com/coreinch/namernut/blob/main/src/lib/suggestNames.ts): `src/lib/suggestNames.ts`
- [Synonym suggestions](https://github.com/coreinch/namernut/blob/main/src/lib/synonyms.ts): `src/lib/synonyms.ts`
- [Invented names](https://github.com/coreinch/namernut/blob/main/src/lib/inventedNames.ts): `src/lib/inventedNames.ts`
- [Alternate spellings](https://github.com/coreinch/namernut/blob/main/src/lib/alternateSpelling.ts): `src/lib/alternateSpelling.ts`
- [Discovery engine](https://github.com/coreinch/namernut/blob/main/src/lib/discovery.ts): `src/lib/discovery.ts`
- [Name quality filters](https://github.com/coreinch/namernut/blob/main/src/lib/discovery.ts): `src/lib/discovery.ts`

### Availability checks

- [Availability checks](https://github.com/coreinch/namernut/blob/main/src/lib/discoveryChecks.ts): `src/lib/discoveryChecks.ts`
- [Social handle checks](https://github.com/coreinch/namernut/blob/main/src/lib/socialStatus.ts): `src/lib/socialStatus.ts`
- [Domain and platform services](https://github.com/coreinch/namernut/blob/main/src/lib/rdap.ts): `src/lib/rdap.ts`

### Brandability analysis

- [Brandability endpoint](https://github.com/coreinch/namernut/blob/main/src/app/api/brandability/route.ts): `src/app/api/brandability/route.ts`
- [Competition scoring](https://github.com/coreinch/namernut/blob/main/src/lib/brandability.ts): `src/lib/brandability.ts`
- [Search fallback](https://github.com/coreinch/namernut/blob/main/src/lib/searchProvider.ts): `src/lib/searchProvider.ts`
- [Serper search](https://github.com/coreinch/namernut/blob/main/src/lib/serperSearch.ts): `src/lib/serperSearch.ts`
- [2captcha search](https://github.com/coreinch/namernut/blob/main/src/lib/twocaptchaSearch.ts): `src/lib/twocaptchaSearch.ts`
- [Serpent search](https://github.com/coreinch/namernut/blob/main/src/lib/serpentSearch.ts): `src/lib/serpentSearch.ts`
- [LLM service](https://github.com/coreinch/namernut/blob/main/src/lib/kilocode.ts): `src/lib/kilocode.ts`

### Results and state

- [Local state](https://github.com/coreinch/namernut/blob/main/src/hooks/usePersistedAppState.ts): `src/hooks/usePersistedAppState.ts`
- [Result lists](https://github.com/coreinch/namernut/blob/main/src/hooks/useResultLists.ts): `src/hooks/useResultLists.ts`
- [Favorites and archive](https://github.com/coreinch/namernut/blob/main/src/hooks/usePersistedAppState.ts): `src/hooks/usePersistedAppState.ts`

### Other components

- **Name seeker**

## Connections

- Name seeker → App workspace: uses (evidence: `src/app/page.tsx`)
- App workspace → Search controls: renders (evidence: `src/app/page.tsx`)
- App workspace → Search settings: renders (evidence: `src/app/page.tsx`)
- App workspace → Run controller: starts runs (evidence: `src/app/page.tsx`)
- App workspace → Local state: loads state (evidence: `src/app/page.tsx`)
- Run controller → Discovery endpoint: requests stream
- Discovery endpoint → Word dictionary: loads words (evidence: `src/app/api/discover/route.ts`)
- Discovery endpoint → AI name variants: requests variants (evidence: `src/app/api/discover/route.ts`)
- Discovery endpoint → Synonym suggestions: requests synonyms (evidence: `src/app/api/discover/route.ts`)
- Discovery endpoint → Invented names: requests names (evidence: `src/app/api/discover/route.ts`)
- Discovery endpoint → Alternate spellings: uses variants (evidence: `src/app/api/discover/route.ts`)
- Discovery endpoint → Discovery engine: runs discovery (evidence: `src/app/api/discover/route.ts`)
- Discovery engine → Candidate builder: builds space (evidence: `src/lib/discovery.ts`)
- Candidate builder → Word dictionary: uses word pool (evidence: `src/lib/candidates.ts`)
- Discovery engine → Name quality filters: filters candidates (evidence: `src/lib/discovery.ts`)
- Discovery engine → Availability checks: checks domains (evidence: `src/lib/discovery.ts`)
- Availability checks → Social handle checks: checks handles
- Availability checks → Domain and platform services: checks domains
- Run controller → Brandability endpoint: checks found names
- Brandability endpoint → Competition scoring: scores names (evidence: `src/app/api/brandability/route.ts`)
- Competition scoring → Search fallback: searches competition (evidence: `src/lib/brandability.ts`)
- Search fallback → Serper search: dispatches search (evidence: `src/lib/searchProvider.ts`)
- Search fallback → 2captcha search: dispatches fallback (evidence: `src/lib/searchProvider.ts`)
- Search fallback → Serpent search: dispatches fallback (evidence: `src/lib/searchProvider.ts`)
- Competition scoring → LLM service: generates summary (evidence: `src/lib/brandability.ts`)
- Run controller → Local state: updates results (evidence: `src/hooks/useDiscoveryRun.ts`)
- App workspace → Result lists: shows lists (evidence: `src/app/page.tsx`)
- Result lists → Name result card: renders entries
- Name result card → Favorites and archive: supports actions
- Local state → Favorites and archive: stores locally (evidence: `src/hooks/usePersistedAppState.ts`)