The ModelTrace web app — your public story, operator previews, and (soon) the dashboards that make verifiable AI billing on Stellar legible to buyers, vendors, and auditors.
This is the Next.js 15 (App Router) frontend for ModelTrace. It is the place where enterprises, inference providers, and contributors understand the product: what gets attested on-chain, how metering and settlement work, and how to participate. The Soroban contracts hold the rules; this app is the human interface—marketing, education, roadmap, and future signed-in operator views. Wallet-heavy or secret-bearing flows should still delegate to ../backend/ when you go to production.
From the root README:
- AI procurement is scaling faster than governance; teams cannot consistently prove model version, region, or policy for a given output.
- Enterprises and regulated buyers need audit trails that survive vendor churn and spreadsheet exports.
- Usage-based billing for inference often lacks a shared neutral layer, increasing disputes between buyers and providers.
- Register signed attestations of inference events tied to policy and pricing tiers.
- Support metered settlement with dispute windows and programmable payout logic on Soroban.
- Provide operator-grade dashboards and exports suitable for procurement and compliance reviews.
- Stay interoperable with existing inference gateways—ModelTrace is a rail, not a replacement model host.
- Trust is narrative + proof: Grant reviewers and CISOs start on the website, not in
contracts/. - Product education: Personas for gateway teams, finance, and compliance need long-form pages (
/product,/compliance). - Delivery transparency: The
ExpectedPagestable on/tracks which routes are real vs planned—same asdocs/SITE_MAP.md. - Operator UX (roadmap): Live usage views, export wizards, and integration guides surface here once auth lands.
- 🧭 Global shell —
app/layout.tsxwith nav to product, contracts, operators, compliance, roadmap, contributors, docs. - 🗺️ Live site map —
components/expected-pages.tsxon the home page mirrors the route backlog for stakeholders. - 📣 Marketing & compliance story — routes for pricing posture, audit exports narrative, and contributor onboarding (iterate content per sprint).
- 🔗 Integration posture — docs routes explain how gateways POST usage and how disputes settle—paired with backend implementation.
- 🔐 Wallet-ready path — scaffold assumes future Freighter/wallet connect for demos; never embed RPC secrets in
NEXT_PUBLIC_*. - 📱 Responsive UI — CSS variables in
globals.cssper protocol theme for demos on laptop + mobile.
| Layer | Choice |
|---|---|
| Framework | Next.js 15 — App Router, React 19 |
| Language | TypeScript (strict) |
| Styling | CSS variables in app/globals.css — protocol-specific palette |
| Components | components/expected-pages.tsx — site map table synced with docs/SITE_MAP.md |
| Data | Static/scaffold today → Server Components + ../backend/ for authenticated flows |
| Blockchain UX | Wallet demos optional — RPC/signing secrets stay off this bundle |
apps/web/
├── app/
│ ├── layout.tsx # Shell: metadata + nav links
│ ├── page.tsx # Landing + <ExpectedPages /> site map
│ ├── globals.css # Design tokens / theme
│ └── … # Feature routes (see route tables below)
├── components/
│ └── expected-pages.tsx
├── next.config.ts
├── package.json
├── tsconfig.json
└── README.md # ← you are here
| Route | Label | Notes |
|---|---|---|
/product |
Product | Primary navigation |
/contracts |
Contracts | Primary navigation |
/operators |
Operators | Primary navigation |
/compliance |
Compliance | Primary navigation |
/roadmap |
Roadmap | Primary navigation |
/contributors |
Contributors | Primary navigation |
/docs |
Docs | Primary navigation |
Authoritative purpose + status: ../../docs/SITE_MAP.md.
| Route | Purpose | Status |
|---|---|---|
/ |
Marketing hub + site map | Scaffold * |
/product |
Personas, pricing hooks, integration story | Planned |
/contracts |
Soroban modules and interaction flows | Planned |
/operators |
Dashboard preview for AI gateways | Planned |
/compliance |
Audit exports and policy packs | Planned |
/roadmap |
Milestones vs grants | Scaffold * |
/contributors |
Good first issues and guild roles | Planned |
/docs |
Technical reference hub | Scaffold * |
The Expected pages section on / mirrors this table so visitors see delivery honesty without opening GitHub.
- Node.js 20.x or 22.x (LTS)
- npm (pnpm/yarn OK if your org standardizes)
cd apps/web
npm install
npm run dev# Terminal A — backend
cd ../backend && npm install && cp .env.example .env && npm run dev
# Terminal B — web (this folder)
cd ../web && npm run devMatch ../backend/README.md CORS origin ↔ Next origin.
| Command | Purpose |
|---|---|
npm run dev |
Dev server + hot reload |
npm run build |
Production build |
npm run start |
Serve production output |
npm run lint |
ESLint (next/core-web-vitals) |
Static scaffold needs no secrets. Use .env.local (gitignored) for optional public config.
Never put private keys or RPC URLs here.
| Variable | Example | Purpose |
|---|---|---|
NEXT_PUBLIC_STELLAR_NETWORK |
testnet / public |
Which network label the UI shows. |
NEXT_PUBLIC_APP_URL |
https://… |
Canonical URL for OG tags / redirects. |
NEXT_PUBLIC_BACKEND_URL |
http://localhost:8080 |
Browser-safe pointer to API when calling from client. |
NEXT_PUBLIC_PLAUSIBLE_DOMAIN |
modeltrace.example |
Enables cookieless analytics (Plausible) and Web Vitals reporting. Unset = both are no-ops. |
- REST: Call
apps/backendunder/api/v1/*from Route Handlers or authenticated clients—never ship server secrets toNEXT_PUBLIC_*. - Soroban: Demonstrate wallet flows with test keys only; production signing patterns belong in backend or secure wallets.
- Contracts: Rules live in
../../contracts/— UI reflects state via Horizon/indexers/backend.
npm run lint
npm run build
npm test
npm run sizeFix all ESLint + TypeScript errors before merging.
npm run size (size-limit) checks the gzipped
weight of every cross-route JS chunk (.next/static/chunks/*.js) against the
budget in .size-limit.json, currently 300 KB. This is a coarser number than
the per-page "First Load JS" next build prints — it sums every shared chunk
rather than de-duplicating per page — so treat it as its own metric with its
own budget, not a stand-in for Next's dashboard figure. CI runs it after
npm run build on every PR and fails the build on a regression past budget.
- Set build command:
npm run build - Set output: Next.js default (
.next) - Configure
NEXT_PUBLIC_*env vars per environment - Point
NEXT_PUBLIC_BACKEND_URLat your deployed API - Enable preview deployments for grant demo links
.github/workflows/preview.yml deploys a preview and comments the URL on every
pull request. It needs four repository secrets:
| Secret | Where to find it |
|---|---|
VERCEL_TOKEN |
Vercel account settings → Tokens |
VERCEL_ORG_ID |
.vercel/project.json after vercel link |
VERCEL_PROJECT_ID |
.vercel/project.json after vercel link |
STAGING_BACKEND_URL |
Your staging API origin — previews are pinned to it |
The workflow runs on pull_request, not pull_request_target, so a pull
request from a fork cannot reach these secrets. Those runs skip the deploy and
report a notice instead of failing.
Previews build with NEXT_PUBLIC_DEPLOY_ENV=preview, which pins them to
testnet, shows a preview badge, and serves Disallow: / plus an
X-Robots-Tag: noindex header so they cannot compete with production in
search. lib/deploy-env.ts re-checks those targets during the build and fails
it if a preview is configured to reach production, rather than trusting the
workflow to have set every variable correctly.
Lighthouse runs against the deployed preview and posts its scores to the pull
request. .github/workflows/preview-cleanup.yml removes a pull request's
deployments when it is merged or closed, so previews do not accumulate.
See ../../CONTRIBUTING.md. UI changes should stay aligned with ../../docs/SITE_MAP.md.
Match repository license (Apache-2.0 common for OSS grants).
| Resource | Link |
|---|---|
| Monorepo overview | ../../README.md |
| Backend API | ../backend/README.md |
| Site map | ../../docs/SITE_MAP.md |
| Layout plan | ../../docs/layout-plan.md |
| Milestones → issues | ../../docs/milestones-issues.md |
npm package: modeltrace-web · Slug: modeltrace · Stack: Next.js App Router
Ship it. 🚀