Development practice

Website suite design: from source to a publishable release

Separate source preparation, isolated builds, version storage, preview review and publication. A company website illustrates the roles of Agent, site management, build environments and hosting.

Design example: a company website system for repeated editing, previewing and publishing, using static sites.

Architecture: responsibilities

01

User + Agent + website Skill

Define content, choose templates and edit source for a company and site.

Submit the creation request ↓

02

Identity and request gateway

Check which sites the user may manage and pass the authorized scope onward.

Gateway verifies identity; management schedules builds and receives results ↓

03

Site management service

Store sites, builds and releases; schedule builds and verify output.

04

Isolated build environment

Download source, install dependencies, test, build and upload static files.

Verify and store releases; hosting serves previews or published pages ↓

05

Private storage + release records

Source archives, build archives and manifests; separate preview and publication pointers.

06

Page hosting service

Serve the published version independently of editing and building.

Execution flow

  1. 01

    Prepare and restore

    Choose a template or restore a release into a fresh temporary project; retain the current revision.

  2. 02

    Submit and build

    Package and hash source, obtain a limited upload grant, start and poll a cloud build using a fixed buildId.

  3. 03

    Create and verify a release

    Server verifies files and registers the release; Agent checks preview and, when available, desktop/mobile browser behavior.

  4. 04

    Publish or roll back manually

    User selects a reviewed release; publishing checks revision and switches the published pointer. Rollback selects an explicit release too.

Key design decisions

Separate site, task and release

A site is a long-lived business object, a build is one production attempt, and a release is a specific deliverable. Give each its own state: build success is not publication, and preview need not match production. The current site can remain online while the next revision is reviewed.

Build in an independent environment

Management schedules and verifies; project code runs in an isolated, disposable environment. Validate source size, digest and extraction paths, limit runtime and resources, and use restricted upload grants. Keep management secrets out of source and build logs.

Handle concurrent edits and uncertain outcomes

Each edit records its base revision and checks for concurrent updates. Query the original task after a timeout before retrying, and prevent late builds from replacing newer previews. For billed builds, separate execution outcome from usage reconciliation so unknown results are not mistaken for success or zero cost.

Example: updating a product catalog

An exporter updates its English catalog. Agent edits release A and builds preview B. A reviewer catches a specification error, leading to C; only after review does the public entry switch from A to C. B remains in history and A is a rollback candidate, without editing live files in place.

{
  "siteId": "site-demo",
  "buildId": "build-demo",
  "expectedRevision": 7,
  "source": { "bytes": 245760, "sha256": "<digest>" },
  "releaseId": "release-demo",
  "previewRelease": "release-demo",
  "publishedRelease": "release-previous"
}
Illustrative data contract, not a callable API.

Scope and limits

This design focuses on company sites, catalogs and campaign pages. Transactions, sign-in, form handling and dynamic data need separate backend and access designs. Human publication suits higher content or brand risk; automatic publication needs explicit checks and rollback policy.

Continue reading