upvote/README.md

Upvote — Feature Request Board

Let users vote on what’s next. A real, buildable Hanzo app: a feature-request board where your team submits ideas, upvotes the ones they want, and moves each request through open → planned → shipped — demand, ranked.

Built on the canonical Hanzo stack you fork on hanzo.app:

• UI — @hanzo/gui (the Hanzo design system) under Vite + React 19. No Tailwind, no second kit.
• Auth — @hanzo/iam, OAuth2 PKCE against hanzo.id. No local passwords — IAM owns every credential interaction.
• Data — @hanzo/base, the IAM-native, org-scoped data plane. Requests, votes, and comments are real Base collections, shared by everyone in your org.

Views

• Board — three status columns (Open · Planned · Shipped), each a soft-white column of vote-sorted request cards with a prominent upvote pill.
• Request detail — the description, a vote toggle, the status control (the product team moves it between columns), and threaded comments.
• Submit — a form to file a new request.

Stack (pinned)

Package	Version
react / react-dom	^19.2.4
@hanzo/gui + @hanzogui/config	7.3.0
@hanzo/iam	^0.13.1
@hanzo/base	^0.2.1
vite	^6 (@vitejs/plugin-react)
react-native-web	^0.21.0
typescript	5.9.3

Run it

npm install
npm run dev        # http://localhost:5173
npm run build      # tsc --noEmit && vite build  ->  dist/
npm run preview    # serve the production build (SPA fallback on)

Out of the box it runs against live Hanzo (hanzo.id + api.hanzo.ai) — no config needed to see the landing + sign-in flow. Copy .env.example to .env to point at a different environment.

Environment contract

Only VITE_-prefixed vars reach the browser (this is a static SPA — no server). Defaults in parentheses.

Var	Purpose
VITE_HANZO_IAM_URL (https://hanzo.id)	OIDC issuer.
VITE_IAM_CLIENT_ID (hanzo-app)	IAM application (<org>-<app>). Its redirect-URI list must allow this deploy’s /auth/callback — see Ambient IAM. Deploy provisions a dedicated per-app client.
VITE_HANZO_REDIRECT_URI (${origin}/auth/callback)	PKCE redirect.
VITE_HANZO_BASE_URL (https://api.hanzo.ai)	Browser-reachable Hanzo Base data plane. Deploy injects the provisioned URL.

How auth works — ambient IAM

login() starts an OAuth2 PKCE S256 redirect to hanzo.id; hanzo.id returns to /auth/callback, where handleCallback() exchanges the code for tokens (stored in localStorage, refresh-aware via offline_access). Every deployed app is a static site at <slug>.hanzo.app; there is no server token — the SPA authenticates the user in the browser and carries the resulting IAM JWT to Base. The one deploy requirement: the IAM client (VITE_IAM_CLIENT_ID) must list this origin’s /auth/callback as an allowed redirect URI.

How data works — Base from schema.sql

schema.sql is the app’s databaseSchema (SQL DDL). On publish, Hanzo Cloud translates each CREATE TABLE into a Hanzo Base collection (provisionBaseFromDDL, additive + idempotent). Base manages id/created/updated/owner/org, stamps owner+org from the verified IAM principal, and scopes every row to the caller’s org (rule @request.auth.org_id = org) — your teammates share the board; other orgs cannot see it. Three collections back the app:

• requests — title, description, status, votes, author_name
• votes — request_id, voter (one vote per person, enables toggling)
• comments — request_id, body, author_name

Keep schema.sql in lockstep with what src/views/* reads/writes.

Deploy — Hanzo Cloud

hanzo.yml declares a static build (npm run build → dist/, served at <slug>.hanzo.app) plus the Base schema to provision and the env to inject. Do not build a container image locally — Hanzo Cloud owns builds and deploys. CI here only proves the template compiles green.

Layout

src/
  main.tsx            entry
  providers.tsx       GuiProvider -> IamProvider -> BaseProvider(client=IAM-token)
  app.tsx             route (/auth/callback) + auth gate
  gui.config.ts       createGui(defaultConfig from @hanzogui/config/v5)
  iam.config.ts       IAM PKCE config
  env.ts              the VITE_ env contract, one place
  lib/base.ts         BaseClient carrying the IAM bearer token
  lib/requests.ts     data model (Request/Vote/Comment) + status meta + palette
  auth/callback.tsx   PKCE return leg
  views/
    signed-out.tsx    landing hero + board preview + sign-in
    home.tsx          signed-in shell (top bar) over the board
    board.tsx         status columns of vote-sorted requests (owns requests+votes)
    request-card.tsx  a card with the upvote pill
    request-detail.tsx description + status control + comments
    submit-form.tsx   new-request form
    upvote-pill.tsx   the caret + count vote control
schema.sql            databaseSchema -> Base collections on publish
hanzo.yml             Hanzo Cloud build/deploy manifest