Truth Geomancer

An MVP web app for Ilm al-Raml (Arabic geomancy / "the science of the sand") — a manuscript marketplace and reader paired with an interactive chart-casting tool. Built as a sibling app to Deftere, reusing its mobile-shell layout pattern (centered column, sticky bottom nav, card-based dashboard) with an entirely new visual identity ("sand and ink": deep ink brown, sand gold, clay orange) and a domain the source app doesn't touch.

Stack: Next.js 14 (App Router) + TypeScript + Tailwind. No external state/UI libraries — everything is hand-rolled React + Tailwind, matching the sibling app's approach.

What's here (MVP scope)

• Dashboard (/) — hero card, three quick actions (Cast / Library / My Star), and a horizontally-scrolling manuscript strip.
• Cast a Chart (/raml) — the core feature. All 16 lines are tapped on one screen: The Four Draws, each broken into its Fire/Air/Water/Earth lines (the classical top-to-bottom element order, which also matches how Kanzul Mikban's own methods isolate "the water element of h7" etc.) — tap each line freely and independently, in any order, until it feels right; a live figure preview appears on each Draw once its 4 lines are done, and "Cast Reading" unlocks once all 16 are. From the 4 Draws (Mothers) the app derives the 4 Daughters, 4 Nieces, 2 Witnesses, the Judge and the Reconciler — the full classical 16-house shield chart — and presents results across tabs: Overview (Judge/Self/Wealth/ Illness), Full Chart (all 16 houses), My Star (Buruji via 3 traditional methods, spiritual-strength check, root-cause check), Sadaqah (the offering indicated by the chart), and Your Reading when a specific question was picked (see Casting types below). Every completed casting is saved automatically (see Persistence below).
• Past Castings (/raml/history) — every chart ever cast on the device, newest first, each showing its question, date, and Judge figure. Tap one to reopen the full result view exactly as it was; delete individual castings from there or from the detail page. A "Recent castings" preview also surfaces the last 3 right on the casting screen, and the My Star tab links out to the full list.
• Library (/books) — marketplace-style catalog, both books fully readable in-app. The Master of Geomancy, Vol. 1 covers the fundamentals chapter by chapter. Kanzul Mikban is the advanced companion — a manuscript notebook of 153 question-specific reading methods (travel, money, marriage, pregnancy, sickness, lost things, court cases, dreams, and much more), transcribed in full with a filterable table of contents. Each book reads as one continuous vertical document (/books/[id]/read) — chapters are stacked <section>s in one scrollable page, not a page-per-chapter carousel, so reading on is exactly "keep scrolling down"; the contents list, search results, and the casting flow's "Open full chapter" links all jump straight to a chapter via a plain #id anchor rather than a page navigation. No payment processor is wired up yet (Phase 1, matching the sibling app's manual-confirmation approach) — the "Start Reading" flow is fully live, purchase is not.
• Casting types (/raml, "What is this reading for?") — before casting, the user browses ten broad categories (Love & Couple, Money & Possessions, Work & Success, Health & Hardships, Family & Loved Ones, Travel & Change, Legal & Conflict, Lost & Stolen Things, Fate & Timing, Dreams) down to a specific question, or searches all 153 questions directly via the "All (A-Z)" toggle; a "Recent" section resurfaces the last few picked (lib/raml/recentIntentions.ts). Every one of Kanzul Mikban's 153 chapters is reachable this way — content/intentions.ts maps each chapter to exactly one selectable question under one category, generated from the book's own chapter titles rather than a hand- picked subset. After casting, a "Your Reading" tab shows that chapter's result: for a growing set of chapters the method now runs automatically end-to-end (houses picked off the chart, combined per the book's rule, and the resulting figure's verdict shown directly); for the rest, the chapter's exact method text is shown with every house it mentions (h1, h7, ...) resolved against the real figure the user's own chart landed on there — see "On not inventing verdicts" and "The automatic interpretation engine" below for how much of that is now fully automatic and why the rest isn't yet.

The geomancy system

This isn't the Latin-named 16-figure system (Via, Populus, Fortuna...). The source manuscript teaches a West African Islamic tradition (Bazdaaho arrangement, attributed to Sheikh Abu Abdullah az-Zanati) where the same 16 classical binary figures carry different names — Yussif, Adam, Mahadi, Iddris, Ibrahim, Issah, Umar, Ayuba, Kalla Allahu, Sulemana, Ali, Nuhu, Hassan & Hussein, Yunus, Usman, Musah — each tied to one of 4 elements (Fire, Air, Water, Sand), with its own House 6 (illness) and House 2 (wealth) meaning and its own sadaqah (charitable remedy). All 16 dot-patterns were decoded from the source PDF via image analysis and cross-validated against the book's own element groupings (all 16 patterns accounted for exactly once, zero conflicts) — see content/stars.ts.

The casting algorithm (lib/raml/casting.ts) implements the classical shield-chart derivation: Daughters read across the Mothers' lines; Nieces, Witnesses, the Judge and the Reconciler are built by the book's own combination rule (same dot-count -> double, different -> single). This was independently verified against on-screen results during testing (see conversation) — every derived house matched hand recomputation.

This is the beginning of the README. Read the rest at the original. Read the full README ↗