01
Vue d'ensemble
A brand naming system for companies, apps, podcasts, nonprofits, communities, and personal brands. The user names what they are naming and what problem they solve; the system generates candidates, scores them, radio-tests them, checks domains and conflicts, screens trademarks, and returns a shortlist, not a dump of syllable soup.
Ce qui a été construit
A full naming pipeline with two generation modes. Local mode runs deterministic generators driven by curated YAML lexicons and naming philosophies. BYOK mode uses the visitor's own AI provider key, for that request only; when AI is on, every name comes from the provider, with no local filler. Production ships inside this site at /apps/namegen with a Nitro API behind it. The original Python application remains the open-source reference and the self-host path.
À qui il s'adresse
Founders, operators, and creators who need a shortlist of ownable names before they buy a domain or file a mark, not a thesaurus of product descriptions.
Contexte métier
Naming tools usually fail in one of two ways: they emit soft invented sludge, or they pretend host-paid AI is free. Namegen's job was to raise the quality bar with hard gates, keep AI optional and user-funded, and avoid a second deploy and subdomain for the live product.
02
Architecture
A stepped client orchestrates a server pipeline. Generation is one stage; domains, conflicts, and trademarks are separate stages, so the UI can show honest progress and survive partial failure.
ClientVue composer + results table
Edge APINitro routes under /api/namegen
Briefentity + problem → category, keywords, tone
one run row, stepped stages
Generatorlocal strategies or BYOK LLM, exclusive
Quality gatesfilter → soft-invented ban → brand quality → scorer
Checksradio → RDAP domains → conflict → trademark
StoreSQLite runs + candidates + favorite signals
Why stepped stages and hard invariants
Generation and checks are separate endpoints against one run row, so the client can step through them and a slow RDAP pass or a failed trademark stage degrades to a partial result instead of a spinner that lies. Two invariants bind the whole pipeline: when BYOK is enabled the run is AI-only, so a weak provider response fails loudly as ai_failed rather than being padded with local filler; and API keys travel only as session-scoped request headers, never into the database or the logs.
03
Composants
The system is built from nine components. Each is documented the same way: why it exists, how it is built, what constrains it, and what it trades away.
›C1Brief composer & entity context
- Pourquoi il existe
- A software company and a local furniture retailer should never get the same kind of names. What you are naming is the primary brand-context signal, so the entity picker leads the form.
- Architecture
- An entity picker with fourteen types plus a problem textarea; optional brand preferences (philosophy, language, audience, liked brands, avoid list) and an advanced drawer (length, count, TLDs, BYOK). The server normalizes entity, style, and language, then infers category, keywords, and tone into a composed brand brief.
- Contraintes
- Entity and problem are required. Entity rules drive max length, spaces, and how the LLM prompt is framed. Preferences must change the output, not just decorate the brief.
- Cas limites
- Legacy aliases normalize (brandable becomes invented, market codes become languages). An empty problem with only a brand brief still composes. A custom Other language passes through.
- Compromis
- Progressive disclosure keeps the first action one click; more control lives behind drawers so the composer stays a single composition.
›C2Naming philosophies
- Pourquoi il existe
- One algorithm with a style slider collapses to the same invented names. Philosophies are distinct strategies, not weights on one method.
- Architecture
- Four philosophies: Invented (Figma and Canva energy), Real Words (Stripe, Cursor, Ramp), Compound (Basecamp, Mailchimp, GitHub), and Descriptive (SurveyMonkey and PayPal, still ownable). Style quotas drive the local generator; LLM prompts are opinionated per philosophy, with positive and negative examples, hard avoid lists, and liked-brand patterns rather than the brands themselves.
- Contraintes
- Real-word candidates must pass curated lexicon checks. Soft inventeds are banned on the AI path. Entity rules can override length and spacing.
- Cas limites
- An AI asked for inventeds that returns product phrases gets culled by the gates. A compound that is not two recognizable halves fails the accept rules.
- Compromis
- Stricter philosophies mean fewer names. Preferred over a long list of sludge.
›C3Generation pipeline
- Pourquoi il existe
- Orchestrates create, generate, and checks as a status machine the UI can step through honestly.
- Architecture
- Load the favorite-signal and preference profiles; run local generation or the LLM, exclusively; filter every name, ban soft inventeds, apply avoid tokens, and score with a tier bonus for the provider's own top picks; cull to a shortlist of 12 to 24; radio-test the top names; persist candidates with safe LLM metadata only, provider, model, and counts, never keys.
- Contrat d'API
// stepped UI path: one run row, separate stages POST /api/namegen/runs { run_pipeline: false } POST /api/namegen/runs/:id/generate + X-LLM-* headers POST /api/namegen/runs/:id/check-domains · check-conflicts · check-trademarks GET /api/namegen/runs/:id → results DTO
- Cas limites
- Provider JSON that will not parse returns ai_failed, with no silent fallback. A quality cull that would empty the set falls back to keeping the best of what passed the structural filter. Favorites can be toggled while a run is open.
- Compromis
- Stepped calls cost more round trips than a one-shot pipeline, and buy honest progress and partial recovery.
›C4Local name generator
- Pourquoi il existe
- A usable product with AI off: free, deterministic, offline-capable generation.
- Architecture
- Six methods (descriptive, compound, invented, evocative, suggestive, real word) driven by curated YAML assets: a vocabulary, a brand lexicon, a real-word lexicon, and syllable tables. Language preferences bend phonotactics and endings.
- Contraintes
- Must respect entity max length and philosophy quotas, and must never emit blocklisted or unpronounceable strings.
- Cas limites
- Exhausted lexicon uniqueness, over-long compounds, and category stems that turn descriptive mode into SEO sludge.
- Compromis
- Curated lexicons beat open-ended invented generation for commercial feel, and they bound creativity to what is in the lists.
›C5BYOK LLM layer
- Pourquoi il existe
- Optional AI lift without the host paying inference or storing user keys.
- Architecture
- The key lives in sessionStorage and travels only as request headers on the generate call. The server prefers the request key; host keys are honored only when a private-deploy flag is set, and the public default is off. Providers: Anthropic, OpenAI-compatible, xAI, and Gemini. The prompt asks for structured JSON, naming directions plus names with tiers, and the AI target is capped per run.
- Contraintes
- Public deploys carry no server keys. Keys never touch query strings, logs, or the database. AI on means no local filler.
- Cas limites
- A key with no provider, an invalid model override, provider rate limits, malformed JSON, and the batch where every AI name fails the gates.
- Compromis
- Ephemeral headers are simple and honest: the key exists for that tab session, by design, and there is no multi-user key vault to secure.
›C6Quality gates
- Pourquoi il existe
- The product is a shortlist, not a brainstorm dump. Soft inventeds fail the commercial test: would you say we use this at work every day?
- Architecture
- Four gates in series. A structural filter checks length, blocklist, consonant clusters, and syllable limits. A soft-invented ban holds a banned set, product endings like ify and bot, and soft Latinate tails, with a small classical whitelist. A brand-quality check applies method-specific accept rules. A weighted scorer applies philosophy overrides, preference penalties and bonuses, and a favorite-affinity bonus.
- Contraintes
- Gates run on both the local and AI paths. Credibility floors are stricter for the invented and real-word styles.
- Cas limites
- Odd but good coinages can be over-rejected; real adverbs that happen to end in ly; multi-word names that need higher syllable limits.
- Compromis
- Aggressive bans improve first-impression quality and discard some creative edges. The right trade for a founder-facing shortlist.
›C7Radio, domains, conflict, trademarks
- Pourquoi il existe
- A pretty name that fails spelling, the dot-com check, or a famous mark is not a shortlist candidate.
- Architecture
- Radio is a heuristic spell-after-hearing score with alternate spellings and an explanation. Domains use RDAP only, which is free, with capped concurrency and a week-long cache. Conflict is a deterministic blocklist over exact matches and brand stems. Trademark screening runs exact, spelling, and phonetic matching with Nice-class weighting from the brief, and reads out as low, medium, or high risk. The default dataset is a labeled sample; a real USPTO import is an operator option.
- Cas limites
- RDAP timeouts surface as an error status rather than a fake available. Premium domain hints, dead versus live marks, and same-industry versus unrelated classes.
- Compromis
- Free RDAP and a labeled sample dataset keep the public tool zero-cost. Every check is informational: it is a filter, never registrar truth and never legal advice.
›C8Persistence & favorite learning
- Pourquoi il existe
- Sessions, export, and soft learning from starring, without a heavy data platform.
- Architecture
- SQLite via better-sqlite3: a runs table (brief, settings, status), candidates (scores, domains, conflict, radio, trademark, favorite), a domain cache, and favorite signals that store only anonymized name shape, length, ending, and style, feeding an affinity bonus on later runs.
- Contraintes
- No API keys in the database, ever. The hosting filesystem is ephemeral without a volume, so runs do not survive deploys unless the database path points at persistent storage.
- Cas limites
- Uniqueness per run and name, migration columns for the radio and trademark fields, and favorite-toggle races.
- Compromis
- SQLite is enough for a personal-site tool; multi-instance hosting would need an external store and a shared rate limit.
›C9On-site Nitro port & open-source split
- Pourquoi il existe
- The planned names subdomain never got DNS, and BYOK removed the cost reason to stay separate. The real barrier was stack isolation, Python versus Nuxt, and a TypeScript port dissolved it.
- Architecture
- A faithful port of the Python services into Nitro server utilities plus a Vue UI at /apps/namegen, with the YAML lexicons shipped as server assets. The apps shelf launches the on-site route; View Source points at the public Python repository, which stays the MIT reference and self-host path.
- Compromis
- Dual maintenance of a TypeScript production app and a Python reference, against one deploy and one domain. On-site TypeScript won for production UX and operations.
04
Rendu visuel
The exhibits this record will carry, captured from the live tool. Every frame below is a slot awaiting a real screenshot; nothing here is mocked.
The composer
Entity, problem, and one Generate action; preferences stay collapsed until asked for.
Screenshot slot · composer at rest
Naming philosophy control
Invented, Real Words, Compound, Descriptive, each with its hint copy.
Screenshot slot · philosophy segmented control
BYOK advanced drawer
AI on, provider selected, key field, and the status chip.
Screenshot slot · BYOK drawer with AI on
Progress states
Generating, then checking domains, conflicts, and trademarks, as separate honest stages.
Screenshot slot · stepped progress
Direction cards and results table
Favorites, source badges for AI and Local, scores, domain pills, trademark risk, and radio.
Screenshot slot · results table
Usable-only filter and CSV export
The shortlist posture: cut to what survives, then take it with you.
Screenshot slot · filter + export
Sample trademark disclaimer
The honesty line: the demo dataset is a sample, not a USPTO search.
Screenshot slot · trademark disclaimer
05
Impact
What the system changed, by audience.
- Business
- A public naming utility ships on the personal site with no second SaaS bill for inference.
- The reference implementation is open source under MIT while production runs on-site.
- Client
- A problem-first brief instead of describe your startup.
- Philosophies that actually change the shape of the names.
- Domains and trademark risk on the same shortlist view.
- Opérations
- One deploy with the site and no orphan subdomain.
- BYOK means abuse cost is mostly CPU and RDAP calls, not API spend.
- Ingénierie
- Hard quality gates as product behavior, not prompt hope.
- An AI-only invariant whenever BYOK is enabled.
- A clear split between the live TypeScript app and the Python reference.
- Échelle
- Shortlists are intentionally small, 12 to 24 names per run.
- The API is rate limited per IP and RDAP concurrency is capped.
06
Documents techniques
Documents this record seeds. Each becomes a dated entry as it is written.
—DecisionWhy BYOK, not host-paid AIPublic naming tools get scraped; user keys keep cost and liability with the user.—DecisionPhilosophies are not a style sliderDistinct method quotas and prompts beat one generator with adjectives.—NoteSoft-invented bans as product qualityNames like Velora pass phonotactics and fail the commercial sentence test.—DecisionAI on means AI onlyLocal filler after a weak LLM call teaches users to distrust both.—DecisionRetiring the names subdomainPlanned DNS never landed; the Nitro port puts the app at /apps/namegen.—NoteRDAP and sample-trademark honestyFree checks are useful filters, not registrar or USPTO truth, and the UI says so.—Long-formPorting a FastAPI naming engine to NitroA one-to-one service map, YAML server assets, synchronous SQLite, and stepped client orchestration.
07
Étude de cas
The complete arc, compressed.
- Problème
- Founders drown in bad name generators: keyword piles, soft inventeds, and tools that hide an API meter behind the word free.
- Objectif
- A shortlist of names worth building around, shaped by what you are naming and the problem you solve, with domain and trademark context and optional AI the host does not pay for.
- Contraintes
- No host LLM keys on the public deploy; deterministic quality gates; a free domain path via RDAP; trademark screening that never pretends to be legal clearance; and no dependency on an unpublished subdomain.
- Approche
- A problem-and-entity brief, philosophy-specific generation, local or BYOK, hard quality gates, then radio, domain, conflict, and trademark checks into one comparison table. Later, port the Python engine to Nitro and TypeScript and host it on-site.
- Architecture
- Vue client, Nitro API, a stepped pipeline over SQLite and YAML lexicons; keys live only in the session and in request headers.
- Compromis
- Aggressive soft-invented rejection, AI-only generation when enabled, a sample trademark dataset by default, a dual codebase, and ephemeral SQLite without a volume.
- Résultat
- The pipeline runs in production at /apps/namegen. The apps shelf launches it in-site, the MIT Python repository remains the reference and self-host path, and the dead subdomain plan is retired.
- Enseignements
- Quality is a gate stack, not a better prompt.
- Free AI on a public tool is a cost center and an abuse magnet; BYOK is the product decision.
- A second deploy for DNS aesthetics is not free; if the site can host it, host it.
- When AI is on, do not dilute failure with local filler.
- Suite
- A persistent volume or external database so runs survive deploys, a documented USPTO dataset path for operators, and either shared fixtures that keep the Python and TypeScript engines aligned or a formal freeze of Python as the reference.