Lead Web Engineer · Technical Vision & Live Monorepo

Systems over screens. Guardrails for speed.

A pragmatic architectural blueprint for unifying Genki's organic web surfaces, phasing out Next.js cleanly into Astro static edge delivery and Vite + React Router member portals, and empowering Marketing, Design, and Ops to ship safely with AI coding agents inside a deterministic pnpm monorepo.

Explore Interactive Blueprints Inspect Monorepo & CLAUDE.md on GitHub ↗
0 KBDefault Astro JS shipped on content & SEO pages
100%SCSS design-token enforcement via CI guardrails
pnpmUnified @genki/ui + apps monorepo workspace
4–5hDaily synchronous BRT ↔ CET overlap with Cologne
01 · Web Consolidation & Migration

Consolidating Organic Web Sprawl into Astro + React Router

Explore the current pain points, the target split between public SEO surfaces and the authenticated Wave Claims portal, and the 3-phase Cloudflare strangler cutover plan.

Purpose-built surfaces unified by @genki/ui SCSS tokens and CLAUDE.md guardrails

Public/SEO surfaces deploy on Astro + Cloudflare with 0 KB default JS; the authenticated Member & Claim OS Portal runs on Vite + React + React Router + GraphQL.

0 KBDefault Astro Page JS
100% SCSS VarsDesign Token Binding
Vite + React RouterMember & Claim OS Stack
Public & SEO Surfaces
0 KB JS Default

Astro + Cloudflare Edge (0 KB Default JS)

genki.world and guide.genki.world compile to static HTML at the Cloudflare edge, hydrating React 19 islands (client:visible) strictly where stateful calculators are needed.

  • Instant LCP/INP worldwide for international travelers and search crawlers
  • Marketing & Design compose campaign pages safely from @genki/ui blocks
Authenticated Portal & Claim OS
Member SPA

Vite + React 19 + React Router + GraphQL

Authenticated member accounts and Wave Claims (Claim OS) run on a crisp Vite + React Router SPA with instant HMR and strictly typed GraphQL operations.

  • Zero SSR overhead behind authentication; clean client-side routing
  • Deterministic multi-step workflows for medical invoice & claim pre-flight
Shared Workspace Package
CODEOWNERS

Figma-Synced @genki/ui + CLAUDE.md Gates

packages/ui exports semantic --genki-* SCSS Modules and typed React primitives protected by CODEOWNERS, Biome, and verify-guardrails.mjs on every PR.

  • Zero Tailwind clutter; 100% scoped *.module.scss bound to var(--genki-*)
  • Non-engineers ship autonomously with AI agents without risking regressions
$pnpm check:all --filter=@genki/monorepo
EXIT 0 · TARGET VERIFIED
  • [PASS]
    Astro Public & Guide Surface (Cloudflare Pages)0 KB baseline JS; selective client:visible React 19 islands
    0 KB Base JS
  • [PASS]
    Member & Claim OS Portal (Vite + React Router + GraphQL)Decoupled SPA build with typed GraphQL schema operations
    SPA Isolated
  • [PASS]
    Figma-Synced @genki/ui + CLAUDE.md Guardrails100% var(--genki-*) SCSS enforcement + CODEOWNERS active
    0 Violations
Verified: Astro static edge + Vite/React Router portal sharing @genki/ui with 0 violations.
02 · Enabling Non-Engineers

Safe AI-Agentic Contribution Simulator (CLAUDE.md + CODEOWNERS)

Simulate how Marketing, Operations, and Design ship changes using Claude Code while deterministic guardrails block raw hex drift, reject unsafe DOM injection, and escalate core design-token edits to Lead Web Engineer review.

Actor: Operations Coordinator + Uncalibrated AI Promptapps/site/src/components/PromoBanner.tsx + PromoBanner.module.scss

Deterministic CI rejection catches off-brand hex literals and XSS injection in < 50ms

An uncalibrated prompt generates hardcoded hex colors in SCSS and raw HTML injection via dangerouslySetInnerHTML. verify-guardrails.mjs and Biome immediately fail the check and feed exact line-level remediation instructions back to the coding agent.

01 · Hallucinated Agent Diff
2 Violations

Raw Hex Color & Raw HTML Injection Attempted

The agent bypassed @genki/ui tokens with a hardcoded hex color in PromoBanner.module.scss and rendered unsanitized HTML via dangerouslySetInnerHTML.

/* PromoBanner.module.scss:4 -> Raw hex literal */
/* PromoBanner.tsx:12 -> dangerouslySetInnerHTML={{ __html: copy }} */
02 · Guardrail Interception
Exit Code 1

verify-guardrails.mjs & Biome Block the PR

Rule 1 flags [TOKEN-NO-HEX] and Rule 2 flags [XSS-NO-DANGEROUS-HTML] alongside Biome security/noDangerouslySetInnerHtml, halting the pipeline.

[GUARDRAIL FAILURE] Found 2 violation(s)
Exit status 1 · Deployment blocked
03 · Self-Healing Agent Feedback
Auto-Fix Loop

Actionable Remediation Returned to Claude Code

Claude Code reads the structured stderr output, replaces the raw color with var(--genki-accent-primary), swaps raw HTML for typed JSX props, and re-runs pnpm check:all.

Fix applied -> color: var(--genki-accent-primary);
Fix applied -> <Card title={promoTitle}>{promoBody}</Card>
$pnpm check:all --filter=@genki/site
EXIT 1 · GUARDRAIL BLOCKED
  • [FAIL]
    PromoBanner.module.scss:4 [TOKEN-NO-HEX]Raw hex color literal detected — replace with var(--genki-accent-primary)
    Rule 1 Fail
  • [FAIL]
    PromoBanner.tsx:12 [XSS-NO-DANGEROUS-HTML]Forbidden dangerouslySetInnerHTML usage — render typed JSX children instead
    Rule 2 Fail
  • [FAIL]
    Biome Linter (security/noDangerouslySetInnerHtml)Static AST analysis rejected unsafe DOM injection prior to build
    Blocked
Blocked: Off-brand styles and XSS vectors cannot reach main—the guardrail script forces the AI agent to self-correct using @genki/ui tokens.
03 · Product Synergy: Claim OS UX

Wave Claims Deterministic Pre-Flight Widget

Combining Genki's Wave Claims philosophy—helping members know at the moment of filing exactly what their claim needs—with deterministic line-item math and currency verification inspired by IntelliBill.

Bangkok Hospital · Wattana, Bangkok, Thailand
Δ 0.00 Verified

Normalized Line-Item & FX Reconciliation

Policy PlanGenki Traveler · Outpatient Medical
Billed Total / EURTHB 4,850.00 (EUR 129.40)
ICD-10 ContextA09 — Infectious gastroenteritis & colitis (Attending MD signed)
Outpatient Specialist Consultation (Internal Medicine)
THB 1,800.00EUR 48.02Covered
Comprehensive GI Diagnostic Lab Panel
THB 2,150.00EUR 57.36Covered
Hospital Outpatient Pharmacy Prescription
THB 900.00EUR 24.02Covered
Wave Claims · Moment-of-Filing UX
Instant Claim OS Routing

Ready to Submit — All Required Documents & Line Items Verified

Your invoice includes the attending physician diagnosis (ICD-10 A09), itemized hospital charges, and exact mathematical reconciliation (THB 4,850.00 = EUR 129.40 at ECB mid-market rate). Estimated fast-track payout: < 48 hours.

Next Step: Ready for 1-Click Wave Claims Submission (Fast-Track Queue)
$claim-os preflight --invoice=bangkok-hosp-4850.pdf --verify-math
EXIT 0 · FAST-TRACK ELIGIBLE
  • [PASS]
    Deterministic Line-Item Math Verification (IntelliBill Engine)1,800 + 2,150 + 900 = THB 4,850.00 (Δ 0.00 against invoice total)
    Δ 0.00
  • [PASS]
    Clinical Diagnosis & ICD-10 ExtractionMapped ICD-10 A09 with attending physician stamp and treatment date
    ICD-10 A09
  • [PASS]
    FX Normalization & Policy Deductible CheckTHB 4,850.00 -> EUR 129.40 (ECB rate 0.02668); member deductible cleared
    EUR 129.40
All Wave Claims pre-flight gates passed at the moment of filing—routed directly to automated payout approval.
@genki-pitch/site · Astro Static Shell + React 19 Islands + SCSS Token GuardrailsBuilt for Genki · Cologne (CET) ↔ Rio de Janeiro (UTC-3)