Built-To-Kanso, Architecture Overview

01 / Surfaces

Four routes and a marketing page.

The product app lives under app/ as a Next.js 16.2 App Router. The marketing landing is plain HTML at the repo root, served standalone.

/ App entry Next.js home route. Registers the studio shell and hands off to Stage 1.

/threshold Stage 1, Threshold Onboarding: pick a curated HDB template, set door-facing on the compass, choose a floor tier, pick a scenario. Reading panel fills as inputs land.

/bones Stage 2, Bones Plan reading. Asking Points (max three), Damp Risk band, Black-state HDB / SCDF protection, token studio, Ghost Futures preview, Kanso Reserve meter, Anti-Cure recommendation, House Changelog.

/methodology Methodology Public evidence ladder, cultural framing, audit gap, hard rules. The page that earns the cultural reviewer’s trust.

index.html Marketing landing Standalone HTML at repo root. Plain HTML and CSS, no framework, no JS bundle.

02 / Data flow

Three inputs, four compute lanes, four outputs.

Plan geometry is the source of truth. AI never alters compliance geometry, walls, streamlines, token legality, Damp Risk, or Black-state decisions. Three.js renders are reference imagery only.

Plan geometry is the only source of compliance truth. The Tier 4 LBM render and the OpenAI sketch pipeline both feed visual layers, never the readings. If WebGPU fails, the prebaked LBM result serves silently; the fallback never surfaces to the homeowner.

      
Lane 1, Scout & Rules
The lane that says what the home is asking. Geometry validates first, then Scout prioritises, then Rules score.
geometry/validation.ts
scout/priority.ts
rules/openingArea, kansoReserve, antiCure
rules/downwind, glow, quiet, ghostFutures, tokens

          Output
          Asking Points, Damp Risk band, Anti-Cure, Changelog
        


      
Lane 2, Tier 4 Simulation
D2Q9 LBM at 256 by 256. WebGPU is canonical, prebaked CPU result serves silently if GPU fails.
lbm/gpuSolver.ts (WebGPURenderer)
lbm/solver.ts (CPU reference)
simulation/tier4.ts, lbm/prebake.ts
materials/* (5 presets)

          Output
          SVG streamlines, atmospheric renders
        


      
Lane 3, Sketch Pipeline
Reference imagery for hero, plan, life, and wind surfaces. Deterministic SVG is the always-available floor.
anchors/lifeAnchor.ts (Three.js seam)
openai/client.ts, cache.ts, sketches.ts
openai/fallbackSvg.ts (deterministic floor)
storage/sketchCache.ts (R2 seam)

          Output
          Hero / Plan / Life / Wind sketches
        


      
Lane 4, Resonance Hours
The lane that stays with the home. When real wind aligns with the unit’s corridor, one quiet push.
resonance/corridor.ts, floorTier.ts
resonance/nea.ts (station match)
resonance/sleepSuppress.ts, cache.ts
resonance/dispatch.ts (web-push, VAPID)

          Output
          One push: “Your home is breathing right now.”
        

    

03 / Evidence ladder

Five tiers, plus a label that is not a tier.

Every reading the homeowner sees declares which tier produced it. cultural_framing is intentionally not part of the evidence enum (Hard Rule 17). It carries voice, never a physical claim.

01 official_constraint HDB / SCDF Black-state element. Household shelter, structural wall, wet zone, pipeshaft opening. Hard-blocked with Golden Failure copy.

02 template_fact Curated archetype geometry. Rooms, openings, fixed elements, openingAreaPct. Three templates curated by hand.

03 heuristic_estimate Layout-based design rule. Damp Risk, west-sun heat path, opening-area badge, downwind check, command-position. Each maps to a measurable physical claim.

04 weather_context NEA outdoor station data. Resonance Hours, Monsoon Turn. Real wind, real time, real station bearing. Never simulated.

05 prototype_visualisation Live LBM, sketches, material renders. Reference imagery only. Compliance is read from plan-geometry.json, not from this layer.

– cultural_framing Voice, not evidence. Carries kansō / Form-School framing. Never appears on a reading that makes a physical claim. Hard Rule 17.

04 / API contracts

Fourteen endpoints under app/api.

Server logic is deterministic and isolated from the UI. AI never alters compliance geometry, walls, streamlines, token legality, Damp Risk, or Black-state decisions.

Method	Path	Purpose
GET	/api/templates/[id]/geometry	Validated template geometry. Compliance source of truth.
POST	/api/scout	Max-three Asking Points, opening-area badge, banded Damp Risk (Clear / Watch / High).
POST	/api/tokens/validate	Token legality and Golden Failure copy on Black-state collisions.
POST	/api/ghost-futures	Pre-placement Breath and Damp deltas, evaluated against current placements.
POST	/api/changelog	Short homeowner receipt after placements. Reads as receipt, not patch note.
POST	/api/simulation	Deterministic Tier 4 field. CPU reference / prebake source metadata. Weather Trial conditions.
POST	/api/resonance/check	Current wind alignment against the unit’s optimal corridor. Sender readiness.
GET / POST	/api/resonance/dispatch	Dry-run or scheduled Resonance push through an injectable sender.
POST	/api/resonance/subscribe	In-memory push subscription registration.
GET	/api/resonance/vapid	Public VAPID key, when configured.
GET	/api/sketches/hero	Prebaked or generated hero image.
POST	/api/sketches/plan	Deterministic SVG fallback. Cached / generated PNG when configured.
POST	/api/sketches/life	Three.js anchor PNG seam. Deterministic SVG fallback. Optional OpenAI materialisation.
POST	/api/sketches/wind	Deterministic Wind Sketch composition. Streamlines never go through GPT image generation.

05 / Stack

Pinned for security, not for vanity.

Cloudflare advisory 2026-05-06 patched three additional CVEs in RSC and Next.js. The pins below are the minimum safe versions. Earlier minors of React 19 and Next 16 are insecure; do not regress.

Frontend

Next.js 16.2.6 React 19.2.6 react-server-dom 19.2.6 App Router Zustand shadcn/ui framer-motion

Compute / 3D

Three.js 0.184.0 WebGPURenderer WebGL2 fallback D2Q9 LBM, 256×256 Deterministic SVG

Cloud / Seams

Cloudflare R2 (cache) NEA wind API OpenAI (sketches) web-push, VAPID Service Worker

Type, voice, tests

Cormorant Garamond Inter JetBrains Mono Noto Serif SC (Phase 2) Playwright e2e WCAG 2.2 AA

06 / Positioning

Form-school, with instruments.

The cultural register the architecture serves. Every claim is physical, every voice is calm, and the school we work in is named correctly so the cultural reviewer stays in the room.

Form-School (形势派) is already environmental.

Form-School reads the actual ground: wind paths, water drainage, room geometry, sightlines, terrain. The brief picks it precisely because it is not the metaphysical, Period-9, or luopan-chart lane.

Built-To-Kanso is not “wisdom distilled from superstition.” That frame mislabels the school we work in and tells the cultural reviewer we don’t know which school we’re in. Form-School was never the superstition.

And the Nanyang positioning works by being something else, not by arguing against mainland feng shui. “Wisdom, not superstition” would re-center the rival, the way “real coffee (unlike Starbucks)” makes Starbucks the brand’s job. Quietly being a wind-aware studio for HDB homes does the inversion without naming it.

Etymology disclosure, non-negotiable

Aesthetic kansō ≠ kasō

School Form (形势派) ≠ Compass / Period-9

Latitude 1.35° N ≠ 22 to 40° N

These three lines, in some form, must appear on every surface that names the tradition. Cultural-credibility critique is a real risk per PRODUCT.md, not a hypothetical.

Built-To-kansō

Four routes and a marketing page.

Three inputs, four compute lanes, four outputs.

Lane 1, Scout & Rules

Lane 2, Tier 4 Simulation

Lane 3, Sketch Pipeline

Lane 4, Resonance Hours

Five tiers, plus a label that is not a tier.

Fourteen endpoints under app/api.

Pinned for security, not for vanity.

Form-school, with instruments.

The product reports. It does not defend.