DEV Community: Innocent Oyebode

One Support Call, Four Bugs: A Postmortem on Our AI Website Builder

Innocent Oyebode — Wed, 22 Jul 2026 14:00:00 +0000

I discovered a page on our customer's site that, at first glance, appeared to be a CSS bug. A hero section on her site had collapsed into a vertical sliver — a fashion-photo strip about 70 pixels wide, running the full height of the page, with her headline text wrapping into a column one word deep. Below it, the same broken hero repeated itself. The service cards that should have been on the page were gone.

It's the kind of screenshot that makes you assume you know the fix before you've looked at anything. A missing breakpoint, probably. Ship a CSS patch, close the ticket, move on.

I was wrong about the scope in almost every direction. By the time I was done, I'd found four separate bugs, two of them in completely different parts of the stack, and one of them entirely unrelated to the customer's report — a bug in the fix itself. This is a write-up of what actually happened, in the order I found it, because the order matters: each bug looked like the whole story until the next one showed up underneath it.

WebDigitize is an AI website builder for Nigerian small businesses — describe your business, get a live, editable, multi-page site in minutes, built on a drag-and-drop editor (Puck) with an AI layer on top. The incident touched the editor, the CSS layout system, the AI onboarding pipeline, and — in the least expected turn — the database ORM.

What I Saw

The customer had onboarded as a business selling physical products, added a handful of items to her catalog, and picked a general-purpose template rather than one of the commerce-flavored ones (it was the best fit for how she described her business). The site generated fine. Interestingly, I launched WebDigitize the previous day, so I was checking to see if there were new onboards. I saw her website on the dashboard and decided to check out each page. That was when I discovered the issue. I followed up with a call, and she confirmed exactly what happened. She went looking for her products on the live site and couldn't find them anywhere — no shop page, no product grid, nothing. So she opened the editor on her phone and started poking at the Services page, trying to see if the products were hiding in a section she hadn't looked at.

That's where the sliver came from. The page's hero component — a two-column "text on the left, full-height photo on the right" layout — had been dragged, on a touchscreen, into a three-column grid meant for service cards. A hero designed to occupy the full page width was now confined to one-third of it, and its internal CSS (a 7fr / 5fr grid split) rendered that third into two even-narrower slivers. The section had also been duplicated somewhere in the process, which is why I saw it twice.

The obvious read: "customer made a drag-and-drop mistake on mobile, CSS broke because nobody designed for a hero being squeezed that small." Both true. Also, not remotely the full story.

Bug One: A Split Hero With No Fallback For Its Own Container

The hero component's CSS looked like this before I touched it:

.hero-split {
  display: grid;
  grid-template-columns: minmax(0, 7fr) minmax(0, 5fr);
}

@media (max-width: 899px) {
  .hero-split {
    grid-template-columns: minmax(0, 1fr);
  }
}

A perfectly reasonable component, built around one assumption: the only thing that would ever make this hero narrow is a narrow viewport. On a phone, stack the columns. On a desktop, split them 7:5. That assumption is true right up until someone drops the component somewhere that isn't the full page width — inside a grid column, a sidebar, anywhere the component's rendered width is decoupled from the browser's.

@media queries answer "how wide is the viewport?" They cannot answer "how wide is this component, right now, wherever it's been placed?" That second question is what a component with an internal responsive layout actually needs answered, and for a long time, CSS had no good way to ask it.

The fix is a container query — CSS that responds to an element's own size rather than the viewport's:

.hero-section {
  container-type: inline-size;
}

@container (max-width: 899px) {
  .hero-split {
    grid-template-columns: minmax(0, 1fr);
  }
}

Same breakpoint, same fallback layout — the difference is what's being measured. Now, if this hero ever ends up somewhere narrow, for any reason, at any nesting depth, it stacks gracefully instead of dividing an already-small box into two useless columns. We didn't design this fix for "what if someone drags a hero into a grid cell" specifically — we designed it for "this component should never assume it owns the full viewport," which is the more durable version of the same idea. The next unanticipated place a hero ends up will handle itself the same way.

If you maintain any component library with a component that has an internal responsive layout, this is worth auditing today: every @media-based internal layout in a component that could ever be nested is a latent version of this bug, just waiting for someone to place the component somewhere you didn't design for.

Bug Two: The Editor Let Her Do This At All

The CSS fix makes the outcome of a hero-in-a-grid drop survivable. It doesn't answer the more basic question: should our drag-and-drop editor have allowed that drop in the first place?

No. A full-width hero, a call-to-action banner, a page section — these are page-level compositional elements. They don't have a sensible meaning inside a three-column card grid, any more than it makes sense to put a <html> tag inside a <div>. The editor had no opinion on this; every block type was a valid child of every container type, and Puck's DropZone component happily accepted the drag.

Puck (and most drag-and-drop editors) probably support allow/disallow lists per drop zone for exactly this reason:

const PAGE_LEVEL_ONLY = ["Section", "EditorialHero", "CTABanner", "StatStrip"];

<DropZone zone="content" disallow={PAGE_LEVEL_ONLY} />;

Every Section/Grid/Flex container's drop zone in our editor now rejects those block types outright. If you drag a hero toward a grid cell, it simply won't drop there — no error message needed, because the interaction itself now communicates the constraint. This is the general lesson: a structural invariant your data model relies on ("heroes live at the page level") should be enforced by the tool that produces the data, not documented and hoped for. I'd implicitly assumed nobody would ever nest a hero in a grid, which was true until the first person who tried.

There's a second layer here, though, that the CSS fix and the drop-zone fix both dodge: this specific mis-drop happened on a phone. Precision drag-and-drop — picking up a small element, dragging it across a cramped viewport, dropping it into the correct one of several adjacent, similarly-sized targets — is a genuinely hard interaction on a touchscreen, even with every guardrail we can add. We could keep discovering edge cases in what happens when a block-based editor gets used with a thumb on a 6-inch screen, or we could accept that this class of editor isn't a good mobile interaction at all and say so plainly:

const isTooNarrow = useMediaQuery("(max-width: 767px)");

if (isTooNarrow) {
  return <OpenOnDesktopMessage />;
}

The editor now blocks editing below a viewport-width threshold with a message pointing the owner at a larger screen — your site stays exactly as it is; you just can't drag things around from a phone. This isn't a workaround for the bug we just fixed; it's an acknowledgement that some tools have a form factor they're honestly built for, and pretending otherwise generates support tickets forever.

Bug Three: The Products That Were Never There

Here's where the incident stopped being a UI bug and became something more interesting — and where I have to admit our first fix was aimed at a symptom.

Reread the timeline: the customer didn't set out to break the Services page. She was hunting for products that had never appeared on her site at all, from the moment it was generated, even before she ever touched the editor. The drag-and-drop mishap was a downstream consequence of a completely separate failure: her site was never given anywhere to sell products in the first place.

Our generation pipeline has two paths. The original path calls the AI to generate an entire page's structure from scratch — and it has always included a check: does this business sell products? If yes, does the generated site actually contain a page to sell them on? If not, build one deterministically (a heading plus a full-catalog product grid, no AI needed for something this mechanical) and wire it into navigation.

The second path is newer and exists for cost and speed: rather than asking the AI to invent a page structure from nothing, I clone one of a set of hand-designed "flagship" templates (a fashion boutique layout, a restaurant layout, a general-purpose services layout) and only ask the AI to fill in twenty or thirty text slots — five to ten times cheaper than full generation, and the design quality of a human-built template rather than an LLM's best guess. This is the path our customer went through.

The bug: the "does this business sell products, and if so, does the site have somewhere to sell them" check lived entirely in the first path. The second path never inherited it. Some flagship templates (fashion, food) do include commerce blocks by design. Others — general, services, events, creative — don't, because they're built for businesses that don't sell physical products. Nothing in the pipeline cross-checked "this owner said she sells products" against "this template has zero commerce blocks." Two individually reasonable systems — a store-detection check built for one generation path, a template library built for a different one — had simply never been asked to talk to each other, because the second path didn't exist yet when the first check was written.

Concretely, in pseudocode, the gap looked like this:

def generate_site(brief):
    if brief.template_id:
        # Fast path: clone template, AI fills text slots. No commerce check.
        return generate_from_template(brief.template_id, brief)
    else:
        # Slow path: full AI generation, WITH a commerce check.
        site = generate_full_ai(brief)
        if brief.sells_products and not has_shop_page(site):
            site = add_shop_page(site)
        return site

The fix moves that check to the one place both paths already pass through — right before either result is saved:

def generate_site(brief):
    if brief.template_id:
        site = generate_from_template(brief.template_id, brief)
    else:
        site = generate_full_ai(brief)

    if brief.sells_products and not has_shop_page(site):
        site = add_shop_page(site)
    return site

One line moved from inside a branch to after both branches. The lesson generalizes past this one bug: a check that depends on a cross-cutting fact about the business ("does this business sell things?") needs to live at the single point where all content-generation paths converge, not be duplicated — or worse, present in only one of them — per path. Every time you add a new way to produce the same kind of output, audit which invariants the old paths guaranteed and confirm the new one guarantees them too. It's an easy thing to miss precisely because both paths were separately correct in isolation; the bug only exists in the gap between them.

Bug Four: Fixing Production Broke My Fix First

With all three root causes understood, the actual data repair was almost the easy part — pull the mangled hero back out to the page level, drop the duplicate, remove the sections the mishap had gutted, and add the shop page the customer should have had from day one. I wrote it as a script, ran it against a copy of the affected data locally, watched it produce exactly the output we expected, and handed off the command to run in production.

It failed immediately, with a stack trace from deep inside SQLAlchemy that had nothing to do with any of the logic I'd written:

sqlalchemy.exc.InvalidRequestError: When initializing mapper Mapper[User(users)],
expression 'BusinessPaymentAccount' failed to locate a name ('BusinessPaymentAccount').

The script imported exactly two model classes — the Site and Product tables it actually needed. That turned out to be the whole problem. SQLAlchemy declares relationships between models by string, so they can reference each other without circular Python imports:

class User(Base):
    payment_account: Mapped["BusinessPaymentAccount"] = relationship(
        "BusinessPaymentAccount", back_populates="user"
    )

That string only resolves if BusinessPaymentAccount has actually been imported somewhere in the running process — not used, just imported, so the class exists in SQLAlchemy's shared mapper registry. And crucially, the first time any query runs, SQLAlchemy configures every mapper it knows about, not just the one you queried — because relationships can point in any direction, it has to make sure the whole graph resolves before it trusts any of it. The script imported Site and Product. Site has a foreign key relationship into User. User has a relationship string-pointing at BusinessPaymentAccount, which nothing in my script had ever imported. First query, mapper configuration walks the whole graph, hits a name it's never heard of, throws.

The live FastAPI application never hits this because one large router module happens to import nearly every model in the app across its many endpoints — by the time any request is served, every relationship target has been imported as a side effect of something completely unrelated. That's not a design decision anyone made on purpose; it's an accident of the app being big enough that everything gets pulled in eventually. A small, standalone script doesn't get that for free — it only has what it explicitly imports.

Once I knew what to look for, I found the same latent bug already sitting in the Alembic migration environment, which manually lists model imports for exactly this reason — and the list was stale, missing four models added since it was last touched. It hadn't broken yet, only because no migration had happened to touch a relationship pointing at one of the missing four. That's the uncomfortable part of this class of bug: it's not "wrong," it's "correct until the next person changes something unrelated."

The fix, instead of hand-maintaining another list that will drift the same way:

import importlib, pkgutil
import app.models as models_pkg

def import_all_models():
    for mod in pkgutil.iter_modules(models_pkg.__path__):
        importlib.import_module(f"{models_pkg.__name__}.{mod.name}")

Call it once, before any query, in any standalone script. It doesn't need to know which models matter — it imports the whole package, every time, so the mapper registry is always complete regardless of which relationships happen to exist this month. The lesson: if correctness depends on "everything got imported somewhere," make that automatic and exhaustive, not a manually maintained list. A list like that isn't wrong when it's written; it's a countdown to the next omission.

Writing a Repair Script You Can Trust

One more thing worth calling out, because it's a pattern I'd recommend for any one-off production data fix: I wrote the repair logic as a pure function — data in, corrected data out, no database access inside it at all — and wrote a test first, hand-constructing a data structure that reproduced the exact damage (hero in a grid, duplicated section, orphaned empty containers) before writing a single line of the fix.

def repair_page(puck_data: dict) -> tuple[dict, list[str]]:
    """Pure transform: returns (fixed_data, human_readable_log). No I/O."""
    ...

def test_repairs_hero_dragged_into_grid():
    broken = build_known_broken_fixture()
    fixed, log = repair_page(broken)
    assert fixed["content"][0]["type"] == "EditorialHero"  # hoisted back to top level
    assert len(log) > 0
    # running it again should be a no-op
    again, log2 = repair_page(fixed)
    assert again == fixed and not log2

That last assertion — repair twice, expect the second run to do nothing — caught a real bug on the first attempt (an empty container removal wasn't marking its parent section as needing re-evaluation, so a heading-only section survived one pass and was only caught on a second). Cheap to check, and it meant I trusted the script's idempotency before it ever touched a live row. The database-facing wrapper around this pure function only had two responsibilities: fetch the record, and — behind an explicit --apply flag, off by default — write it back. Every run without that flag prints exactly what would change and touches nothing. For a script that runs once, against production data, days after the incident that necessitated it, that's not overkill.

What I Shipped

CSS: the split-hero layout responds to its own rendered width via a container query, with the viewport-based media query kept as a belt-and-suspenders fallback for browsers without container query support.
Editor: page-level blocks (heroes, CTA banners, stat strips) are now disallowed as children of Section/Grid/Flex drop zones — the mis-drop can't happen again, on any device.
Editor, mobile: drag-and-drop editing is blocked below a viewport-width threshold, with a plain-language message pointing the owner to a larger screen.
Generation pipeline: the "does this business sell products, and does the site have somewhere to sell them" check now runs after both generation paths, not inside only one of them.
Tooling: a reusable "import every model module" helper for standalone scripts, so the SQLAlchemy mapper-registry gap can't silently resurface in the next one-off script — or, we hope, in the Alembic environment that had the same latent issue.
Data: the customer's affected page was repaired, and her shop page was added via a pure-function, test-first, dry-run-by-default script.

Takeaways

A component with an internal responsive layout should respond to its own rendered size, not the viewport. @media answers the wrong question the moment a component can be nested anywhere other than the page's full width; container queries answer the right one.
Enforce structural invariants in the tool, not in documentation or hope. If your data model assumes X can never contain Y, make the editor refuse that drop rather than discovering the assumption was implicit.
Some interactions don't degrade gracefully to a smaller form factor — say so explicitly. Blocking drag-and-drop editing on a phone, with a clear message, beats an editor that technically "works" on mobile but produces this class of damage.
A cross-cutting business rule needs one home, at the point where all paths converge — not one copy per code path. Every time you add a new way to produce an existing kind of output, audit whether it inherited every invariant the old paths guaranteed.
If correctness depends on "everything got imported somewhere," make that automatic, not a hand-maintained list. Manually maintained import lists (or any similar "remember to register X" pattern) are correct when written and wrong on a schedule you don't control.
Write one-off production data repairs as pure functions, test-first, against a fixture that reproduces the actual damage — and make them idempotent and dry-run-by-default. The five extra minutes this takes is cheaper than a second incident caused by the fix for the first one.

None of these four bugs would have been caught by looking only at the screenshot we started with. Each one only became visible by asking "why did this actually happen", one layer deeper than the last — and the layer that mattered most to the customer (her missing products) was the one furthest from what she'd actually reported.

WebDigitize is live. If you're building on top of a drag-and-drop editor or running an AI generation pipeline in production, I'd be curious what invariant-enforcement patterns you've settled on — drop a comment below.

Lessons from Embedding an LLM Inside a Drag-and-Drop Editor

Innocent Oyebode — Wed, 15 Jul 2026 14:00:00 +0000

When you integrate an AI generation step into a drag-and-drop editor, you face a problem that is rarely discussed in LLM tutorials: the model's output must be structurally valid, not just semantically good. A hallucinated CSS class name is a style regression. A hallucinated prop key in an editor schema is a broken component.

This is a writeup of what I learned building WebDigitize, an AI-powered website generator and editor for Nigerian small businesses, using Puck as the editor layer.

What Puck Expects

Puck stores page state as a JSON document:

{
  "root": { "props": {} },
  "content": [
    {
      "type": "HeroSection",
      "props": {
        "headline": "Fresh Bread, Delivered Daily in Lagos"
      }
    }
  ],
  "zones": {}
}

Each entry in content maps to a React component registered in Puck's config:

const config: Config = {
  components: {
    HeroSection: {
      fields: {
        headline: { type: "text" },
        subheadline: { type: "text" },
        ctaLabel: { type: "text" },
        ctaHref: { type: "text" },
      },
      render: ({ headline, subheadline, ctaLabel, ctaHref }) => (
        <section>
          <h1>{headline}</h1>
          <p>{subheadline}</p>
          <a href={ctaHref}>{ctaLabel}</a>
        </section>
      ),
    },
  },
};

The critical insight: Puck only renders props defined in fields. If the AI emits headlineText instead of headline, the component renders silently with undefined. No error. No warning. An invisible field.

The Schema Representation Problem

Your LLM knows nothing about your Puck config. You need to tell it what is valid. The naive approach is to describe your components in prose:

"The HeroSection component takes a headline, a subheadline, a CTA label, and a CTA href."

This works for simple cases and fails for complex ones. If you have 15 components, each with 4–8 fields, prose descriptions become ambiguous, and the model drifts toward invented field names that sound plausible.

The approach that worked: represent your component schemas as a compact formal notation in the system prompt.

=== PUCK BLOCK SCHEMAS (STRICT) ===
Only use the exact prop keys listed. No extra keys. No variations.

HeroSection:
  headline: string           (max 60 chars — punchy, specific to this business)
  subheadline: string        (max 120 chars)
  ctaLabel: string           (max 30 chars)
  ctaHref: string            (WhatsApp link preferred; format: https://wa.me/{number})

ServicesSection:
  title: string
  services: Array<{
    icon: "star" | "check" | "bolt" | "heart" | "shield" | "phone"
    title: string            (max 40 chars)
    description: string      (max 100 chars)
  }>                         (2–4 items, no more)

ContactSection:
  address: string
  phone: string              (must match brief — do not invent)
  hours: string              (format: "Mon–Sat, 8am–6pm")
  mapEmbedQuery: string      (Google Maps query string, e.g. "Chicken Republic Ikeja Lagos")

Key decisions in this notation:

Pipe-separated enums ("star" | "check" | ...) are extremely effective — the model treats them as a closed set.
Inline constraints (max 60 chars) prevent verbose fields that break layouts.
Explicit notes (must match brief — do not invent) address the most common semantic failures.

System Prompt vs User Message

I spent some time debugging why the critic pass kept ignoring my schema constraints. The answer was placement.

Schema in the user message:

[System]: You are a web design assistant. Output only valid JSON.
[User]:   Generate a home page for Mama Titi's Kitchen.
          Here are the allowed block schemas: ...
          Business details: ...

In multi-turn conversations (generation → critic → refinement), the schema in the user message is treated as part of the task context that can be "overridden" by subsequent turns. The critic saw new information in its turn and occasionally invented prop names that were not in the original schema.

Schema in the system prompt:

[System]: You are a web design assistant. Output only valid JSON.
          === PUCK BLOCK SCHEMAS (STRICT) ===
          HeroSection: ...
          [all schemas]
[User]:   Generate a home page for Mama Titi's Kitchen.
          Business details: ...

The system prompt is treated as a persistent context across all turns. Schema violations dropped to nearly zero. The model seems to correctly understand that system prompt constraints are inviolable while user message constraints can flex.

Validating Output at the Boundary

Even with strict prompting, I added a validation step before storing any generated content:

ALLOWED_BLOCKS = {
    "HeroSection": {"headline", "subheadline", "ctaLabel", "ctaHref"},
    "ServicesSection": {"title", "services"},
    "ContactSection": {"address", "phone", "hours", "mapEmbedQuery"},
    # ...
}

def validate_puck_content(content: dict) -> list[str]:
    errors = []
    for block in content.get("content", []):
        block_type = block.get("type")
        if block_type not in ALLOWED_BLOCKS:
            errors.append(f"Unknown block type: {block_type}")
            continue
        allowed_keys = ALLOWED_BLOCKS[block_type]
        for key in block.get("props", {}):
            if key not in allowed_keys:
                errors.append(f"{block_type}: unknown prop '{key}'")
    return errors

When validation fails, I log the raw output and retry generation with an amended prompt that includes the specific error:

if errors:
    additional_constraint = f"CRITICAL: Previous attempt used invalid props: {errors}. Fix these."
    return await generate_with_retry(brief, page_type, extra_constraint=additional_constraint)

In practice, the retry only triggers for about 2% of generations.

The Array Prop Problem

Arrays are the most reliably broken output format. Consider services: Array<{icon, title, description}>. The model produces:

"services": [
  {"icon": "star", "title": "Fresh Bread", "description": "Baked daily"},
  {"icon": "check", "title": "Fast Delivery", "description": "Within 2 hours"}
]

This is valid. But then on a retry or critic pass, I have seen:

"services": {
  "items": [...],
  "count": 2
}

Or:

"services": [
  {"icon_name": "star", "service_title": "Fresh Bread", "text": "Baked daily"}
]

The second failure (renamed keys inside array items) is invisible without deep validation. I extended the validator to recurse into array items:

SERVICES_ITEM_KEYS = {"icon", "title", "description"}

def validate_services(items):
    for i, item in enumerate(items):
        for key in item:
            if key not in SERVICES_ITEM_KEYS:
                return [f"services[{i}]: unknown key '{key}'"]
    return []

Rich Text: The Unexpected Footgun

One of the blocks — a ContentBlock for long-form text — accepted a body field that was supposed to be a Puck rich text value (a Lexical editor serialised state, not a plain string).

I made the mistake of exposing this to the AI. The model produced beautiful-looking text, but it was a plain string. The Lexical editor expected an object. The result was a crash on the editor load that only appeared when the user tried to edit the block.

The fix: never ask an LLM to produce rich text editor state. Instead, the ContentBlock accepts a bodyText: string prop. A useEffect in the component converts it to a Lexical initial state on first render. The AI never touches the editor's internal format.

Structuring the Puck Config for AI-Friendliness

After building this, I restructured the Puck config with AI consumers in mind:

Use consistent naming conventions. All text fields are string types named with a noun (headline, subheadline, address). All boolean toggles start with show (showCta, showImage). The model learned these conventions quickly and stopped inventing alternatives.
Keep array items flat. Nested object arrays are reliable. Arrays of arrays are not. If you need complex nested structures, flatten them at the schema layer.
Provide default prop values in the component. If ctaHref is missing, the component should gracefully render without a CTA link rather than throwing. This makes partial AI output survivable.
Separate "AI-generated" fields from "user-configured" fields. Fields like backgroundImage and colorScheme are set by the user through the visual editor, never by the AI. Keeping these out of the generation schema prevents the model from guessing colours or image URLs, which it consistently does poorly.

The Rendering Architecture

Puck renders in two modes in WebDigitize:

Editor mode (<Puck config={config} data={data} />) — used in the dashboard, full interactive editing
Render mode (<Render config={config} data={data} />) — used on public-facing site pages, no editing chrome

Both modes use the same config and data. When the AI generates content and stores it, it is immediately renderable on the public site. When the user opens the editor, they see the AI output in the Puck canvas, ready to drag, drop, and edit.

This single-schema-serves-both-modes design is the most important architectural decision. It means the AI, the editor, and the public renderer are all working with the same contract.

Takeaways

Formal schema notation in the system prompt outperforms prose descriptions for structured output tasks.
System prompt beats user message for persistent constraints across multi-turn generation pipelines.
Validate at the boundary, not at render time. Silent failures are the enemy.
Never send rich text editor state formats to an LLM. Accept plain strings and convert at the component layer.
Design your block schemas with AI consumers in mind from the start — consistent conventions, flat structures, clear defaults.

Have you run into schema validation problems with LLM output in your own projects? I'd love to hear how you solved it.

How I Built a Multi-Page AI Website Generator for Nigerian SMBs — Architecture, LLM Prompting, and Lessons Learned

Innocent Oyebode — Wed, 15 Jul 2026 11:00:00 +0000

The Problem

Most Nigerian small businesses have no web presence at all. When they do get a website, it is usually a stale brochure-ware page that took a freelancer three weeks to deliver and costs ₦150,000 they could not really afford. The freelancer is long gone; the business owner cannot update a word.

The conventional "website builder" alternatives — Wix, Squarespace, GoDaddy — are not built for Nigeria. Payment integration means Stripe (not available to Nigerian merchants directly). Domain registration defaults to USD. The templates look like they belong in Manchester, not Maiduguri. Even if the interface were perfect, a bakery owner in Lagos should not need to understand the difference between a hero section and a call-to-action button to get a professional website.

I built WebDigitize to solve this end-to-end: a platform where a Nigerian business owner fills in a short onboarding form — business name, type, brief description, preferred visual style, phone, city — and receives a complete, multi-page, styled website with a live subdomain and e-commerce capability within minutes.

The hard part is step one: taking those five fields and producing a website that looks like a human designed it.

The Architecture at a Glance

Next.js 15 (App Router)  ←→  FastAPI (Python)  ←→  PostgreSQL (Neon)
                                     ↓
                             Anthropic Claude API
                                     ↓
                          Background task queue (asyncio)
                                     ↓
                             Puck JSON stored in DB
                                     ↓
                    Cloudflare for SaaS (custom domains)
                          Cloudflare R2 (media)
                             Paystack (billing)

The core website builder is Puck — an open-source React drag-and-drop editor. Puck stores page content as a JSON document describing a tree of typed blocks (HeroSection, FeaturesGrid, TestimonialCard, etc.). The AI's job is to generate that JSON document, filled with content that makes sense for the specific business.

The Generation Pipeline

Step 1: Business Brief

The onboarding wizard collects:

interface BusinessBrief {
  businessName: string;
  businessType: string;       // "Restaurant", "Law firm", "Tech startup", etc.
  description: string;        // free-text, up to ~300 chars
  style: "modern" | "classic" | "bold" | "minimal";
  city: string;
  phone: string;
  whatsapp?: string;
  instagram?: string;
  services?: string[];        // optional structured list
}

The style field maps to a concrete design token set — font pairings, border radii, colour palette — so the AI never needs to reason about hex codes. It picks from four named personalities; the platform fills in the rest.

Step 2: Home Page Generation (Always Async)

Generation happens in a FastAPI background task so the HTTP response returns immediately and the user sees a progress screen:

@router.post("/onboarding")
async def complete_onboarding(
    body: OnboardingRequest,
    background_tasks: BackgroundTasks,
    ...
):
    site = create_site(db, user, body)
    background_tasks.add_task(generate_site_content, site.id, body)
    return {"status": "generating", "site_id": site.id}

The generation function calls Claude with a carefully structured system prompt and returns a Puck JSON document:

async def generate_home_page(brief: BusinessBrief) -> dict:
    system = """
You are a professional web designer generating page content for Nigerian businesses.
Output ONLY valid JSON conforming to the Puck content schema.
Never include placeholder text like "Lorem ipsum".
All phone numbers must use the Nigerian format provided.
Business hours should reflect typical Nigerian business culture (Mon-Sat, 8am-6pm).
    """

    user_message = f"""
Generate a home page for:
Business name: {brief.business_name}
Type: {brief.business_type}
Description: {brief.description}
City: {brief.city}
Phone: {brief.phone}
Style preference: {brief.style}

The page must include (in order):
1. HeroSection — compelling headline + one-sentence subheadline, no generic filler
2. ServicesSection — 3–4 services inferred from the business type and description
3. WhyUsSection — 3 trust signals realistic for this business category
4. TestimonialsSection — 2 synthetic but realistic-sounding customer testimonials
5. CTASection — contact or WhatsApp prompt
6. ContactSection — address (city), phone, business hours

Output the full Puck JSON object only. No explanation.
    """

    response = await anthropic_client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=4096,
        system=system,
        messages=[{"role": "user", "content": user_message}],
    )
    return json.loads(response.content[0].text)

Step 3: The Design Critic Pass

Raw LLM output can be technically valid JSON but weak content — headlines that are too generic, services that do not match the business type, testimonials that read as obviously fake. After the first generation pass, a second prompt acts as a critic:

async def critic_review(brief: BusinessBrief, draft: dict) -> dict:
    critique_prompt = f"""
Review this website draft for {brief.business_name} ({brief.business_type}).

Check for:
1. Headlines that are too generic ("Welcome to our website") — rewrite them to be specific
2. Services that don't match the business — fix or remove
3. Testimonials that sound fake or unnatural — make them read like real Nigerian customers
4. Any western cultural assumptions (e.g., "Schedule a meeting" for a street-food business) — localise
5. Missing local context (area of {brief.city}, local terminology)

Return the improved Puck JSON. If the draft is already strong, return it unchanged.
    """

    response = await anthropic_client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=4096,
        messages=[
            {"role": "user", "content": critique_prompt},
            {"role": "assistant", "content": json.dumps(draft)},
            {"role": "user", "content": "Improve the draft based on the criteria above. Return only JSON."},
        ],
    )
    return json.loads(response.content[0].text)

This two-pass approach consistently produces noticeably better output than a single long prompt, at the cost of one extra API call per page.

Step 4: Sub-Page Generation (Paid Plans)

Growth and Pro plan customers get full multi-page sites. After the home page is stored, additional pages are generated in parallel:

async def generate_subpages(site_id: int, brief: BusinessBrief):
    pages_to_generate = ["about", "services", "contact"]
    tasks = [generate_page(brief, page) for page in pages_to_generate]
    results = await asyncio.gather(*tasks, return_exceptions=True)
    for page, result in zip(pages_to_generate, results):
        if not isinstance(result, Exception):
            store_page(site_id, page, result)

Each page type has its own prompt, but they share the same critic pass. The about page prompt, for example, explicitly asks for the origin story implied by the business description, not a generic "About Us" template.

Step 5: The Shop Page (Deterministic, No AI)

The e-commerce shop page is rendered entirely from structured product data in the database — no LLM involved. This was a deliberate decision: the shop layout needs to be perfectly predictable, support filtering and pagination, and respond to real-time inventory. Asking an LLM to generate a page that also needs to execute logic is a footgun.

Instead, the shop is a fixed Puck-compatible layout component (ShopPage) that is always rendered in position regardless of what the AI generated. The block receives a siteId prop and fetches live product data client-side.

The Puck JSON Schema Problem

The hardest part of this project was not prompting — it was schema design.

Puck's content format looks like this:

{
  "root": { "props": {} },
  "content": [
    {
      "type": "HeroSection",
      "props": {
        "headline": "Fresh Bread, Delivered Daily",
        "subheadline": "Abuja's favourite artisan bakery since 2018",
        "ctaLabel": "Order via WhatsApp",
        "ctaHref": "https://wa.me/2348012345678"
      }
    }
  ],
  "zones": {}
}

Each block type has its own props shape. The LLM must produce valid prop keys and value types — if it hallucinates a key that does not exist in the component definition, the block fails to render silently.

My solution was to include a condensed block schema in the system prompt:

Block schemas (strict — use ONLY these keys):

HeroSection:
  headline: string (max 60 chars, punchy)
  subheadline: string (max 120 chars)
  ctaLabel: string (max 30 chars)
  ctaHref: string (WhatsApp link if phone available, else "#contact")
  backgroundImage?: string (omit — will be set by user)

ServicesSection:
  title: string
  services: Array<{ icon: "star"|"check"|"bolt"|"heart"|"shield"|"phone", title: string, description: string }>
  (max 4 items)

...

Keeping the schema in the system prompt (not the user message) made it sticky across multi-turn critic passes. I initially put it in the user message, and the critic pass would occasionally "forget" a constraint and hallucinate props.

Handling Invalid JSON

Claude is very reliable at producing valid JSON when instructed, but I still wrap every parse in a retry loop with exponential backoff:

async def generate_with_retry(brief, page_type, max_attempts=3):
    for attempt in range(max_attempts):
        try:
            raw = await call_claude(brief, page_type)
            # Strip markdown code fences if present
            cleaned = re.sub(r'^```

json\n?|

```$', '', raw.strip(), flags=re.MULTILINE)
            return json.loads(cleaned)
        except json.JSONDecodeError:
            if attempt == max_attempts - 1:
                raise
            await asyncio.sleep(2 ** attempt)

The markdown fence stripping handles the most common failure mode — Claude occasionally wraps JSON in json even when told not to.

Image Sourcing

Generated pages reference images by semantic query, not URL. After content generation, a second async step queries the Stock Photos API with auto-derived search terms:

async def hydrate_images(site: Site, page_content: dict) -> dict:
    """Replace semantic image placeholders with real Stock Photo API's URLs."""
    for block in page_content.get("content", []):
        if "backgroundImageQuery" in block.get("props", {}):
            query = block["props"].pop("backgroundImageQuery")
            url = await fetch_stock_photo_apis_image(query, orientation="landscape")
            if url:
                block["props"]["backgroundImage"] = url
    return page_content

The LLM emits backgroundImageQuery: "nigerian bakery fresh bread" rather than a URL. The hydration step runs after validation, so a failed image fetch never breaks page storage.

Nigerian-Specific Design Decisions

Payment: Paystack, Not Stripe

Paystack is the de facto standard for Nigerian card payments. The integration covers:

Monthly and annual billing plans with plan codes managed in Paystack's dashboard
Webhook-driven subscription state machine (charge.success → activate, subscription.not_renew → deactivate)
Naira amounts throughout — no currency conversion complexity

Annual billing required propagating the interval choice from the marketing pricing page all the way through signup → onboarding → backend → Paystack plan code selection. The key architectural point: the interval is stored in Paystack webhook metadata so that even if a user's browser crashes between initiating checkout and completing payment, the correct plan is activated.

Custom Domains: Cloudflare for SaaS

Every site gets a free subdomain (yourstore.webdigitize.com). Paid plans can connect a custom domain. This works via Cloudflare for SaaS: each custom domain is registered as a Cloudflare Custom Hostname, which handles SSL provisioning and CNAME routing without any manual per-site DNS configuration.

The Next.js middleware reads the incoming hostname, routes to the correct site, and injects the site's theme tokens and content. A single deployment serves thousands of storefronts.

WhatsApp as the Default CTA

For most Nigerian SMBs, WhatsApp is the primary business communication channel — not email, not a contact form. The AI generation pipeline is instructed to default CTAs to WhatsApp deep links (https://wa.me/{phone}) whenever a phone number is available. This alone meaningfully increases the conversion rate of the generated sites for our customers.

What I Got Wrong (and Fixed)

1. Trying to generate the shop page with AI

The first iteration asked Claude to generate a shop page layout. The result appeared fine statically, but it was dead, lacking product data, cart integration, and real-time inventory. I wasted a week before accepting that some pages need to be code, not content.

2. Putting too much in a single prompt

The first-generation home page prompt tried to generate all six sections in one shot with a 2,000-token instruction block. Output quality was inconsistent. Splitting into a generation pass + a focused critic pass with a shorter prompt produced dramatically better results with less prompt engineering effort.

3. Not fixing props at the schema layer

Early components had flexible props — any key was accepted, missing keys fell back to defaults. This made the LLM's job feel easier but pushed validation errors to render time, where they were silent. Switching to strict TypeScript prop types with runtime validation at the schema boundary caught hallucinated keys immediately and gave cleaner error messages during development.

4. Synchronous generation blocking the HTTP response

The first version await-ed generation inside the request handler. For a 4-page site, that meant a 15–25 second HTTP response. FastAPI's BackgroundTasks solved this: the response returns immediately with a job ID, the client polls a /status endpoint, and a Server-Sent Event pushes the "ready" signal. Users see a progress animation instead of a blank spinner.

Performance and Cost

Average home page generation time: 8–12 seconds (two Claude API calls)
Average full site (4 pages): 20–35 seconds (concurrent sub-page generation)
Claude API cost per site generated: approximately well within our margin at scale.
Stock Photos API: free tier covers 200 requests/hour, more than sufficient for current volume

The per-generation cost is negligible relative to monthly subscription revenue.

The Editor: Puck

Once a site is generated, users can edit it themselves through the Puck drag-and-drop editor embedded in the dashboard. The same JSON schema the AI produces is the schema the editor operates on — so a human tweak and an AI regeneration produce output in the same format, stored in the same database column.

This is the key architectural win: the AI is not a separate system that hands off to the editor. It is an initialiser for a data structure that the human can continue editing. Users who want no involvement after generation get a live website immediately. Users who want to customise have a full visual editor.

Open Questions and Future Work

Incremental regeneration: allow a user to say "regenerate just the services section" without touching the rest of the page.
Voice-driven brief: record a 60-second audio description, transcribe it with Whisper, and use that as the generation brief. This removes even the typing barrier for less tech-comfortable users.
Fine-tuning on accepted/rejected outputs: track which generated sites users edit heavily (a signal of poor initial quality) and use that as a training signal.
Multilingual generation: Yoruba, Hausa, and Igbo UI and content generation for non-English-primary users.

Conclusion

Building this taught me that the hard part of AI product development is rarely the model. It is the interface between the model's output and the rest of your system: schema design, validation, graceful degradation, and the user experience around the inevitable latency.

The dual-pass generation + critic architecture is the single most impactful thing I did to improve output quality. The schema-in-system-prompt trick is a close second.

If you are building anything similar, my recommendations:

Model output is a first draft. Build a critic step into your pipeline.
Schema constraints belong in the system prompt, not the user message.
Separate deterministic UI (shop, cart, checkout) from generated content.
Async everything — users will not wait 15 seconds for a first response.

WebDigitize is live at webdigitize.com.
Kindly share your thoughts (and questions) on this architecture. Do you think the design is scalable, and what are some risks you would flag in a critical review?