Documentation / Build
Architecture
Creator Core connects the parts a product and its coding agent need to work with. The repository makes ownership explicit so each part can be extended without replacing the rest of the system.
Connected layers
| Layer | Responsibility |
|---|---|
| Next.js and React | Routes, rendering, and the application shell |
| Hexclave | Identity, sessions, teams, permissions, and enabled user services |
| Convex | Reactive application data and server-side access checks |
| Base UI and local components | Editable controls, account views, and compositions |
| Design tokens and shared runtime | Themes, motion, and action feedback |
| Agent guidance and checks | Where to extend the system and how to verify the result |
Rendering and hosting
Cloudflare Workers hosts Next.js through the OpenNext adapter, with Node.js compatibility enabled. Static pages and assets ship with the Worker; account and application data load through authenticated Hexclave and Convex APIs. The current read-only static cache does not support ISR or on-demand revalidation. Add a writable cache when those features are introduced.
Hexclave is authoritative for users, sessions, teams, permissions, API keys, email, and enabled commercial services. Convex stores product data. Next.js owns rendering; shadcn/Base UI owns the application primitives. The app owns account UI in src/components/account; Hexclave SDK hooks and operations supply the data. Authentication pages remain hosted. See ACCOUNT_UI.md.
Authentication
The browser supplies Hexclave tokens through ConvexProviderWithAuth, including forced refresh. Convex verifies the issuer, audience, and signing key for the configured Hexclave project. Anonymous, restricted, and incomplete MFA identities cannot access protected data.
The /app layout uses Hexclave's documented useUser({ or: "redirect" }) navigation gate. This allows the SDK to finish a hosted callback before deciding whether sign-in or onboarding is needed. Dashboard data comes from the authenticated Hexclave API and Convex; no private data is embedded in prerendered HTML. Each Convex operation independently requires an authenticated identity; hiding a page or control is never authorization. Future Next.js server operations must use getHexclaveServerApp().getUser({ or: "throw" }) and enforce their own access checks. Server keys stay in server environments.
Ownership
The example notes table is personal. Its owner is derived from the verified token, never an argument. Reads use an owner index and deletes verify ownership. Notes are capped at 100 per user and 2,000 characters each. Changing the selected Hexclave team does not change note ownership or visibility.
Teams and invitations are managed through our account components using Hexclave APIs. The template configuration enables client team creation and defines member/admin roles; actual availability follows the target project's settings and permissions, including cloud overrides. There is no team-owned Convex table yet. Before adding one, implement a contract for verified membership, scoped permissions, and timely revocation; test two users in different teams. Do not treat the client-selected team ID as proof of membership.
Environments and reuse
The initial connected Convex deployment is a development deployment. GitHub Actions syncs that deployment after checks pass on main. It does not deploy a production backend. Provision a separate production deployment and deploy key before a production launch.
The supplied Hexclave cloud project is used for this starter. bun run dev:local-auth is an optional isolated Hexclave development environment; if using it with Convex, configure a separate Convex development deployment to trust that local project's issuer. Do not overwrite the shared deployment's auth configuration casually.
Every derived product gets its own GitHub repository, Hexclave project, Convex deployment, and Cloudflare Worker. Product initialization updates product.config.json; customize that file or the existing branding environment overrides, theme tokens, service values, GitHub secrets/variables, and an optional project-specific email theme. The template contains no reusable service credentials.
Enabled versus configured
hexclave.config.ts retains the supplied product and sign-in selections exactly. Enabling payments, API keys, RBAC, or webhooks does not invent a billing catalog, permission policy, API endpoint, or webhook consumer. Configure these against the first product's requirements. Use Hexclave's delivery and checkout setup before sending production email or taking payments.