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. |
- 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 buildFix all ESLint + TypeScript errors before merging.
- 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
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. 🚀