FengShui Blueprint
Engineering-grade feng-shui assessment for Toronto buildings. Form School + Compass School rules engine fused with an engineering-blueprint UI — classical citations, deterministic scoring, ~2s edge-served reports.
Context
Online feng-shui sits in two camps. There’s the gilt-scroll, magenta-ink, dragon-motif category that reads like a fortune-teller’s pamphlet — interpretation by vibes, no traceability. And there’s the academic literature on classical geomancy that nobody can actually run a building through. Nothing sits in the middle.
FengShui Blueprint is the middle: input a Toronto address + floor + facing + unit size (or tap the map). In about two seconds you get a CAD-styled report — composite score, five dimensional scores (qi flow, wealth, health, career, sha), a master’s annotation citing classical sources, a surrounding-feature inventory pulled from real GIS, and a static map of the eight nearest features.
Positioning is deliberate: entertainment + a share-worthy artifact, the way a horoscope is — but engineered. Not divination, not advisory.
Approach
The rules engine is a dependency-free TypeScript package
packages/rules-toronto is pure functions with no I/O. It takes a normalized “site reading” — facing in degrees, floor, surrounding features within 2km — and emits dimensional scores + a composite + a list of detected defects. Same input always yields the same scores. 55 Vitest tests cover 6 sha detectors, 24 facing wedges, and 5 element interactions.
That hard separation is what keeps the project from collapsing into “an LLM emits feng-shui prose.” The narrator only describes what the engine computed.
Form School + Compass School fused
v0.2.0 wires both traditions into one pipeline:
- Orientation — 24 mountains (二十四山, 15° each) → bagua trigram → element + polarity → baseline multiplier
- Floor → five-elements — Hetu numerology (河图) harmonization
- Sha detection — six classical forms (road-thrust / reverse-bow / white-tiger-rising / vermilion-bird-pressing / black-tortoise-empty / yin-accumulation)
- Four-emblem analysis — vermilion-bird-with-water, black-tortoise-supported, dragon-tiger balance
- Surrounding features × five-elements harmony — distance-banded weights for lakes, rivers, parks, subway, hospitals, landmarks, tall buildings, highways, cemeteries, schools
- Floor-height correction
Every module cites where in the canon it came from — 《青囊奥语》, 《葬书》, 《阳宅十书》, 《河图》, 《雪心赋》 — the citations are the point. It makes the score legible.
Engineering blueprint as the visual identity
Bone-paper background, deep ink-blue type, monospace numerics, drafting frames (DRAWING NO. / SHEET / CONFIDENCE). The aesthetic is a deliberate distance from the category’s visual cliché. The report reads like a drafting sheet for a building’s qi, not a fortune-teller’s pamphlet.
Edge-served, single-key Google Maps integration
A Hono worker on Cloudflare Workers handles geocoding (zh-CN), reverse geocoding, Places lookups, and Static Maps composition behind one Google key. KV caches results; a daily quota guard prevents an over-curious user from burning the key budget. D1 archives every assessment under an 8-character Crockford base32 short id. R2 is reserved for the upcoming PNG share card.
The whole web app is Next.js 15 + React 19 deployed to Workers via @opennextjs/cloudflare — no Pages, no separate host.
What Makes It Different
| Most online feng-shui sites | FengShui Blueprint |
|---|---|
| Generic bagua + horoscope-style “your element is…” | Site-specific report from real address + GIS data |
| One-line interpretation | Five dimensional scores + composite + cited advice |
| Static text | Map-driven — tap anywhere in Toronto |
| Gilt scroll / magenta ink visual cliché | Engineering blueprint drafting frames, monospace, bone paper |
| No traceability | Every score points to a classical citation + a deterministic rule |
| Subjective hand-wave | Rules engine with 55 tests — pure functions, identical inputs → identical scores |
Results & What I’m Learning
v0.2.0 live at fengshui-web.pp-account.workers.dev. Plan 5 land-parcel assessment + draggable plot toolbar + address autocomplete is the latest pass. Plan 2 (LLM-augmented narration + PNG share card via Cloudflare Browser Rendering + short links) is in flight.
Two non-obvious lessons so far:
Citing the canon is the load-bearing UX choice. People don’t trust feng-shui apps because there’s no traceability. The moment every advisory line is footnoted to 《阳宅十书》 or 《青囊奥语》, the report reads less like “an algorithm guessing” and more like “a draftsman reading a real reference.” The classical sources aren’t decoration — they’re how the product earns the right to a score.
Keeping the rules engine dependency-free was a multiplier. I almost let it import dayjs for a one-off date thing. Resisting that kept the package portable across web + worker + future LLM agent — and made the 55-test suite feasible. The narrator is allowed to be messy; the engine isn’t.
Tech Stack & Links
Frontend: Next.js 15 (App Router) · React 19 · TypeScript (strict) · Tailwind · Leaflet + react-leaflet + CartoDB Light tiles · Zod
Edge API: Hono on Cloudflare Workers · Wrangler 4 · D1 (assessment archive) · KV (geocode cache + daily Maps quota guard) · R2 (PNG share, reserved)
Rules engine: packages/rules-toronto — pure functions, dependency-free, 55 Vitest tests
External: Google Maps Geocoding (zh-CN) / Reverse Geocoding / Places / Static Maps
Deploy: @opennextjs/cloudflare for Next.js 15 → Workers
Live: fengshui-web.pp-account.workers.dev
Public overview: github.com/YSKM523/fengshui-blueprint-overview (private source kept separate)