How GeMater works

This doc maps the theory from the rest of /docs onto the code in this repo, and describes what we ship today vs. what's on the roadmap.

The two surfaces

Calculator (/)

Type a word or phrase. The page calls calculate(text) from packages/engine/src/gematria.ts and renders one card per method:

• Simple — English Ordinal (A=1 … Z=26)
• English — English Sumerian (Simple × 6)
• Jewish — Hebrew Standard, transliterated to A–Z

Each card shows:

• The per-letter breakdown
• The running total
• The digital root of the total, plus its full reduction chain (e.g. 611 → 8, 666 → 18 → 9)
• A method-coloured "metal" treatment (gold / silver / bronze)

The engine is pure and dependency-free; everything visual is in @gemater/components.

Name generator (/generator)

Submit a job: "give me names like X with the 3·6·9 property." The flow:

1. apps/web/app/api/jobs/route.ts enqueues a BullMQ job on Redis.
2. services/worker consumes the queue. It optionally calls OpenRouter to expand a seed corpus (graceful fallback: use the bundled corpus).
3. packages/engine/src/namegen/ runs a character-level trigram Markov chain over the corpus and emits candidate names.
4. packages/engine/src/namegen/constraint.ts filters them: only names whose digital root is in {3, 6, 9} for all three methods survive (≈ 1 in 9 hit rate).
5. The worker enriches survivors with .com availability via @gemater/domain-check (RDAP, no API key).
6. Worker writes history to Postgres if the job is from a signed-in user, then returns the job result.
7. The client polls /api/jobs/[id] and renders NameResultCards.

If the user is signed in, they can save names into collections (default "Favorites"); collections live at /saved and /saved/[id].

Why the 3·6·9 filter is non-arbitrary

See 03-the-3-6-9-pattern.md for the math. The short version: digital root ∈ {3, 6, 9} ⇔ divisible by 3. Because our English method is Simple × 6, the English constraint is always satisfied — the real gate is Simple % 3 == 0 AND Jewish % 3 == 0, a ~1-in-9 filter on random pronounceable names.

The visual payoff: every name that survives gets a stamped-metal medallion (RootSeal) with its root number. The medallion only feels earned because the math is non-trivial.

What we ship today vs. the broader tradition

Capability	Today	Notes
English Ordinal	✅ ("Simple")	The cleanest cipher
English Sumerian (× 6)	✅ ("English")	Popularised by decoder community
Hebrew Standard (transliterated)	✅ ("Jewish")	Mispar Hechrachi mapped onto A–Z
Atbash	⏳ planned	Substitution-then-sum
English Reduction	⏳ planned	Digital-root per letter, summed
Reverse Ordinal	⏳ planned	27 − ordinal per letter
Mispar Gadol (with finals)	❌ not planned in v1	Requires Hebrew script input
Mispar Katan / Siduri (Hebrew)	❌ not planned in v1	Same
Greek isopsephy	❌ not planned in v1	Adjacent feature
Arabic abjad	❌ not planned in v1	Adjacent feature
Hebrew-script input (RTL keyboard)	❌ not planned in v1	Large UI/typography lift
Word/phrase match list	⏳ roadmap	See "Roadmap" below
Daily 3·6·9 phrase + share card	⏳ roadmap	See "Roadmap" below
.com availability per name	✅	RDAP via @gemater/domain-check
Saved collections (per user)	✅	Postgres via @gemater/database
Background generation (microservice)	✅	BullMQ + Redis

Architecture in one paragraph

GeMater is an npm-workspaces monorepo with three runtime artefacts: the Next.js app (apps/web), the BullMQ worker (services/worker), and the shared engine + types + components (packages/*). The calculator runs client-side off @gemater/engine. The generator submits jobs through apps/web/lib/queue.ts to a dedicated gemater-redis container in production; the worker consumes them, runs the same engine + the namegen constraint, enriches results with RDAP, and persists history through @gemater/database. Auth is optional (better-auth: email/password, Google OAuth, One Tap) — calculator and generator both work fully anonymously; signing in adds collections + persistent history.

Full code-level architecture lives in CLAUDE.md.

Roadmap

These are the next features the docs-driven research surfaced. Each gets its own plan when scoped.

1. Expand the cipher registry (in-progress)

Add Atbash, English Reduction, Reverse Ordinal to GEMATRIA_METHODS. Each is a one-entry registry add. The namegen gains a "Strict mode" that requires the 3·6·9 property under all six methods (stricter filter, rarer + more striking results); the default mode keeps the classic three for backwards compatibility.

2. Word / phrase match list

Given a phrase and a method, show other words/phrases with the same total. This is the hallmark feature of decoder-community calculators (Gematrinator). Requires a curated English wordlist (e.g. SCOWL) and a small "famous phrases" set. Could reuse OpenRouter to surface semantic clusters among matches.

Surface: a new "Matches" tab on each method's card on /.

3. Daily 3·6·9 phrase + share card

A scheduled GitHub Action runs the namegen once a day, picks a featured 3·6·9 phrase, and posts it to a new /daily route. The route renders a 1200×630 Open Graph image via Next's dynamic OG support, making each phrase trivially shareable to social. Content-engine SEO play that compounds over months.

4. Hebrew-script input (longer-term)

Let the user type Hebrew directly and pick Mispar Hechrachi, Gadol, Katan, or Siduri. Requires RTL keyboard handling, Hebrew font loading, and an honest Hebrew-letter engine (not the A–Z transliteration we use today). This moves us toward TorahCalc's positioning.