HIPsHanzo Proposals
Back to HIPs
HIP-0115DraftStandards TrackInfrastructure

Hanzo Frontend Delivery

Hanzo AI Team
Created: 2026-06-25
Requires: HIP-0036, HIP-0068, HIP-0119, HIP-0504

HIP-0115: Hanzo Frontend Delivery

Abstract

This is the one and only way a frontend — a site, a docs surface, a dashboard — is organized, built, and shipped across Hanzo, Lux, and Zoo. Every frontend is one repo in its org's apps organization, is one application on the PaaS, builds the same way, and is served the same way. There is exactly one project per site; there are no second implementations and no second homes.

It is the frontend peer of HIP-0119. HIP-0119 governs backend services — they serve /v1/* and :9090 to machines, live in per-service repos, and are deployed by the operator. This HIP governs apps — they serve / to humans, live in the per-org apps organization, and are deployed by the PaaS. The split is the decomplection: machine surface vs human surface, operator vs PaaS, never braided.

Specification

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, MAY are per RFC 2119.

§1 One repo per site, in the org's apps organization

  • Every frontend is its own repository in the <org>-apps GitHub organization (hanzo-apps, lux-apps, zoo-apps), cloned locally to ~/work/<org>/apps/<name>.
  • One project per site. A site MUST have exactly one repository. Multiple implementations of the same site (e.g. docs, app-docs, platform-docs) MUST be collapsed to one; the others are retired (archived), not left to rot.
  • A frontend MUST NOT live in the platform/service org (hanzoai, luxfi, zooai). Those orgs hold backend services and libraries. Static content and sites that currently sit there MUST be migrated into the apps org. One home.
  • Repos are separate (not a monorepo) precisely so each app is an independent PaaS application with an independent deploy. Sharing is by published package (the design system), never by workspace coupling.

§2 The design system is shared, not copied

A frontend MUST consume the design system as a dependency — @hanzo/ui, themed per brand to @luxfi/ui / @zooai/ui (HIP-0504: brand UIs are theme values, not forks). A frontend MUST NOT vendor or re-implement shared components. Brand differs in values (tokens, logo, domain); shape is identical.

§3 Build — the PaaS, one of two targets

Every app builds on the PaaS (platform.hanzo.ai). An app declares exactly one build target:

  • static — the default for sites and docs. The PaaS builds the app and publishes the static export (Next output: export, Vite dist, etc.) as an immutable artifact. This is the common case; prefer it.
  • container — only when the app genuinely needs a server at request time (SSR, server actions, auth callbacks that can't be edge/static). Runs as a PaaS container app.

An app MUST NOT be built or deployed by a hand-run pipeline, a bespoke per-repo GitHub Action that pushes to a host, or a second PaaS. One control plane.

§4 Serve — static to s3 + ingress, no nginx

  • A static app's artifact MUST be published to hanzoai/s3 (the object store) and served by hanzoai/ingress + the static plugin. nginx, caddy, and per-site web servers MUST NOT be used (per the platform rule).
  • A container app is served through hanzoai/ingress → the app, per HIP-0068.
  • DNS is Cloudflare; TLS is cert-manager/ingress. The host is <site>.<brand-domain>.
  • Adding a site is: new repo in <org>-apps → register the PaaS app (static, host) → deploy. No cluster YAML hand-editing, no new web server.

§5 One uniform shape across Hanzo, Lux, Zoo

hanzo-apps, lux-apps, and zoo-apps are the same organization in three brands. An app in any of them follows this HIP identically; only values differ — the org segment (<org>-apps), the brand domain, the theme package. LPs and ZIPs adopt this HIP by reference and MUST NOT restate or fork it.

§6 Forbidden

  • A site implemented in more than one repo; a site living in the service org.
  • A frontend that vendors the design system instead of depending on it.
  • A bespoke deploy pipeline; a second PaaS; nginx/caddy/per-site servers.
  • Static artifacts served from anywhere but hanzoai/s3 via ingress+static.

Conformance checklist

  1. The site is exactly one repo in <org>-apps; no alternate implementations.
  2. It depends on the design system; it vendors nothing shared.
  3. It builds on the PaaS as static (or container only if it must).
  4. static artifacts go to hanzoai/s3, served by ingress+static — no nginx.
  5. One host, Cloudflare DNS, ingress TLS.
  6. Nothing from §6.

References

  • HIP-0036 CI/CD Build System · HIP-0068 Ingress Standard
  • HIP-0119 Service Conventions (the backend peer) · HIP-0504 Design System
Edit on GitHubView Raw