Hydrix Docs

Concepts

Administration and site development mental models.

Use this page to understand where the client portal fits, how a deployed site is structured, and which API and auth surface belongs to which job.

Administration

Client portal scope

  • Manage organizations, members, billing, domains, sites, and repositories from one control surface.
  • Use it to create sites, review deployment status, and adjust safe reprovision-time settings.
  • Portal auth lives in the client portal user pool and is separate from every site runtime auth system.

Common portal flow

  • If you sign in without an active organization, the portal first opens the organization access page so you can create one or accept pending invites, and organization-scoped navigation stays hidden until one is selected.
  • Create or select an organization.
  • Add or purchase a domain, then create or bind a repository.
  • Provision the site and return to the portal for status, redeploy, localhost auth, and operations.

Boundary to remember

  • The client portal is the Hydrix control-plane experience.
  • The deployed site's /admin and /data routes are the site runtime experience.
  • Hydrix internal controller APIs stay IAM-only and are not part of the browser contract.

Site development

Think of site development in Hydrix as a loop: the admin surface defines the runtime, and the data surface exposes that runtime to the site or your client's users.

Runtime surfaces

  • /admin/* serves the site admin SPA.
  • /admin/public/* is the public bootstrap and onboarding surface.
  • /data/* is the site-facing runtime API surface.

Admin API purpose

  • /admin/api/* handles users, mailboxes, aliases, profile settings, and auth-email branding.
  • /admin/data/* handles resources, operations, jobs, env vars, groups, and IaC-driven setup.
  • Build the admin UI against this surface, not against internal Hydrix controller endpoints.

Data API purpose

  • /data/public/{operation} is for intentionally anonymous runtime actions.
  • /data/{operation} is for authenticated runtime actions used by the site or app itself.
  • Keep this surface focused on site features, not provisioning or operator tasks.

IaC and runtime setup

  • Use /admin/data or IaC definition profiles to declare resources, operations, jobs, groups, and env vars.
  • Hydrix applies those definitions idempotently and reconciles runtime permissions.
  • Saved profiles help you repeat the same site setup across multiple client sites without rebuilding it by hand.

Two auth pools per site

  • Each site gets its own admin pool and its own data-system pool.
  • The admin pool issues tokens for /admin/api/* and /admin/data/*.
  • The data-system pool issues access tokens for authenticated /data/{operation} calls.
  • Do not send admin-pool tokens to /data/{operation}.

Roles and groups

  • Admin-pool roles are super-admin, admin, and user.
  • Data-system groups are feature-specific and gate app behavior on authenticated data routes.
  • Groups can be managed directly or included in IaC jobs so route access stays reproducible.

Typical implementation flow

  • Provision the site in the client portal and confirm repository, domain, and localhost auth settings.
  • Build the admin experience around /admin/public, /admin/api, and /admin/data.
  • Use admin-side resource or IaC flows to create the runtime shape.
  • Build the site experience around /data/public/{operation} and /data/{operation}.

Open API contracts or Build & Integrate guides