Architecture Overview

WebbiOS employs a unique, decentralized yet ecosystem-driven architecture to deliver a “Soft Lock-in” experience that maximizes developer flexibility while maintaining centralized governance.

The Core Concept

WebbiOS is fundamentally an App-as-Worker and Theme-as-Worker system built natively on Cloudflare’s edge infrastructure.

Unlike traditional SaaS platforms where all customer data lives in a single monolithic database, WebbiOS provisions a dedicated Cloudflare D1 Database and independent Worker instances for every single shop. This means:

• Customers truly own their data.
• The system is highly scalable since resources are decentralized.
• There is no single point of failure for end-user storefronts.

The 3-Tier Architecture

To manage this distributed ecosystem, we built a 3-tier architecture:

1. The Platform (God Instance)

Located at platform.webbios.dev, this is the centralized “brain” and marketplace. It is built using WebbiOS Core itself (dogfooding) but includes a specialized Platform Suite.

• Role: Manages licenses, billing, partner payouts, app listings, and provisions infrastructure.
• API Gateway: To use value-added services (like payment gateways or shipping partners), end-user shops must route requests through the Platform’s API Gateway. This hides sensitive master API keys (e.g., GHTK, VNPAY) from the end-user.

2. Regional Clients

These are distributors (like webbi.vn for Vietnam) that interact with the Platform API to register customers, handle localized payments, and provide support.

3. End-user Shops

The actual stores running on custom domains. Each shop is an independent instance of WebbiOS Core.

Infrastructure Provisioning

When a customer registers a shop, the Platform automatically:

1. Calls Cloudflare’s APIs to create a new D1 database for the shop.
2. Configures a new Worker for the Core API (setting INSTANCE_TYPE="shop").
3. Deploys the Dashboard UI to Cloudflare Pages.

This automated provisioning process takes seconds and guarantees isolated environments for every customer.

Blueprint Registry

To simplify setup, WebbiOS uses Blueprints. A Blueprint is a JSON recipe defining which core suites, apps, and themes should be installed by default (e.g., an “E-commerce” blueprint vs. a “Corporate Site” blueprint). When a shop is provisioned, the Platform reads the blueprint and automatically installs the required components via the Marketplace.