DEV Community: KunStudio

Building for Korean users: 5 quirks Western devs always get wrong

KunStudio — Mon, 10 Aug 2026 00:20:59 +0000

Building for Korean Users: 5 Quirks Western Devs Always Get Wrong

I've watched Western engineers ship products to Korea and watch them fail spectacularly. Not because the products were bad—often they were technically solid. But they built for themselves, not for Korean users. After three years running a product that serves tens of thousands of Korean users, I've documented the patterns that actually matter.

Korean users operate with different expectations shaped by the country's tech infrastructure, regulatory environment, and cultural norms. These aren't edge cases you can ignore. They're core requirements that determine whether your product gains traction or gets relegated to the "foreign app" category that nobody uses.

1. You're Ignoring Local Payment Methods Entirely

This is the killer mistake. You support Stripe, maybe PayPal. Korean users look at your payment options and immediately leave.

Korea's payment ecosystem is fundamentally different. The primary methods are:

Credit cards through specific Korean acquirers (most Korean credit cards won't work through international gateways reliably)
Naver Pay and Kakao Pay (these two control roughly 70% of mobile payments in Korea)
Bank transfer (계좌이체) - still used heavily for B2B and online purchases
Mobile carrier billing (SKT, KT, LG U+) - particularly for younger users and in-app purchases

You can't just add Naver Pay as an afterthought. These services have specific integration requirements, settlement delays (typically 3-5 days), and their own user authentication flows.

I integrated Kakao Pay into my product and watched conversion from Korean users jump 340% in the first month. When I added Naver Pay two months later, another 180% increase. These aren't niche options—they're table stakes.

The cost is non-trivial. Gateway fees run 2.9-3.5% for Kakao/Naver Pay, compared to 2.2% for Stripe. But losing 90% of your Korean market because payment isn't available costs far more.

2. Your Phone Number Validation Is Broken

Western developers build phone validation assuming E.164 format and country code prefix. Then Korean users enter their phone numbers without the +82 prefix (they expect just "010-1234-5678"), and the system rejects it.

More subtle: you're probably using a library like libphonenumber which is good, but you're not handling Korean-specific validation rules. Korean mobile numbers have specific patterns—010, 011, 016, 017, 018, 019 prefixes for mobile, 02-XXXX-XXXX for Seoul landlines. If you're not validating these patterns correctly, you'll reject legitimate numbers or accept invalid ones.

I've seen products fail SMS verification on first attempt for 35% of Korean users because the validation was too strict about formatting. The solution: localize your number input component with proper placeholder formatting (010-####-####), validate against Korean-specific patterns, and accept flexible input formats (with or without hyphens, with or without country code).

Test this thoroughly. Your US test phone numbers won't catch these issues.

3. You're Not Handling the Real Name Registration Requirement

Korea has strict real-name verification requirements for financial transactions, online purchases, and certain services. This isn't optional—it's regulatory.

If your product handles money, content moderation, or identity-related features, you need I-PIN (Internet Personal Identification Number) verification or NICE/KCP authentication service integration. These are the certified Korean identity verification systems.

Many Western products ignore this and offer anonymous sign-up. Korean financial regulators will shut you down. It's not a gray area—it's black and white.

The implementation is annoying. You need to integrate with NICE (pronounced "nee-say") or similar services which require:

A Korean registered company
Specific certification levels
Integration through their XML-RPC APIs (yeah, it's 2024 and they're still using XML-RPC in some places)
Handling of encrypted personal identification data

Costs run 20-100 KRW per verification (roughly $0.015-$0.075 USD). The infrastructure is robust but dated. Plan 2-3 weeks for integration if you've never done it.

4. You Forgot About ISMS Compliance and Data Localization

Korea's Information Security Management System (ISMS) certification isn't a suggestion if you're handling user data. Major companies, government contracts, and even mid-market enterprises won't touch products without it.

More importantly: Korean personal data must be stored on Korean servers. Not "backed up" to Korean servers—actually stored there. You can't run everything on AWS us-east-1 with a compliance checkbox. Article 17 of the Personal Information Protection Act is explicit.

What this means practically: if you're processing credit card payments, real names, phone numbers, or identity information, you need:

Servers physically located in Korea (AWS Seoul region exists, but also consider Naver Cloud, KT Cloud, or NHN Cloud)
Encryption at rest and in transit (TLS 1.2 minimum, though 1.3 is increasingly required)
Audit logs that survive at least 3 years
A written data processing agreement in Korean

I've seen products get popular, then suddenly need to rebuild their entire infrastructure when a customer asked for ISMS certification. The Wannacry and Ashley Madison incidents made Korean regulations tighter, not looser.

5. You're Shipping Without Korean Language Support and It's Worse Than You Think

This is not just translation. This is localization.

Your English UI with Korean translation will work, yes. But "localization" for Korean needs:

Proper handling of 받침 (final consonants) in UI components—Korean particles change based on whether words end with consonants
Date and time formats that feel natural (Koreans use both Western calendar and lunar calendar for certain contexts)
Currency formatting: 1,000,000 won displays as "₩1,000,000" not "100 cents"—the visual weight matters
Error messages that don't sound robotic—Korean translation tools often produce stilted, unnatural phrasing

More critically: right-to-left considerations don't apply, but vertical text considerations do in certain contexts (though less common in software). More important is understanding that Korean reads fast—dense information that would require explanation in English can be compressed in Korean because of the writing system's efficiency.

I launched with Google Translate-level Korean once. Users complained the interface felt "foreign" and "cheap." After hiring a native Korean writer to rewrite every string naturally, not literally, retention improved 22%. It wasn't about correctness—native speakers understood the bad translation fine. It was about feeling local.

Budget proper translation at $0.12-0.20 per word minimum for quality. That's roughly $3,000-8,000 for a typical app's user-facing strings. Cheap translation is expensive in terms of user perception.

The Compounding Effect

These aren't five independent problems—they compound. A user who can't pay easily, has phone number validation issues, encounters an unlocalized interface, and worries about data privacy will simply use a Korean alternative instead. You don't get five chances to fail. You get zero.

Korean users are pragmatic. If your product doesn't work smoothly for them, they'll use Naver, Kakao, or a local competitor. The Korean tech market is competitive, mature, and unforgiving of shortcuts.

I built Saju (our product serving Korean users with local features) specifically because I noticed Western tools were leaving money and users on the table. The engineering required is non-trivial but manageable. The difference in traction is immediate and measurable.

If you're serious about Korean users—not just "nice to have someday" but actual revenue and growth—start here. Localize payment methods, validate phone numbers correctly, handle the regulatory requirements, store data locally, and invest in proper Korean localization. The 50+ million internet users in Korea aren't a niche market. They're where you should be building.

If you're building a product for Korean users or planning to expand there, I'm documenting patterns and building tools specifically for this market at Saju. We're solving these exact problems so you don't have to rebuild them yourself.

é ©å å å å å… ç åº è ç ©æ »ç ¥ â ä å æ å®¢ç é ç§ ç

KunStudio — Mon, 03 Aug 2026 00:30:44 +0000

éŸ©å›½åŒ–å¦†å“å…ç¨Žåº—è´ç‰©æ”»ç•¥ â€” ä¸å›½æ¸¸å®¢çœé’±ç§˜ç±

éŸ©å›½åŒ–å¦†å“åœ¨å…ç¨Žåº—çœŸçš„ä¾¿å®œ 30%~50%?æœ¬æŒ‡å—ä¸ºä¸å›½æ¸¸å®¢è¯¦è§£æœºåœºå…ç¨Žã€å¸‚å†…å…ç¨Žã€å“ç‰Œä¸“æŸœçš„çœŸå®žä»·å·®,ä»¥åŠå“ªäº›å“ç‰Œè¯¥åœ¨å“ªé‡Œä¹°ã€‚

Korean mobile-first architecture: lessons for SaaS founders

KunStudio — Mon, 03 Aug 2026 00:00:35 +0000

Why Korea's Mobile-First Mindset Matters for Your SaaS

Three years ago, I was building a scheduling tool in Seoul while most of my peers in San Francisco were still designing desktop-first UIs. The irony wasn't lost on me—Korea had 96.5% smartphone penetration by 2021, yet we kept shipping products that looked like they were optimized for 2010. I watched Kakao, Naver, and dozens of smaller Korean startups demolish foreign competitors not because of better engineering, but because they understood something fundamental: mobile is your primary product interface.

This isn't a story about mobile optimization as a checkbox feature. It's about architectural decisions that change how you think about data flow, state management, and user experience. Korean founders didn't accidentally build mobile-first; they had no choice. There's no comfortable desktop escape hatch here. And that constraint created better products.

Mobile-First Architecture, Not Mobile Optimization

There's a critical difference. Mobile optimization means taking your desktop design and shrinking it. Mobile-first architecture means building your entire data model, API contracts, and UI framework assuming a 6-inch screen with intermittent connectivity is your primary use case.

When I started building Saju, I made the deliberate choice to design the data schema around mobile-first assumptions:

Smaller request payloads: Instead of fetching a user's complete data object with nested relationships, we fetch paginated, minimalist resources. A user profile response is ~2KB, not 15KB.
Offline-first capabilities: We pre-cache essential data and queue mutations locally. If your 3G connection drops in the subway (and it will), the app doesn't crash—it queues actions.
Conditional rendering: We don't ship the same DOM across all devices. Mobile clients receive mobile-optimized templates. This seems obvious, but many SaaS platforms still load desktop-level complexity into mobile browsers.

Korean platforms like Coupang use this architecture ruthlessly. Their mobile app feels snappy because the backend is literally designed to serve mobile clients efficiently, not as an afterthought.

The practical result: our mobile app loads in under 2 seconds on 4G, and critical paths work offline. Desktop web is a companion experience, not the main event.

Handling Intermittent Connectivity at Scale

Korea has excellent infrastructure, but mobile networks are still mobile networks. Subway rides, elevator transitions, and coverage gaps are real. This taught us to build systems assuming connectivity is a feature, not a guarantee.

Here's what we implemented:

Optimistic updates with reconciliation: When a user creates a booking, the UI updates immediately. The mutation queues if offline. Once connected, we reconcile the server state. If there's a conflict (say, the slot was booked by someone else), we show a specific error and revert with explanation, not a generic "something went wrong."

// Pseudo-pattern
async function submitBooking(booking) {
  // Optimistic update
  updateLocalState(booking);
  updateUI();

  try {
    await api.post('/bookings', booking);
  } catch (error) {
    if (isOffline(error)) {
      queueForRetry(booking);
      // UI stays optimistic until retry succeeds
    } else if (isConflict(error)) {
      revertLocalState(booking);
      showConflictModal(error.details);
    }
  }
}

Incremental sync: Rather than full data refreshes, we sync only deltas. If you last synced at 3:42 PM and reconnect at 4:15 PM, we fetch changes from 3:42 PM forward, not the entire dataset. For Korean platforms handling millions of concurrent users, this is essential.

Compression and minimal payloads: We aggressively compress responses. Our API returns CBOR instead of JSON for mobile clients when possible (26% smaller). We strip unnecessary fields at the API gateway level—a mobile client gets a different schema than a desktop client.

The cost: more complexity in the backend and API versioning. The benefit: your mobile app works reliably in real-world conditions, and that reliability compounds into retention.

State Management for Unreliable Networks

Korean SaaS products deal with something Western founders often don't: a user base expecting your app to work perfectly under imperfect conditions. This drove specific patterns.

We use a three-layer state model:

Local cache (SQLite on mobile): Single source of truth for what the device knows
Pending queue (persistent storage): Actions waiting to sync
Server state (source of truth during connectivity)

When network returns, the queue processes sequentially with retry logic. We track mutation IDs to detect duplicates—if a request times out but actually succeeded, we don't process it twice.

// Queue entry structure
{
  id: 'uuid-1234',
  action: 'updateEvent',
  payload: { eventId: 'abc', title: 'New Title' },
  timestamp: 1699564800000,
  retries: 2,
  status: 'pending'
}

This pattern is used by Kakao Talk, Line, and other Korean messaging apps. Your users expect read receipts, message delivery indicators, and guaranteed ordering even when switching between WiFi and cellular. Build for that from day one, and you've already won against competitors who treat mobile as secondary.

Database Design for Mobile Clients

Korean SaaS founders think about database design differently because they're optimizing for millions of mobile clients hitting their API simultaneously. This shapes schema decisions:

Denormalization over normalization: A user's profile includes their follower count, not a COUNT(*) query. A booking includes all required event details, not a foreign key reference. This trades storage for latency, and on mobile latency kills retention.

Indexed for access patterns, not normalization: Queries look like "give me all bookings for user X in the next 7 days" and "give me availability for service Y at location Z," not normalized relational queries. Indexes exist for these specific patterns.

Sharding from the start: Korean platforms shard by user ID or region from day one, not as a scaling afterthought. This prevents hot partitions and makes mobile queries predictably fast.

For Saju, we shard by region (Seoul/Busan/etc.) and by date. A query for "all appointments tomorrow in Gangnam-gu" hits one partition and returns in <50ms. The same query on an unsharded database would timeout on mobile networks.

Polish for Retention

Korean mobile apps have absurdly high polish standards. Users notice:

Haptic feedback: Every interaction provides subtle haptic confirmation. Users don't wonder if their tap registered.
Offline indicators: A subtle visual indicator shows sync status. Red when offline, green when synced, yellow while pending. No confusion.
Loading states: Every async operation shows progress. Skeleton screens, not spinners. Korean users have grown up with snappy apps—a blank screen feels broken.
Error recovery: Errors aren't dead ends. They're recoverable states with clear next steps.

We spent 40 hours polishing error states and offline indicators. It's invisible when it works but devastating when absent. Korean competitors ship apps where every 1% of users doesn't experience loading spinners; they experience skeleton screens that feel instant.

The Real Cost

Building mobile-first architecture requires discipline. Your backend becomes more complex. Your API must support multiple schemas. Your deployment process needs to handle versioning for mobile clients that update on their own schedule, not yours.

We've maintained two API versions for six months because 12% of users hadn't updated the app. That's the cost of serving diverse devices and network conditions.

But the return is measurable: 68% of our active users access Saju exclusively through mobile. Our churn rate is 2.1% monthly, compared to industry averages of 5-8% for scheduling SaaS. That difference compounds.

Korean mobile-first architecture isn't about trends—it's about pragmatism. When your market has no desktop escape hatch, you build for the constraints you actually have. For SaaS founders, adopting this mindset early means you're not retrofitting mobile later; you're building a product that happens to have a web interface.

If you're building scheduling, booking, or any transaction-heavy SaaS, mobile-first architecture isn't optional anymore. The market expects apps that work offline, sync reliably, and feel native to the device. I'm building Saju exactly this way—if you want to see these patterns in practice, check out https://sajuapp.app to see how these principles shape real product decisions.

True Solar Time in Code: Your Clock Is Not the Sun

KunStudio — Wed, 29 Jul 2026 11:32:33 +0000

If your code needs to know where the sun actually was at a given moment, the timestamp on the clock is not the number you want. Solar yield models, sundial software, golden-hour tools, agronomy models and traditional calendar systems all run into this. Civil time is an administrative decision. Solar time is astronomy. Two independent corrections sit between them.

Neither correction is hard. What is easy to get wrong is the input you feed them, and I will get to that at the end, because it is the part that actually broke things for me.

Correction 1: you are not standing on the zone meridian

A time zone is a band of longitude that agrees to share one clock. That clock is anchored to a meridian: UTC+9 is anchored to 135 degrees east. If you are not standing on 135E, your local noon is not the zone's noon.

The Earth rotates 360 degrees in 1440 minutes, so one degree of longitude is four minutes of time.

MINUTES_PER_DEGREE = 4.0  # Earth turns 360 deg in 1440 min

def longitude_correction_minutes(longitude_deg, utc_offset_hours):
    """Minutes to add to clock time to reach local mean solar time."""
    zone_meridian = utc_offset_hours * 15.0
    return (longitude_deg - zone_meridian) * MINUTES_PER_DEGREE

Korea is the textbook case. It keeps UTC+9, anchored to 135E, but Seoul sits at roughly 126.978E. That is eight degrees of slack:

Seoul     lon  126.9780  ->  -32.09 min
Tokyo     lon  139.6917  ->  +18.77 min
London    lon   -0.1276  ->   -0.51 min
New York  lon  -74.0060  ->   +3.98 min

Seoul's sun runs about 32 minutes behind Seoul's clocks, permanently. London, sitting almost on the prime meridian, needs half a minute. This offset is fixed for a given location and zone, and it is not seasonal.

Correction 2: the equation of time

The second correction is seasonal, and it is the more interesting one. Even a perfect sundial standing on the zone meridian disagrees with a perfect clock, because the Earth's orbit is elliptical and its axis is tilted. Apparent solar days are not all the same length. The accumulated difference is the equation of time, and it swings across roughly half an hour over the year.

This is the NOAA Solar Calculator formulation. It is a truncated series rather than a full ephemeris, which makes it small enough to inline anywhere:

import math

def julian_century(dt_utc):
    y, m = dt_utc.year, dt_utc.month
    if m <= 2:
        y -= 1
        m += 12
    a = y // 100
    b = 2 - a + a // 4
    day_fraction = (dt_utc.hour + dt_utc.minute / 60 + dt_utc.second / 3600) / 24
    jd = (math.floor(365.25 * (y + 4716))
          + math.floor(30.6001 * (m + 1))
          + dt_utc.day + day_fraction + b - 1524.5)
    return (jd - 2451545.0) / 36525.0

def equation_of_time_minutes(dt_utc):
    t = julian_century(dt_utc)
    l0 = math.radians((280.46646 + t * (36000.76983 + t * 0.0003032)) % 360.0)
    m = math.radians(357.52911 + t * (35999.05029 - 0.0001537 * t))
    e = 0.016708634 - t * (0.000042037 + 0.0000001267 * t)
    seconds = 21.448 - t * (46.8150 + t * (0.00059 - t * 0.001813))
    eps0 = 23.0 + (26.0 + seconds / 60.0) / 60.0
    omega = math.radians(125.04 - 1934.136 * t)
    eps = math.radians(eps0 + 0.00256 * math.cos(omega))
    y = math.tan(eps / 2.0) ** 2
    eot = (y * math.sin(2 * l0)
           - 2 * e * math.sin(m)
           + 4 * e * y * math.sin(m) * math.cos(2 * l0)
           - 0.5 * y * y * math.sin(4 * l0)
           - 1.25 * e * e * math.sin(2 * m))
    return math.degrees(eot) * 4.0

Validate it before you trust it. Sweep a year and look for the extremes, which are well documented:

max EoT 2026-11-03 16.49
min EoT 2026-02-11 -14.23

Published tables put the annual minimum on Feb 11 near -14.24 minutes and the annual maximum in early November near +16.49 minutes. Matching to two decimal places is a good sign the series is transcribed correctly. If you port this and your February minimum comes out positive, you have a sign error in the eccentricity term.

Putting them together

from datetime import timedelta, timezone

def true_solar_time(local_dt, longitude_deg):
    """local_dt must be timezone-aware."""
    offset_hours = local_dt.utcoffset().total_seconds() / 3600.0
    lon_corr = longitude_correction_minutes(longitude_deg, offset_hours)
    eot = equation_of_time_minutes(local_dt.astimezone(timezone.utc))
    total = lon_corr + eot
    return local_dt.replace(tzinfo=None) + timedelta(minutes=total), total

For a clock reading of 23:30 in Seoul, across a year:

clock (KST)    lon(min)   eot(min)      total   true solar time
2026-01-15       -32.09      -9.44     -41.53   2026-01-15 22:48:28
2026-04-15       -32.09       0.00     -32.09   2026-04-15 22:57:54
2026-07-15       -32.09      -6.03     -38.11   2026-07-15 22:51:53
2026-10-15       -32.09      14.27     -17.82   2026-10-15 23:12:10
2026-11-15       -32.09      15.43     -16.66   2026-11-15 23:13:20

The total correction moves between about -42 and -17 minutes depending on the date. A single hardcoded constant will be wrong by up to 25 minutes.

The part that actually bites: the offset is an input, not a constant

Look at true_solar_time again. It reads utcoffset() off the datetime you hand it. Everything downstream depends on that being right, and this is where real code fails, because UTC offsets are historical facts rather than properties of a country.

Korea changed its standard time more than once. It adopted UTC+08:30 in 1908, moved to UTC+09:00 in 1912, went back to UTC+08:30 in 1954, and returned to UTC+09:00 in 1961. It also ran summer time in several years. The IANA time zone database knows all of this:

from zoneinfo import ZoneInfo
from datetime import datetime

tz = ZoneInfo("Asia/Seoul")
for y in (1954, 1955, 1960, 1961, 1962, 1988, 1989):
    print(y, datetime(y, 7, 1, 12, tzinfo=tz).utcoffset())

1954 8:30:00
1955 9:30:00
1960 9:30:00
1961 8:30:00
1962 9:00:00
1988 10:00:00
1989 9:00:00

July 1988 is UTC+10, not UTC+9, because South Korea observed daylight saving around the Seoul Olympics. Hardcode timezone(timedelta(hours=9)) and every summer 1987 and 1988 local time in your database is an hour off before the solar correction even runs.

Here is what that costs. Traditional East Asian calendars bucket the day into twelve two-hour branches, so a shifted timestamp can land in a different bucket:

hardcoded UTC+9      offset=9:00:00   lon=-32.09  eot=-5.95  total=-38.04  -> 21:21:57  branch=Pig
Asia/Seoul (tzdata)  offset=10:00:00  lon=-92.09  eot=-5.95  total=-98.04  -> 20:21:57  branch=Dog

Same record, different answer. Note that the longitude correction itself also changed, from -32 to -92 minutes, because the zone meridian moved with the offset. The bug compounds rather than cancelling out.

I ran into this while building Cheonmyeongdang, a Korean Saju (Four Pillars) calculator that derives a chart from a birth date and hour. When the hour pillar is a two-hour bucket and your correction is half an hour wide, boundary cases are not rare, they are routine.

The rule is short: never construct a fixed-offset timezone for a historical local time. Use zoneinfo in Python, or the equivalent tz-aware type in your language, and let the database tell you the offset.

JavaScript

Same maths, and the offset lookup goes through Intl, so it respects historical transitions too:

function zoneOffsetMinutes(date, timeZone) {
  const parts = new Intl.DateTimeFormat('en-US', {
    timeZone: timeZone,
    timeZoneName: 'longOffset',
  }).formatToParts(date);
  const name = parts.find((p) => p.type === 'timeZoneName').value; // "GMT+10:00"
  const m = name.match(/GMT([+-])(\d{2}):?(\d{2})?/);
  if (!m) return 0;
  return (m[1] === '-' ? -1 : 1) * (Number(m[2]) * 60 + Number(m[3] || 0));
}

Converting wall-clock fields to an instant needs one fixed-point step, since you cannot know the offset until you know the instant:

function wallClockToInstant(w, timeZone) {
  const naive = Date.UTC(w.year, w.month - 1, w.day, w.hour, w.minute);
  let ts = naive;
  for (let i = 0; i < 2; i++) {
    ts = naive - zoneOffsetMinutes(new Date(ts), timeZone) * 60000;
  }
  return new Date(ts);
}

Running the 1988 case through the JavaScript port on Node 24:

Asia/Seoul  offset=UTC+10  lon=-92.09  eot=-5.95  total=-98.04  -> 20:21:57

Identical to the Python, which is the check you want whenever you maintain two implementations of the same formula.

Caveats

The NOAA series is a low-precision approximation. It is fine for minute-level work and not intended for arcsecond astronomy, so reach for a real ephemeris if you need better.

"Longitude of the city" is also a simplification. A city is not a point, and Seoul spans enough longitude to move the correction by a fraction of a minute. Pick a documented reference point and write it down rather than letting it drift between modules.

Finally, decide explicitly whether your domain wants apparent solar time, which is both corrections, or local mean solar time, which is longitude only. Different traditions and technical standards answer that differently. Silently mixing the two across a codebase is worse than picking the less popular one and applying it consistently.

Lichun Is Not Always February 4: Computing Solar Terms With Newton's Method

KunStudio — Wed, 29 Jul 2026 04:55:19 +0000

Most calendar code that touches East Asian astrology has the same bug hiding in it: someone wrote down that Lichun (立春, the start of spring) falls on February 4, and moved on.

It does not. In 2021 and 2025 it fell on February 3. In 2025 the exact moment was 23:10 KST — fifty minutes before midnight. Anyone born in that fifty-minute window gets a different year pillar and a different month pillar than a hardcoded table would give them. For a birth-chart engine, that is not a rounding error. That is the wrong chart.

Here is what a solar term actually is, and how to compute one properly.

A solar term is an angle, not a date

The 24 solar terms (절기 / 節氣) are not calendar conventions. Each one is the instant at which the sun's apparent ecliptic longitude reaches a multiple of 15 degrees. Lichun is 315 degrees. The vernal equinox is 0. There are 24 of them because 360 / 15 = 24.

That definition has two consequences that matter for implementation:

The instant is global. It is one moment in physical time, the same for every observer on Earth. Only its local clock representation differs.
The instant does not land on a tidy calendar boundary. It drifts year to year because the tropical year is not 365 days, and leap years shove it around.

So the question "what date is Lichun in year Y" is really "solve for the time t where apparentSolarLongitude(t) == 315, then render t in the target timezone."

That is a root-finding problem.

Step 1: apparent solar longitude

I use the low-precision solar series from Jean Meeus, Astronomical Algorithms (2nd ed.). Given a Julian Ephemeris Day:

function sunApparentLongitude(jde) {
  const T = (jde - J2000) / 36525.0;
  const L0 = rev360(280.46646 + 36000.76983 * T + 0.0003032 * T * T);
  const M  = rev360(357.52911 + 35999.05029 * T - 0.0001537 * T * T);
  const Mr = M * D2R;
  const C =
    (1.914602 - 0.004817 * T - 0.000014 * T * T) * Math.sin(Mr) +
    (0.019993 - 0.000101 * T)                    * Math.sin(2 * Mr) +
     0.000289                                    * Math.sin(3 * Mr);
  const trueLong = L0 + C;
  const omega = 125.04 - 1934.136 * T;
  return rev360(trueLong - 0.00569 - 0.00478 * Math.sin(omega * D2R));
}

L0 is the geometric mean longitude, M the mean anomaly, C the equation of the center. The final line is what makes it apparent rather than true: -0.00569 is aberration, and the omega term is nutation in longitude. Skip those two and you are off by roughly 20 arcseconds, which is about seven minutes of time. Usually harmless, occasionally the difference between February 3 and February 4.

Step 2: Newton's method on a circle

Now solve sunApparentLongitude(jde) == targetLon. The derivative is well-behaved (the sun moves about 1 degree per day, always forward), so plain Newton converges in a handful of iterations:

function solveLongitude(targetLon, jdeGuess) {
  let jde = jdeGuess;
  for (let i = 0; i < 12; i++) {
    const lon = sunApparentLongitude(jde);
    let diff = lon - targetLon;
    while (diff >  180) diff -= 360;
    while (diff < -180) diff += 360;

    const h = 0.02;
    let d1 = sunApparentLongitude(jde + h) - sunApparentLongitude(jde - h);
    while (d1 >  180) d1 -= 360;
    while (d1 < -180) d1 += 360;

    const rate = d1 / (2 * h);
    const corr = diff / rate;
    jde -= corr;
    if (Math.abs(corr) < 1e-7) break;
  }
  return jde;
}

The while loops wrapping diff and d1 into [-180, 180] are the entire trick, and they are the thing people get wrong. Longitude is modular. Near 0 degrees the naive difference between 359.9 and 0.1 is -359.8, which sends Newton flying off to the wrong year. Normalizing the difference rather than the values keeps the step honest across the wrap point. The same normalization is needed on the numerical derivative for the same reason.

I use a central difference (jde + h and jde - h) instead of deriving the series analytically. It costs one extra evaluation per iteration and removes a whole class of transcription errors.

Step 3: the part everyone forgets, delta-T

Newton gives an answer in Terrestrial Time. Civil clocks run on Universal Time. The gap between them, ΔT = TT − UT, is not a constant — it tracks the irregular rotation of the Earth, and it is currently around 69 seconds and growing.

Sixty-nine seconds sounds ignorable until the term lands at 23:59:30 local. Then it moves the date by a day, and the date is the thing the chart is keyed on. So it gets applied as a piecewise polynomial in the year:

if (year >= 2005 && year < 2050) {
  const t = y - 2000;
  dt = 62.92 + 0.32217 * t + 0.005589 * t * t;
}

with separate branches for earlier epochs, then:

const dt = deltaTSeconds(approx.year, approx.month);
const jdKST = jde - dt / 86400 + 9 / 24;   // TT -> UT -> KST

Subtract ΔT to get UT, add 9 hours for KST, and only then convert to a calendar date.

Note the ordering. Converting to a date first and adjusting afterwards is the bug that produces off-by-one days at year boundaries.

Step 4: guess the right year

One more trap. Seeding Newton from a day-of-year approximation can converge into the neighbouring year's occurrence of the same longitude, because 315 degrees happens every year. The fix is to probe and verify:

for (const probeYear of [year - 1, year, year + 1]) {
  let approxDoy = 79 + (lon / 360) * 365.2422;
  if (approxDoy > 365.2422) approxDoy -= 365.2422;
  const jde = solveLongitude(lon, gregorianToJD(probeYear, 1, 0.5) + approxDoy);
  // ...convert to KST...
  if (g.year !== year) continue;   // converged into a neighbour, try again
  return g;
}

The 79 offset is the approximate day-of-year of the vernal equinox, which is where ecliptic longitude 0 sits.

Validation

Claiming astronomical accuracy without checking it is how these bugs survive. I ran all 12 major terms across 1920–2050 against Korea's public calendar API and the dates match exactly across the whole range.

On precision: the date is exact throughout. The minute can differ by up to roughly 15 minutes against a full VSOP87 solution, because the Meeus low-precision series carries about 0.01 degrees of error. For pillar boundaries that is irrelevant — the boundary is evaluated at day granularity. If you are building something that needs the minute, use the full series.

Why bother

The honest answer is that the hardcoded version is right most of the time. Lichun is February 4 in the majority of years, so the table passes casual testing and fails silently for the people born on the edge — who are exactly the people most likely to notice their chart is wrong.

Roughly 130 lines of astronomy replaces the table and removes the failure mode. It is self-contained, has no dependencies, and runs fine at the edge; ours executes inside a Cloudflare Function.

I build Cheonmyeongdang, a Korean Saju (four pillars) reading service, and this calculation sits under every chart it produces. If you want to see the boundary behaviour without installing anything, the English chart calculator is free and needs no signup — try a birth date on February 3 or 4 of 2021 or 2025 and watch the month pillar change.

The general lesson transfers beyond astrology: when a date in your domain is defined by a physical event rather than a calendar rule, storing it as a constant is a bug with a delayed fuse.

Why Naver/Kakao dominate Korean search and what global devs miss

KunStudio — Mon, 27 Jul 2026 00:00:13 +0000

The Korean Search Puzzle: Why Google Lost to Local Players

When I first started building products in Korea, I made an embarrassing mistake. I assumed Naver and Kakao were just "Korean alternatives to Google." They're not. They're different beasts entirely, optimized for how Koreans actually search, communicate, and discover information. Google's market share in Korea sits around 3-5%, while Naver commands roughly 60-70% of desktop search. For mobile, the picture fragments further—Kakao Talk's integrated search and commerce features matter as much as traditional search engines.

This isn't about inferior technology. It's about understanding why network effects and local infrastructure create advantages that are genuinely difficult for foreign competitors to overcome.

Naver's Ecosystem Lock-in: More Than Search

Naver started as a portal in 1999, but calling it a "search engine" undersells what it became. The platform evolved into an ecosystem where users don't just search—they live.

Naver Blog is the critical piece. Unlike Medium or dev.to, Naver Blog had 40+ million registered users at its peak and became the default place Koreans publish long-form content, product reviews, and tutorials. When you search on Naver, you're not getting indexed web pages like Google. You're pulling from Naver's closed ecosystem: Naver Blog posts, Naver Cafe (community forums), Naver Knowledge iN (Q&A), and Naver Shopping integration. This creates a self-reinforcing loop—content creators publish on Naver Blog because that's where Naver search drives traffic. Users search on Naver because that's where the content is.

Try searching for Korean restaurant reviews or product recommendations. You'll find Naver Blog posts ranking first. Google's algorithm would rank Wikipedia, Reddit, or review sites. Naver ranks content within its own network.

Naver Shopping integration further cements this. When you search for a product, Naver doesn't just link you to retail sites—it surfaces prices, reviews, and purchase options directly within Naver Shopping, taking a percentage of transactions. For Korean e-commerce businesses, Naver Shopping advertising (called "Product Ads") is non-negotiable. It's where customers search and convert.

The technical implication: Naver's entire ranking system optimizes for content within its platform, not the open web. PageRank doesn't apply. Backlinks from outside Naver matter less than community engagement metrics within Naver's ecosystem.

Kakao's Infrastructure Play: WeChat Before WeChat

Kakao's dominance comes from a different angle—platform integration and messaging infrastructure.

Kakao Talk (messaging app) grew to over 50 million daily active users in Korea by the mid-2010s. The company realized they owned the layer through which Koreans communicate. They embedded search, commerce, and content discovery directly into the app. Kakao Map became more useful than Google Maps for Korean users because businesses are indexed there, customer reviews are aggregated, and payment integration is seamless.

From a developer perspective, here's what matters: Kakao's business model depends on owning the transaction layer. When a Korean user discovers a restaurant via Kakao Map, books a table through Kakao Talk's restaurant bot, and pays via Kakao Pay—Kakao captures data and fees at every step. Google's search model, while powerful globally, generates money through advertising. Kakao generates money through transaction volume.

This shapes how their search algorithms work. Kakao prioritizes discoverable businesses and services that drive transactions, not just relevant information. If you're a small cafe with 100 menu items indexed on Kakao Map, you're more discoverable than a high-quality but not-yet-indexed competitor.

Kakao Brain investments in AI and generative models suggest they're building toward conversational discovery—users asking Kakao Talk bot for recommendations rather than typing search queries. The early versions show how this reshapes search intent.

Network Effects and Regulatory Protection

Both Naver and Kakao benefit from regulatory factors that Western tech didn't have to navigate the same way.

Korea's adoption of ISP registration requirements and strict regulations around foreign payment processors created barriers for international players. But more importantly, Korean users simply trusted local companies with their data and payments earlier than Western users did. By the time Google wanted to seriously invest in Korean search around 2010, Naver and Kakao had already captured user behavior.

Network effects then become unbeatable. If 65% of Korean users search on Naver, 65% of Korean content creators optimize for Naver. If they optimize for Naver, more users have reason to search there. Google entering this market required breaking trust and convincing creators to optimize for Google while still optimizing for Naver for their primary audience.

The regulatory angle also mattered technically. Korea's Real Name Registration System and other identity verification requirements meant these platforms had higher-quality user data for personalization than Google initially did.

What Global Developers Miss

The strategic lesson for developers building for or in Korea:

1. SEO means Naver and Kakao, not Google. If your target market is Korean users, allocate resources accordingly. Naver Blog syndication, Naver Shopping optimization, and Kakao Map listing are non-negotiable. Global SEO best practices transfer maybe 30% to this market.

2. Transaction-driven ranking beats relevance-driven ranking. Traditional SEO assumes search engines want to surface the most relevant result. Naver and Kakao want to surface results that drive monetizable actions. This means small businesses see better ROI optimizing for transaction intent rather than organic search volume.

3. Closed ecosystems compound faster than open ones. Google's strength is indexing the entire web. Naver and Kakao's strength is that they don't have to—they built ecosystems where the content they want ranked is created on their platforms. Building into these ecosystems rather than against them matters more than search optimization.

4. Mobile and messaging layer changes discovery patterns. A significant portion of Korean search now happens through Kakao Talk bots and mobile apps, not search.naver.com. Optimization means API integration and bot development, not just content.

The Practical Framework for Korean Market Entry

If you're building a product for Korean users:

Months 1-3: Get indexed on Naver and Kakao Map. This takes longer than Google indexing (4-8 weeks typically). Start immediately.
Months 2-6: Build a Kakao Talk bot or Kakao Map integration. If you're a service business, Kakao Map is non-negotiable. If you're B2B SaaS selling to Koreans, consider a Kakao Talk bot for customer support.
Ongoing: Monitor Naver Search Advisor and Kakao Business Console like you'd monitor Google Search Console. The interfaces are different. The data signals are different.

The uncomfortable truth: Naver and Kakao's dominance isn't temporary. They've made mistakes (Naver's poor mobile transition in the early 2010s, Kakao's overexpansion), but both remain entrenched. New competitors emerge—Coupang's search for commerce, Naver's own TikTok alternative competition—but the core search and discovery layer remains their territory.

If you're building in Korea or serving Korean users, treat this market as fundamentally different from Western markets. The search and discovery layer isn't Google. It's Naver for informational queries, Kakao for transactional discovery, and increasingly, social platforms for recommendations. Optimizing for this reality is the difference between traction and invisibility.

For teams navigating Korean market entry, I've built tools to help developers understand these dynamics better. At Saju, we're working on making Korean market analysis more accessible—giving builders data on what actually works in Korean search and commerce before they invest months chasing the wrong optimization vectors.

The Math Behind a Late-Fee: Turning "Net 30" Into an Enforceable Number

KunStudio — Tue, 21 Jul 2026 08:37:29 +0000

The math behind a late-fee: turning "net 30" into an enforceable number

I build small web tools, and the one that surprised me most wasn't AI-heavy at all — it was a late-fee calculator for freelancers. The hard part wasn't the arithmetic. It was deciding which arithmetic is defensible enough to put in front of a client who is already 45 days late.

This is a short write-up of the reasoning, with the actual formula I shipped in Invoice Rescue.

Simple interest, day-count, no compounding

The instinct is to reach for compound interest. Don't. For overdue B2B invoices, a client-facing fee that compounds daily reads as punitive and invites a dispute. Simple interest on a daily accrual is both easier to justify and closer to how most late-payment statutes actually describe it.

function lateFee(amount, annualRatePct, daysOverdue) {
  const dailyRate = (annualRatePct / 100) / 365;
  const fee = amount * dailyRate * Math.max(0, daysOverdue);
  return Math.round(fee * 100) / 100;
}
// $2,500 invoice, 18%/yr, 20 days late → $24.66

Two decisions are doing the work here:

Math.max(0, daysOverdue) — the due date is in the future for a lot of "check the fee" sessions (people model it before it's actually late). A naive today - dueDate goes negative and produces a phantom credit. Clamp it.
/ 365 — some contracts and jurisdictions use a 360-day "banker's year." Pick one, state it in the output, and don't silently switch. The number a client sees has to match the number in the clause you send them.

The part everyone skips: the day-count is a UX problem, not a math problem

When someone types a due date, they mean their timezone and their calendar day. If you diff two Date objects you'll get an off-by-one every time the browser TZ and the invoice TZ disagree at midnight. Compare calendar dates, not timestamps:

function daysBetween(dueISO) {
  const d = new Date(dueISO + "T00:00:00");
  const now = new Date();
  const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
  return Math.round((today - d) / 86400000);
}

The reminder sequence is a state machine, not three templates

The other half of getting paid is the follow-up, and the mistake is treating "polite / firm / final" as three static emails. They're a state machine with one input that changes tone: how much rapport you can still afford to spend.

Polite (day 1–7 overdue): assume an oversight. No fee mentioned. One clear ask, one clear due date.
Firm (day 8–21): name the amount, the invoice number, and the days overdue as facts. Introduce the fee clause as information, not a threat.
Final (22+): state the next concrete step and a hard date. Still no insults — a final notice that stays professional is the one that survives being forwarded to their accounts team.

The thing that makes this convert is that every message references the specific invoice and the specific number. Generic "just following up!" emails get ignored precisely because they carry no cost signal.

What I'd tell my past self

Don't compound, clamp the day-count, compare calendar dates, and keep the final notice boring. The tool that came out of this reasoning is Invoice Rescue — the fee calculator and the three-step templates are free to use with no signup; a paid AI pack writes the full chase sequence for a specific situation. But honestly, the four rules above are the whole product. The rest is just typing.

If you've got an invoice sitting past due right now, run the numbers on Invoice Rescue and start with the polite template today — the longer you wait, the more the tone has to escalate.

Written by the KunStudio team. We build small, focused web tools. This is general information about invoicing workflows, not legal or financial advice — check your contract and local law for the enforceable rate.

How Korean fintech (Toss / KakaoPay / PortOne) actually works under the hood

KunStudio — Mon, 20 Jul 2026 00:00:07 +0000

The Architecture Behind Korea's Fintech Giants: How Toss, KakaoPay, and PortOne Actually Work

Korean fintech companies like Toss, KakaoPay, and PortOne have become synonymous with financial innovation, but most developers only see the polished UI. I've spent months reverse-engineering their payment flows, API patterns, and infrastructure choices while building payment features for my own products. Here's what actually happens when you tap "send money" in Toss or click "pay" on PortOne.

Understanding the Three-Layer Korean Fintech Model

Korean fintech operates within a regulatory framework that forces a specific architectural pattern: the three-layer stack. Unlike other countries, Korea mandates strict separation between payment service providers (PG), payment intermediaries, and actual banks.

Layer 1: Frontend & User Interface
This is what users see. Toss's interface is famously minimal—a transfer takes maybe 3 taps. But under the hood, the frontend performs several crucial steps: biometric authentication (fingerprint, face recognition via Knox on Samsung devices), device binding validation, and transaction signing. Toss uses a combination of WebAuthn for web and proprietary SDK integration for mobile apps.

Layer 2: Payment Service Provider (PG)
PortOne (formerly I'mport) sits here. They don't actually hold money—they're orchestrators. When you initiate a payment through PortOne's API, you're hitting their unified payment gateway that routes to the actual acquiring banks. PortOne normalizes requests across 50+ Korean payment methods into a single API surface. Their core business is handling the translation layer between merchants and banks.

Layer 3: Banking Infrastructure
The actual money movement happens through Korea's interbank network. Toss itself operates as a "virtual bank" (인터넷 전문은행) licensed by the FSC since 2021. This is critical—they can hold customer deposits directly, which KakaoPay cannot. This explains why Toss launched checking accounts and why KakaoPay had to partner with Kakao Bank.

The Real-Time Clearing System: A-Wait-FTS

The backbone of Korean money movement isn't SWIFT or ACH. It's A-Wait-FTS (Advanced Waiting Financial Telecom System), the interbank settlement platform operated by the Korean Financial Telecommunications and Clearings Institute. Think of it as Korea's version of Fedwire, but with specific requirements for fintech.

When you send ₩10,000 from a Toss account to another bank, here's the actual sequence:

Authentication (~100ms): Multi-factor auth combines something you have (device), something you know (PIN), and something you are (biometrics). Toss uses device binding—your phone is registered with your account. A transaction from an unregistered device triggers additional verification.
Transaction Signing (~50ms): The request is signed using PKI (Public Key Infrastructure). Korean regulations require specific encryption standards—primarily AES-256 for transmission and RSA-2048 for key exchange.
Message Format Conversion (~30ms): PortOne or the direct bank connection formats the request into SWIFT-like messages, but with Korean-specific fields. Bank codes use the 3-digit BIC system (우리은행=020, 국민은행=004, etc.).
Real-Time Settlement (~1-3 seconds): The money moves through A-Wait-FTS. Unlike older batch systems, A-Wait-FTS processes transfers individually and immediately. Most Korean transfers complete in under 10 seconds, often faster than 5 seconds.
Notification (~100ms): Both sides receive settlement confirmations. Apps display "전송 완료" (transfer complete) almost instantly.

The entire flow completes in 5-10 seconds, which is why Korean users expect instant transfers. This is standard, not exceptional.

How KakaoPay Handles Money Without Being a Bank

KakaoPay's architecture reveals how fintech navigates regulatory constraints. They operate as a payment service intermediary (결제중개사), not a bank. This means they cannot legally hold customer money.

Their workaround: custodial banking relationships. When you load ₩100,000 into KakaoPay, it's actually held by partner banks (신한은행, 우리은행, 국민은행). The frontend shows one unified wallet, but the backend maintains separate ledgers per partner bank. Kakao's system determines which partner bank holds which funds based on customer velocity and liquidity forecasts.

When you send money from KakaoPay to another user, two scenarios occur:

If recipient is also on KakaoPay: Internal ledger transfer, instant, no clearing required. Just a database update in Kakao's system.

If recipient is on another platform or bank: Actual clearing through A-Wait-FTS, incurring fees. This is why KakaoPay encourages transfers between KakaoPay users—zero fees.

The fee structure here is telling: ₩0 for in-network, ₩1,000 for cross-network transfers under ₩1,000,000. That difference is literally the cost of A-Wait-FTS clearing.

PortOne's API Abstraction Layer

PortOne's technical value isn't flashy, but it's where the real engineering happens. They normalize payment methods across different banks and PGs.

A merchant integrating PortOne makes one API call:

IMP.request_pay({
  pg: 'danal',
  pay_method: 'card',
  merchant_uid: '20231015-000001',
  name: '상품명',
  amount: 14000,
  buyer_email: 'example@example.com',
  buyer_name: '구매자명',
  buyer_tel: '010-1234-5678'
}, function(rsp) {
  if (rsp.success) {
    // payment success
  }
});

Behind this single call, PortOne:

Routes to the appropriate PG (Danal, KCP, NICE, etc.) based on pg parameter and inventory logic
Handles method-specific quirks (일반결제 vs 정기결제 parameters differ per PG)
Manages token storage for recurring payments
Normalizes response formats (each PG returns different field names)
Handles escrow payments, which are common for marketplace transactions

They process ~₩20 trillion annually (2023 numbers), roughly 40% of Korean online transactions. That volume requires serious infrastructure—they use redundant data centers, real-time failover to backup PGs, and maintain <99.99% uptime SLA.

Security: Beyond HTTPS

Korean fintech security goes beyond standard TLS. It mandates specific practices:

Card Information Never Touches Your Server: All sensitive payment data goes directly to the PG's secure servers via client-side encryption. This is non-negotiable under PCI DSS + Korean regulations.

Token-Based Transactions: After initial payment, merchants receive tokens. Subsequent transactions use tokens, never raw card data. PortOne manages this token lifecycle.

Device Binding: A payment initiated from an unknown device automatically triggers additional verification. Toss stores device fingerprints (hardware identifiers, OS, installed apps) to detect anomalies.

Real-Time Fraud Detection: Most platforms use ML-based scoring (Datamines, SK Infosec, etc.). Transaction flagged as suspicious? SMS 2FA required. This adds 10-30 seconds but is invisible if legitimate.

Encryption Standards: The regulatory default is AES-256-CBC for data transmission, RSA-2048 for key exchange. Older MD5 hashing is explicitly forbidden since 2015.

Why Integration Speed Still Matters

Despite standardization, Korean fintech integration takes 1-2 weeks for a competent engineer, not days. Why?

Certification delays: Your merchant registration can't process payments until the PG's compliance team reviews your business (3-5 days).
Test-mode requirements: Each PG's sandbox has different test card numbers, amounts that trigger specific responses. Test card 4111-1111-1111-1111 works at one PG, fails at another.
Recurring payment setup: If you need subscriptions, the setup flow diverges dramatically between PGs. NICE requires explicit API keys per subscription type, while Danal doesn't.

Building payment infrastructure in Korea is pragmatic engineering. You're not fighting the system—you're working within it. Toss, KakaoPay, and PortOne succeeded not through technical wizardry, but by understanding Korean financial regulations intimately and building systems that respect them while delivering exceptional user experience.

If you're building payment features for Korean users or expanding into Korea, integrating properly from the start saves months later. Understanding these three layers—user interface, PG orchestration, and banking infrastructure—shapes every architectural decision.

I'm currently building Saju, a fintech dashboard for Korean solo founders and small businesses to manage cash flow across multiple payment platforms. We went through this exact integration nightmare, and I'm documenting lessons learned at https://sajuapp.app. If you're navigating Korean payment infrastructure for the first time, that might save you days of debugging.

Two SKUs, One Model: How Prompt Engineering Alone Creates a $19 vs $29 SOP Generator

KunStudio — Sun, 19 Jul 2026 13:23:39 +0000

Two SKUs, One Model: How Prompt Engineering Alone Creates a $19 vs $29 SOP Generator

AI SOP Builder turns a plain-language process description into a finished Standard Operating Procedure. There's no fine-tuned model and no separate "pro" pipeline — it's a single Claude Haiku call, and the entire product differentiation between the $19 and $29 tiers lives in how the prompt is assembled.

One generation function, two tiers

Both SKUs — single ($19, standard) and pro ($29, "audit-ready") — route through the same generateSOP() function and the same model (claude-haiku-4-5, with an optional SOP_MODEL_PRO env override). What changes is a tier string threaded through the prompt builders:

export function buildSystem(brief, tier) {
  return [
    "You are a senior operations and quality-management specialist who writes Standard " +
    "Operating Procedures (SOPs) that pass ISO 9001-style audits...",
    "Never invent fake statistics, regulation numbers, certification IDs, or citations. " +
    "If a step depends on a policy you were not given, refer to it generically (for example " +
    "'per your data-retention policy') and flag it as something the owner must fill in...",
    tier === "pro"
      ? "This is the audit-ready edition: add a compact RACI view ... explicit controls, " +
        "checkpoints, and risk/compliance notes throughout the Procedure, and make the " +
        "Quality Checklist thorough enough to serve as a sign-off sheet."
      : "Keep it practical, complete, and immediately usable by a small team.",
  ].join(" ");
}

Pro doesn't get a different retrieval source or bigger context window — it gets one extra paragraph telling the same model to add a RACI matrix (Responsible/Accountable/Consulted/Informed), inline compliance notes, and a heavier sign-off checklist. The anti-hallucination instruction — never invent a regulation number or certification ID, flag anything unprovided as something "the owner must fill in" — applies to both tiers, since a fabricated ISO clause in an audit file is worse than an SOP that's honestly generic.

The free preview is a capped, separate generation — not a truncated one

Before payment, /api/preview generates only the "Purpose and Scope" section, capped at 240 output tokens:

export async function generateSOP(env, brief, previewOnly, tier) {
  const system = buildSystem(brief, tier);
  const user = buildUser(brief, previewOnly, tier);
  const model = !previewOnly && tier === "pro" ? env.SOP_MODEL_PRO || undefined : undefined;
  return claudeGenerate(env, system, user, previewOnly ? 240 : tier === "pro" ? 5200 : 3600, model);
}

This isn't the full SOP truncated client-side — in previewOnly mode the prompt itself tells the model to write nothing but that section ("write nothing else — no other section, no numbered steps"). The visitor reads something genuinely specific to their process before paying anything, which is the point: a preview obviously tailored to your input converts differently than a generic marketing screenshot.

Fulfillment happens inline with payment capture — deliberately

There's no separate "generate" step after checkout. capture-order.js captures the PayPal order and, in the same request, calls generateSOP() for the full document before responding:

let sop = "";
let processingError = false;
try {
  sop = await generateSOP(env, b.brief, false, priced.tier);
} catch (e) { processingError = true; }

return json({
  status: "COMPLETED", orderID: body.orderID, tier: priced.tier, sop,
  processing_error: processingError,
  support: processingError ? "ghdejr11@gmail.com (auto-refund if unfulfilled)" : undefined,
}, 200);

The important line: status: "COMPLETED" still returns even if generation throws — the payment succeeded, so the response says so, with a processing_error flag and a support contact instead of silently losing the fact that money changed hands. A source comment ties this directly to a lesson from a prior pipe where payments succeeded while fulfillment silently failed with no record of it.

Rendering the result without a Markdown library

The SOP comes back as Markdown, and the front end renders it with a small hand-written parser — line-by-line regex matching for headings (^#{1,4}\s), numbered lists (^\d+[.)]\s), bullets (^[-*]\s), and **bold** spans — built entirely with createElement/textContent, never innerHTML. It's a deliberately small vocabulary because that's the entire output format the system prompt requires — "render-safe Markdown only... no tables, code fences, or HTML" — so the renderer only has to handle exactly what the model is told to produce.

Live: https://ai-sop-builder.pages.dev/

Redesigning a Yard Without Touching the House: Structure-Preserving AI Image Edits With FLUX.2 [pro]

KunStudio — Sun, 19 Jul 2026 13:23:02 +0000

Redesigning a Yard Without Touching the House: Structure-Preserving AI Image Edits With FLUX.2 [pro]

AI Garden Design takes a photo of a front yard, backyard, or facade and re-renders the landscaping in a different style — modern, cottage, Japanese zen, desert xeriscape, tropical — while leaving the house itself alone. That constraint, "leave the house alone," turned out to be the whole engineering problem. Nobody wants a "redesign" that also invents a different roofline or moves the driveway.

The model choice: an edit model, not a fresh generation

This isn't text-to-image, it's image-to-image editing — specifically fal-ai/flux-2-pro/edit, a multi-reference, structure-preserving photoreal edit model. The uploaded photo is the reference image, and image_size: "auto" matches the output aspect ratio to the input instead of forcing a fixed size, which matters when the same house has to stay in the same position in the frame:

async function falRedesign(env, imageUrl, prompt) {
  const res = await falQueue(env, "fal-ai/flux-2-pro/edit", {
    prompt, image_urls: [imageUrl],
    image_size: "auto", output_format: "jpeg",
    safety_tolerance: "5",
  });
  const base = res.images && res.images[0] && res.images[0].url;
  if (!base) throw new Error("no image");
  return falUpscale(env, base);
}

safety_tolerance: "5" (the most permissive setting) exists for a boring reason: default safety filters on image-edit models are tuned for far broader content than "photo of a lawn," and even benign yard photos were tripping false positives without it.

Preserving structure is a prompting problem, not a masking problem

The obvious approach would be an inpainting mask — edit only the ground, leave the house region untouched pixel-for-pixel. This pipe doesn't do that; it relies entirely on prompt instructions. Every style prompt follows the same shape: describe the new landscaping, then explicitly state what not to touch:

modern:
  "Redesign only the outdoor yard and landscaping in a clean modern style: geometric " +
  "planting beds, ornamental grasses, minimalist concrete or corten-steel planters, a tidy " +
  "paved path, low-maintenance evergreen shrubs and a crisp lawn edge. Keep the house, walls, " +
  "windows, roof, driveway, fences and property boundaries exactly unchanged." + REAL

REAL is a shared suffix appended to every style prompt — a push toward "real DSLR architectural photograph" plus an explicit reject list: no illustration, no cartoon, no Unreal-Engine-style 3D render, no plastic CGI sheen. Landscape imagery lives or dies on "does this look like a real photo of my actual house," so the negative instructions do as much work as the positive description.

Same finishing-pass trick as the rest of the fal.ai pipes

After the edit model returns a base render, it runs through fal-ai/clarity-upscaler again — low creativity (0.3), moderate resemblance (0.75) — purely for sharpness, with a try/catch that falls back to the un-upscaled base on any failure so a paid render is never lost to a flaky second call:

async function falUpscale(env, imageUrl) {
  try {
    const res = await falQueue(env, "fal-ai/clarity-upscaler", {
      image_url: imageUrl, upscale_factor: 2, creativity: 0.3, resemblance: 0.75,
      num_inference_steps: 18,
      prompt: "masterpiece, best quality, highres, sharp, photorealistic garden photograph",
    }, 60);
    return (res.image && res.image.url) || imageUrl;
  } catch (e) { return imageUrl; }
}

The submit-then-poll helper (falQueue) is fully generic — the same function submits to flux-2-pro/edit, clarity-upscaler, and backs the text add-on below.

The upsell: an LLM-written landscaping brief, gated by the same grant

The Pro tier ($19.99, 25 renders across all five styles) unlocks /api/brief, which calls Claude (claude-haiku-4-5) to write a plant list, a rough budget, and a contractor-ready scope of work. It reuses the same HMAC grant verification as the image endpoint, plus one extra check — the tier itself has to have brief: true:

const tier = TIERS[grant.sku];
if (!tier) return json({ error: "Unknown tier" }, 400);
if (!tier.brief) return json({ error: "Design brief is included with the Pro pack only" }, 403);

Feature-gating between Starter ($9.99, 2 styles) and Pro ($19.99, 5 styles + brief) is just a boolean flag on a shared TIERS config, checked in-line at request time — not a separate SKU-handling code path.

Live: https://ai-garden-design.pages.dev/

Fusing Two Parents Into One Face: Building an Identity-Preserving AI Baby Generator on Cloudflare Functions

KunStudio — Sun, 19 Jul 2026 13:22:59 +0000

Fusing Two Parents Into One Face: Building an Identity-Preserving AI Baby Generator on Cloudflare Functions

BabyGlimpse takes a photo of each parent and generates AI baby portraits across three age stages (newborn, toddler, child). The interesting problem wasn't "call an image model" — it was fusing two separate faces into one coherent identity, inside the wall-clock limits of a serverless function.

The model: PuLID, not a generic text-to-image call

Describing both faces in a text prompt doesn't work — text can't carry facial identity with any fidelity. This pipe uses fal-ai/pulid, an identity-preserving diffusion model that accepts actual reference images. Both parent photos go in as reference_images, and id_mix tells the model to blend the two identities into one new face instead of copying either one:

const submit = await fetch("https://queue.fal.run/fal-ai/pulid", {
  method: "POST",
  headers: { Authorization: "Key " + env.FAL_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    reference_images: [{ image_url: refA }, { image_url: refB }],
    prompt, image_size: "square_hd",
    num_inference_steps: 8, guidance_scale: 1.2,
    id_scale: 0.8, id_mix: true, mode: "fidelity",
    negative_prompt: NEG, seed,
  }),
});

fal-ai/pulid runs on SDXL-Lightning, tuned for very few steps (4-8) — more steps don't improve a Lightning checkpoint, they just burn time. id_scale: 0.8 sets how strongly the result must resemble both reference identities versus the text prompt; mode: "fidelity" biases PuLID toward keeping recognizable features from both parents.

The finishing pass: a second model call kills the "AI plastic" look

An 8-step Lightning output is identity-accurate but lacks fine skin texture. Rather than push more steps into a model tuned for few steps, the output goes through fal-ai/clarity-upscaler as a separate pass with a real (non-Lightning) CFG — low creativity, high resemblance, so it enhances texture without drifting from the identity PuLID already locked in:

const submit = await fetch("https://queue.fal.run/fal-ai/clarity-upscaler", {
  method: "POST",
  headers: { Authorization: "Key " + env.FAL_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    image_url: imageUrl, upscale_factor: 2,
    creativity: 0.3, resemblance: 1.4,
    guidance_scale: 4, num_inference_steps: 18,
    negative_prompt: "cartoon, cgi, 3d render, plastic skin, waxy skin, ...",
  }),
});

If this pass fails or times out, the code falls back to the un-upscaled base image — a paid job should never come back empty because a secondary enhancement step had a bad day.

Why the browser drives the loop, not the server

fal.run is an async queue: submit a job, get a status_url/response_url pair, poll until status === "COMPLETED". A full batch (three age stages, several images each, each with its own upscale pass) can take minutes — too long for one serverless invocation to own.

So the client owns the top-level loop. Each /api/generate call handles exactly one age stage; the browser calls it three times in sequence (newborn → toddler → child), updating a progress bar between calls. Each Cloudflare Pages Function invocation only has to survive polling for one stage's images, keeping every request inside the platform's CPU/time budget instead of babysitting one giant multi-minute request.

Payment: a signed grant instead of a database

There's no database here. After PayPal capture succeeds server-side, capture-order.js issues an HMAC-signed grant — a base64 JSON payload {o, sku, n, exp} plus a SHA-256 signature via the Web Crypto API:

async function sign(secret, payload) {
  const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret),
    { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
  const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(payload));
  return btoa(String.fromCharCode(...new Uint8Array(sig))).replace(/=+$/, "");
}

/api/generate re-derives the same signature and rejects the request if it doesn't match, or if exp has passed (grants last 6 hours). That's the entire access-control layer for a paid API calling a metered third-party image model — no session store, no order table, just a signed token the browser carries between requests. Pricing itself lives server-side in one TIERS object; the client never gets to influence what PayPal actually charges.

Live: https://ai-baby-generator.pages.dev/

Why a cancellation-script generator is a lookup table and a template matrix, not an LLM call

KunStudio — Sat, 18 Jul 2026 13:22:26 +0000

Why a cancellation-script generator is a lookup table and a template matrix, not an LLM call

The obvious way to build "write me a cancellation message" is to send the service name and a goal to a language model and let it generate the paragraph. I built Cancel Helper the other way — a known-service lookup table plus a fixed template matrix — because the moment the output starts citing consumer-protection law, "usually right" stops being good enough.

A known-service table with fuzzy lookup

Common services (streaming, gyms, software subscriptions) get an entry in a KNOWN table: which channel actually works for that provider (web form vs. a phone line vs. in-person only), a provider-specific gotcha worth knowing before you start, and — for gym contracts especially — the retention tactic to expect. lookupKnown() normalizes whatever the user typed (lowercased, + expanded to "plus", punctuation stripped) and tries an exact slug match first, then falls back to substring/keyword matching, so "Netflix", "netflix premium", and "NETFLIX" all resolve to the same entry without the user having to type the name exactly right. Each known entry also carries a three-tier difficulty rating, shown as a small pip meter, so someone dealing with a gym contract knows upfront it's a harder path than cancelling a streaming subscription in an app.

The template matrix instead of a per-request generation call

buildScript() takes three inputs — goal (cancel / refund / cut short a signup trial / reach a human), channel (phone / email / chat / app-store), and tone (plain / cites-the-law) — and assembles one of a fixed set of reviewed paragraphs by string concatenation. Nothing here is generated per request; every combination is a known, previously-read piece of text. The store channel gets a special case regardless of goal: App Store and Google Play subscriptions have to be cancelled in the store itself, because the merchant on the other end of the message has no ability to stop that billing even if they wanted to — a script politely asking a company to cancel a charge it doesn't control would just waste the user's time.

Why the legal-tone branch is the actual reason not to use a model here

The tone toggle's second option cites specific consumer-protection law: the federal Restore Online Shoppers' Confidence Act, the Fair Credit Billing Act for disputed charges, and the FTC's complaint channel. That's exactly the category of claim a generative model will produce fluently and occasionally wrong — a plausible-sounding statute name, a slightly-off requirement, a citation that doesn't exist. A fixed string gets checked once, by a person, and then reused verbatim for every request instead of being reconstructed (and re-risked) every time. The upside of a small, owned piece of text over a model call isn't just consistency — it's that legal-adjacent copy can be kept current on purpose: the tool's own rights summary explicitly notes that the FTC's broader "click to cancel" rule was vacated by a federal court in mid-2025 and a revival attempt was underway as of early 2026, a detail that would already be stale if it were baked into a model's training data instead of a string that gets reviewed when the law changes.

Disclosing the affiliate step instead of hiding it

Past the script itself, there's a single goal-aware recommendation block — which partner it points to depends on whether the user picked cancel, refund, cut-short-a-trial, or reach-a-human — tagged rel="sponsored" and carrying a plain disclosure line stated in the block itself rather than buried in a footer: that a signup may earn a commission, that it never changes what the user pays, and that the partner isn't affiliated with the tool. Putting the disclosure in the same block as the pitch, instead of a separate terms page, was the easy part; not routing every goal to the same generic pitch was the part actually worth doing.

Live tool: https://cancel-helper.pages.dev/?utm_source=devto&utm_medium=backlink

Happy to go deeper on the fuzzy-lookup normalization or the goal/channel/tone template matrix if useful — drop a comment.

DEV Community: KunStudio

Building for Korean users: 5 quirks Western devs always get wrong

Building for Korean Users: 5 Quirks Western Devs Always Get Wrong

1. You're Ignoring Local Payment Methods Entirely

2. Your Phone Number Validation Is Broken

3. You're Not Handling the Real Name Registration Requirement

4. You Forgot About ISMS Compliance and Data Localization

5. You're Shipping Without Korean Language Support and It's Worse Than You Think

The Compounding Effect

é ©å å å å å… ç åº è ç ©æ »ç ¥ â ä å æ å®¢ç é ç§ ç

éŸ©å›½åŒ–å¦†å“å…ç¨Žåº—è´­ç‰©æ”»ç•¥ â€” ä¸­å›½æ¸¸å®¢çœé’±ç§˜ç±

Korean mobile-first architecture: lessons for SaaS founders

Why Korea's Mobile-First Mindset Matters for Your SaaS

Mobile-First Architecture, Not Mobile Optimization

Handling Intermittent Connectivity at Scale

State Management for Unreliable Networks

Database Design for Mobile Clients

Polish for Retention

The Real Cost

True Solar Time in Code: Your Clock Is Not the Sun

Correction 1: you are not standing on the zone meridian

Correction 2: the equation of time

Putting them together

The part that actually bites: the offset is an input, not a constant

JavaScript

Caveats

Lichun Is Not Always February 4: Computing Solar Terms With Newton's Method

A solar term is an angle, not a date

Step 1: apparent solar longitude

Step 2: Newton's method on a circle

Step 3: the part everyone forgets, delta-T

Step 4: guess the right year

Validation

Why bother

Why Naver/Kakao dominate Korean search and what global devs miss

The Korean Search Puzzle: Why Google Lost to Local Players

Naver's Ecosystem Lock-in: More Than Search

Kakao's Infrastructure Play: WeChat Before WeChat

Network Effects and Regulatory Protection

What Global Developers Miss

The Practical Framework for Korean Market Entry

The Math Behind a Late-Fee: Turning "Net 30" Into an Enforceable Number

The math behind a late-fee: turning "net 30" into an enforceable number

Simple interest, day-count, no compounding

The part everyone skips: the day-count is a UX problem, not a math problem

The reminder sequence is a state machine, not three templates

What I'd tell my past self

How Korean fintech (Toss / KakaoPay / PortOne) actually works under the hood

The Architecture Behind Korea's Fintech Giants: How Toss, KakaoPay, and PortOne Actually Work

Understanding the Three-Layer Korean Fintech Model

The Real-Time Clearing System: A-Wait-FTS

How KakaoPay Handles Money Without Being a Bank

PortOne's API Abstraction Layer

Security: Beyond HTTPS

Why Integration Speed Still Matters

Two SKUs, One Model: How Prompt Engineering Alone Creates a $19 vs $29 SOP Generator

Two SKUs, One Model: How Prompt Engineering Alone Creates a $19 vs $29 SOP Generator

One generation function, two tiers

The free preview is a capped, separate generation — not a truncated one

Fulfillment happens inline with payment capture — deliberately

Rendering the result without a Markdown library

Redesigning a Yard Without Touching the House: Structure-Preserving AI Image Edits With FLUX.2 [pro]

Redesigning a Yard Without Touching the House: Structure-Preserving AI Image Edits With FLUX.2 [pro]

The model choice: an edit model, not a fresh generation

Preserving structure is a prompting problem, not a masking problem

Same finishing-pass trick as the rest of the fal.ai pipes

The upsell: an LLM-written landscaping brief, gated by the same grant

Fusing Two Parents Into One Face: Building an Identity-Preserving AI Baby Generator on Cloudflare Functions

Fusing Two Parents Into One Face: Building an Identity-Preserving AI Baby Generator on Cloudflare Functions

The model: PuLID, not a generic text-to-image call

The finishing pass: a second model call kills the "AI plastic" look

Why the browser drives the loop, not the server

Payment: a signed grant instead of a database

Why a cancellation-script generator is a lookup table and a template matrix, not an LLM call

Why a cancellation-script generator is a lookup table and a template matrix, not an LLM call

A known-service table with fuzzy lookup

The template matrix instead of a per-request generation call

Why the legal-tone branch is the actual reason not to use a model here

Disclosing the affiliate step instead of hiding it

éŸ©å›½åŒ–å¦†å“å…ç¨Žåº—è´ç‰©æ”»ç•¥ â€” ä¸å›½æ¸¸å®¢çœé’±ç§˜ç±