From f8b15754c02f13f1dffd0a766ce6598cb87fefc6 Mon Sep 17 00:00:00 2001
From: VitorBernalRodrigues <vitorhugobernal@gmail.com>
Date: Fri, 21 Aug 2026 11:16:18 -0400
Subject: [PATCH] feat: add SEO metadata and structured data

---
 .gitignore                    |   1 +
 app/compliance/page.tsx       |   7 +++
 app/contracts/page.tsx        |   7 +++
 app/contributors/page.tsx     |   7 +++
 app/docs/page.tsx             |   7 +++
 app/layout.tsx                |  29 ++++++---
 app/operators/page.tsx        |   7 +++
 app/page.tsx                  |   6 ++
 app/product/page.tsx          |   7 +++
 app/roadmap/page.tsx          |   7 +++
 app/robots.ts                 |  21 +++++++
 app/sitemap.ts                |  11 ++++
 components/expected-pages.tsx |  17 +++---
 lib/site-map.ts               |  63 ++++++++++++++++++++
 lib/site.ts                   |  19 ++++++
 lib/structured-data.ts        |  29 +++++++++
 package.json                  |   3 +-
 tests/seo.test.ts             | 107 ++++++++++++++++++++++++++++++++++
 tsconfig.test.json            |  16 +++++
 19 files changed, 353 insertions(+), 18 deletions(-)
 create mode 100644 app/robots.ts
 create mode 100644 app/sitemap.ts
 create mode 100644 lib/site-map.ts
 create mode 100644 lib/site.ts
 create mode 100644 lib/structured-data.ts
 create mode 100644 tests/seo.test.ts
 create mode 100644 tsconfig.test.json

diff --git a/.gitignore b/.gitignore
index 1055e6d..2c3bc13 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,6 @@
 node_modules/
 .next/
+.test-dist/
 out/
 .env
 .env.local
diff --git a/app/compliance/page.tsx b/app/compliance/page.tsx
index 938df9f..db11021 100644
--- a/app/compliance/page.tsx
+++ b/app/compliance/page.tsx
@@ -1,3 +1,10 @@
+import type { Metadata } from "next";
+import { getRouteDescription } from "@/lib/site-map";
+
+export const metadata: Metadata = {
+  description: getRouteDescription("/compliance"),
+};
+
 export default function Page() {
   return (
     <section className="section">
diff --git a/app/contracts/page.tsx b/app/contracts/page.tsx
index 8b4cd26..1baf6ac 100644
--- a/app/contracts/page.tsx
+++ b/app/contracts/page.tsx
@@ -1,3 +1,10 @@
+import type { Metadata } from "next";
+import { getRouteDescription } from "@/lib/site-map";
+
+export const metadata: Metadata = {
+  description: getRouteDescription("/contracts"),
+};
+
 export default function Page() {
   return (
     <section className="section">
diff --git a/app/contributors/page.tsx b/app/contributors/page.tsx
index 301b35f..0cf95d3 100644
--- a/app/contributors/page.tsx
+++ b/app/contributors/page.tsx
@@ -1,3 +1,10 @@
+import type { Metadata } from "next";
+import { getRouteDescription } from "@/lib/site-map";
+
+export const metadata: Metadata = {
+  description: getRouteDescription("/contributors"),
+};
+
 export default function Page() {
   return (
     <section className="section">
diff --git a/app/docs/page.tsx b/app/docs/page.tsx
index 07197ba..e730dd6 100644
--- a/app/docs/page.tsx
+++ b/app/docs/page.tsx
@@ -1,3 +1,10 @@
+import type { Metadata } from "next";
+import { getRouteDescription } from "@/lib/site-map";
+
+export const metadata: Metadata = {
+  description: getRouteDescription("/docs"),
+};
+
 export default function Page() {
   return (
     <section className="section">
diff --git a/app/layout.tsx b/app/layout.tsx
index 0875230..580c01b 100644
--- a/app/layout.tsx
+++ b/app/layout.tsx
@@ -1,26 +1,31 @@
 import type { Metadata } from "next";
 import Image from "next/image";
 import Link from "next/link";
+import { getSiteUrl, isPreviewDeployment, SITE_DESCRIPTION, SITE_NAME } from "@/lib/site";
+import { getStructuredData, serializeJsonLd } from "@/lib/structured-data";
 import "./globals.css";
 
 export const metadata: Metadata = {
-  metadataBase: new URL("http://localhost:3000"),
+  metadataBase: getSiteUrl(),
   title: {
-    default: "ModelTrace",
-    template: "%s | " + "ModelTrace",
+    default: SITE_NAME,
+    template: `%s | ${SITE_NAME}`,
   },
-  description: "Verifiable AI inference accounting on Stellar.",
-  applicationName: "ModelTrace",
+  description: SITE_DESCRIPTION,
+  applicationName: SITE_NAME,
+  robots: isPreviewDeployment()
+    ? { index: false, follow: false }
+    : { index: true, follow: true },
   openGraph: {
-    title: "ModelTrace",
-    description: "Verifiable AI inference accounting on Stellar.",
+    title: SITE_NAME,
+    description: SITE_DESCRIPTION,
     type: "website",
     locale: "en_US",
   },
   twitter: {
     card: "summary_large_image",
-    title: "ModelTrace",
-    description: "Verifiable AI inference accounting on Stellar.",
+    title: SITE_NAME,
+    description: SITE_DESCRIPTION,
   },
   icons: {
     icon: [{ url: "/icon.svg", type: "image/svg+xml" }],
@@ -39,9 +44,15 @@ const nav = [
 ] as const;
 
 export default function RootLayout({ children }: { children: React.ReactNode }) {
+  const structuredData = getStructuredData();
+
   return (
     <html lang="en">
       <body>
+        <script
+          type="application/ld+json"
+          dangerouslySetInnerHTML={{ __html: serializeJsonLd(structuredData) }}
+        />
         <header className="nav">
           <div className="container nav-inner">
             <Link href="/" className="brand brand-with-logo">
diff --git a/app/operators/page.tsx b/app/operators/page.tsx
index 41a5393..a962e24 100644
--- a/app/operators/page.tsx
+++ b/app/operators/page.tsx
@@ -1,3 +1,10 @@
+import type { Metadata } from "next";
+import { getRouteDescription } from "@/lib/site-map";
+
+export const metadata: Metadata = {
+  description: getRouteDescription("/operators"),
+};
+
 export default function Page() {
   return (
     <section className="section">
diff --git a/app/page.tsx b/app/page.tsx
index 206226b..d6788b6 100644
--- a/app/page.tsx
+++ b/app/page.tsx
@@ -1,6 +1,12 @@
+import type { Metadata } from "next";
 import Link from "next/link";
 import { BrandLogo } from "@/components/brand-logo";
 import { ExpectedPages } from "@/components/expected-pages";
+import { getRouteDescription } from "@/lib/site-map";
+
+export const metadata: Metadata = {
+  description: getRouteDescription("/"),
+};
 
 export default function HomePage() {
   return (
diff --git a/app/product/page.tsx b/app/product/page.tsx
index b7a0844..11c6f19 100644
--- a/app/product/page.tsx
+++ b/app/product/page.tsx
@@ -1,3 +1,10 @@
+import type { Metadata } from "next";
+import { getRouteDescription } from "@/lib/site-map";
+
+export const metadata: Metadata = {
+  description: getRouteDescription("/product"),
+};
+
 export default function Page() {
   return (
     <section className="section">
diff --git a/app/roadmap/page.tsx b/app/roadmap/page.tsx
index 8f68322..6f489cc 100644
--- a/app/roadmap/page.tsx
+++ b/app/roadmap/page.tsx
@@ -1,3 +1,10 @@
+import type { Metadata } from "next";
+import { getRouteDescription } from "@/lib/site-map";
+
+export const metadata: Metadata = {
+  description: getRouteDescription("/roadmap"),
+};
+
 export default function Page() {
   return (
     <section className="section">
diff --git a/app/robots.ts b/app/robots.ts
new file mode 100644
index 0000000..e400603
--- /dev/null
+++ b/app/robots.ts
@@ -0,0 +1,21 @@
+import type { MetadataRoute } from "next";
+import { getSiteUrl, isPreviewDeployment } from "../lib/site";
+
+export default function robots(): MetadataRoute.Robots {
+  if (isPreviewDeployment()) {
+    return {
+      rules: {
+        userAgent: "*",
+        disallow: "/",
+      },
+    };
+  }
+
+  return {
+    rules: {
+      userAgent: "*",
+      allow: "/",
+    },
+    sitemap: new URL("/sitemap.xml", getSiteUrl()).toString(),
+  };
+}
diff --git a/app/sitemap.ts b/app/sitemap.ts
new file mode 100644
index 0000000..3cb9f85
--- /dev/null
+++ b/app/sitemap.ts
@@ -0,0 +1,11 @@
+import type { MetadataRoute } from "next";
+import { publicRoutes } from "../lib/site-map";
+import { getSiteUrl } from "../lib/site";
+
+export default function sitemap(): MetadataRoute.Sitemap {
+  const siteUrl = getSiteUrl();
+
+  return publicRoutes.map(({ path }) => ({
+    url: new URL(path, siteUrl).toString(),
+  }));
+}
diff --git a/components/expected-pages.tsx b/components/expected-pages.tsx
index c666f8c..ba30e1f 100644
--- a/components/expected-pages.tsx
+++ b/components/expected-pages.tsx
@@ -1,3 +1,5 @@
+import { publicRoutes } from "@/lib/site-map";
+
 export function ExpectedPages() {
   return (
     <section className="section site-map" id="site-map">
@@ -17,14 +19,13 @@ export function ExpectedPages() {
             </tr>
           </thead>
           <tbody>
-            <tr key="/"><td><code>/</code></td><td>Marketing hub + site map</td><td>Scaffold</td></tr>
-            <tr key="/product"><td><code>/product</code></td><td>Personas, pricing hooks, integration story</td><td>Planned</td></tr>
-            <tr key="/contracts"><td><code>/contracts</code></td><td>Soroban modules and interaction flows</td><td>Planned</td></tr>
-            <tr key="/operators"><td><code>/operators</code></td><td>Dashboard preview for AI gateways</td><td>Planned</td></tr>
-            <tr key="/compliance"><td><code>/compliance</code></td><td>Audit exports and policy packs</td><td>Planned</td></tr>
-            <tr key="/roadmap"><td><code>/roadmap</code></td><td>Milestones vs grants</td><td>Scaffold</td></tr>
-            <tr key="/contributors"><td><code>/contributors</code></td><td>Good first issues and guild roles</td><td>Planned</td></tr>
-            <tr key="/docs"><td><code>/docs</code></td><td>Technical reference hub</td><td>Scaffold</td></tr>
+            {publicRoutes.map(({ path, purpose, status }) => (
+              <tr key={path}>
+                <td><code>{path}</code></td>
+                <td>{purpose}</td>
+                <td>{status}</td>
+              </tr>
+            ))}
           </tbody>
         </table>
       </div>
diff --git a/lib/site-map.ts b/lib/site-map.ts
new file mode 100644
index 0000000..5310e3f
--- /dev/null
+++ b/lib/site-map.ts
@@ -0,0 +1,63 @@
+export const publicRoutes = [
+  {
+    path: "/",
+    purpose: "Marketing hub + site map",
+    status: "Scaffold",
+    description:
+      "Learn how ModelTrace turns AI usage into attested facts on-chain for procurement, finance, and audit teams.",
+  },
+  {
+    path: "/product",
+    purpose: "Personas, pricing hooks, integration story",
+    status: "Planned",
+    description: "Explore ModelTrace personas, pricing hooks, and integration story.",
+  },
+  {
+    path: "/contracts",
+    purpose: "Soroban modules and interaction flows",
+    status: "Planned",
+    description: "Explore ModelTrace Soroban modules and interaction flows.",
+  },
+  {
+    path: "/operators",
+    purpose: "Dashboard preview for AI gateways",
+    status: "Planned",
+    description: "Preview the ModelTrace dashboard planned for AI gateway operators.",
+  },
+  {
+    path: "/compliance",
+    purpose: "Audit exports and policy packs",
+    status: "Planned",
+    description: "Explore ModelTrace audit exports and policy packs.",
+  },
+  {
+    path: "/roadmap",
+    purpose: "Milestones vs grants",
+    status: "Scaffold",
+    description: "Track ModelTrace milestones, protocol releases, and grant checkpoints.",
+  },
+  {
+    path: "/contributors",
+    purpose: "Good first issues and guild roles",
+    status: "Planned",
+    description: "Find ModelTrace good first issues and contributor guild roles.",
+  },
+  {
+    path: "/docs",
+    purpose: "Technical reference hub",
+    status: "Scaffold",
+    description: "Read ModelTrace technical specifications, governance, and integration guides.",
+  },
+] as const;
+
+export type PublicPath = (typeof publicRoutes)[number]["path"];
+
+export function getRouteDescription(path: PublicPath): string {
+  const route = publicRoutes.find((candidate) => candidate.path === path);
+
+  if (!route) {
+    throw new Error(`Unknown public route: ${path}`);
+  }
+
+  return route.description;
+}
diff --git a/lib/site.ts b/lib/site.ts
new file mode 100644
index 0000000..69d3d2c
--- /dev/null
+++ b/lib/site.ts
@@ -0,0 +1,19 @@
+export const SITE_NAME = "ModelTrace";
+export const SITE_DESCRIPTION = "Verifiable AI inference accounting on Stellar.";
+
+const LOCAL_URL = "http://localhost:3000";
+
+function absoluteUrl(value: string): URL {
+  return new URL(value.includes("://") ? value : `https://${value}`);
+}
+
+export function getSiteUrl(): URL {
+  const deploymentUrl =
+    process.env.VERCEL_PROJECT_PRODUCTION_URL ?? process.env.VERCEL_URL;
+
+  return deploymentUrl ? absoluteUrl(deploymentUrl) : new URL(LOCAL_URL);
+}
+
+export function isPreviewDeployment(): boolean {
+  return process.env.VERCEL_ENV === "preview";
+}
diff --git a/lib/structured-data.ts b/lib/structured-data.ts
new file mode 100644
index 0000000..563eeb2
--- /dev/null
+++ b/lib/structured-data.ts
@@ -0,0 +1,29 @@
+import { SITE_DESCRIPTION, SITE_NAME, getSiteUrl } from "./site";
+
+const ORGANIZATION_NAME = "FinesseStudioLab";
+const ORGANIZATION_URL = "https://github.com/FinesseStudioLab";
+
+export function getStructuredData() {
+  return {
+    "@context": "https://schema.org",
+    "@graph": [
+      {
+        "@type": "Organization",
+        "@id": ORGANIZATION_URL,
+        name: ORGANIZATION_NAME,
+        url: ORGANIZATION_URL,
+      },
+      {
+        "@type": "SoftwareApplication",
+        name: SITE_NAME,
+        url: getSiteUrl().toString(),
+        description: SITE_DESCRIPTION,
+        publisher: { "@id": ORGANIZATION_URL },
+      },
+    ],
+  };
+}
+
+export function serializeJsonLd(value: unknown): string {
+  return JSON.stringify(value).replace(/</g, "\\u003c");
+}
diff --git a/package.json b/package.json
index fa7baef..4b52baa 100644
--- a/package.json
+++ b/package.json
@@ -6,7 +6,8 @@
     "dev": "next dev",
     "build": "next build",
     "start": "next start",
-    "lint": "next lint"
+    "lint": "next lint",
+    "test:seo": "tsc -p tsconfig.test.json && node --test .test-dist/tests/seo.test.js"
   },
   "dependencies": {
     "next": "^15.1.3",
diff --git a/tests/seo.test.ts b/tests/seo.test.ts
new file mode 100644
index 0000000..46568a3
--- /dev/null
+++ b/tests/seo.test.ts
@@ -0,0 +1,107 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import test from "node:test";
+import robots from "../app/robots";
+import sitemap from "../app/sitemap";
+import { publicRoutes } from "../lib/site-map";
+import { getStructuredData, serializeJsonLd } from "../lib/structured-data";
+
+const originalEnvironment = {
+  VERCEL_ENV: process.env.VERCEL_ENV,
+  VERCEL_PROJECT_PRODUCTION_URL: process.env.VERCEL_PROJECT_PRODUCTION_URL,
+  VERCEL_URL: process.env.VERCEL_URL,
+};
+
+function setEnvironment(values: Partial<typeof process.env>): void {
+  for (const [name, value] of Object.entries(values)) {
+    if (value === undefined) {
+      delete process.env[name];
+    } else {
+      process.env[name] = value;
+    }
+  }
+}
+
+test.afterEach(() => setEnvironment(originalEnvironment));
+
+test("sitemap contains every public route as an absolute, deterministic URL", () => {
+  setEnvironment({
+    VERCEL_PROJECT_PRODUCTION_URL: "modeltrace.example",
+    VERCEL_URL: undefined,
+  });
+
+  const firstResult = sitemap();
+
+  assert.deepEqual(firstResult, sitemap());
+  assert.deepEqual(
+    firstResult.map(({ url }) => url),
+    publicRoutes.map(({ path: routePath }) =>
+      new URL(routePath, "https://modeltrace.example").toString(),
+    ),
+  );
+  assert.ok(firstResult.every(({ url }) => URL.canParse(url)));
+});
+
+test("robots allows production and references the absolute sitemap URL", () => {
+  setEnvironment({
+    VERCEL_ENV: "production",
+    VERCEL_PROJECT_PRODUCTION_URL: "modeltrace.example",
+  });
+
+  assert.deepEqual(robots(), {
+    rules: { userAgent: "*", allow: "/" },
+    sitemap: "https://modeltrace.example/sitemap.xml",
+  });
+});
+
+test("robots blocks preview deployments and does not advertise a sitemap", () => {
+  setEnvironment({
+    VERCEL_ENV: "preview",
+    VERCEL_PROJECT_PRODUCTION_URL: "modeltrace.example",
+  });
+
+  assert.deepEqual(robots(), {
+    rules: { userAgent: "*", disallow: "/" },
+  });
+});
+
+test("robots does not treat local development as preview", () => {
+  setEnvironment({
+    VERCEL_ENV: undefined,
+    VERCEL_PROJECT_PRODUCTION_URL: undefined,
+    VERCEL_URL: undefined,
+  });
+
+  assert.deepEqual(robots(), {
+    rules: { userAgent: "*", allow: "/" },
+    sitemap: "http://localhost:3000/sitemap.xml",
+  });
+});
+
+test("structured data contains Organization and SoftwareApplication", () => {
+  setEnvironment({ VERCEL_PROJECT_PRODUCTION_URL: "modeltrace.example" });
+
+  const structuredData = getStructuredData();
+  const types = structuredData["@graph"].map((entry) => entry["@type"]);
+
+  assert.deepEqual(types, ["Organization", "SoftwareApplication"]);
+  assert.equal(structuredData["@graph"][1].url, "https://modeltrace.example/");
+  assert.equal(serializeJsonLd({ value: "</script>" }).includes("<"), false);
+});
+
+test("every public route has a unique description wired to its page", () => {
+  const descriptions = new Set(publicRoutes.map(({ description }) => description));
+
+  assert.equal(descriptions.size, publicRoutes.length);
+
+  for (const route of publicRoutes) {
+    assert.ok(route.description.length > 0);
+
+    const pagePath =
+      route.path === "/" ? "app/page.tsx" : `app${route.path}/page.tsx`;
+    const pageSource = readFileSync(path.join(process.cwd(), pagePath), "utf8");
+
+    assert.match(pageSource, new RegExp(`getRouteDescription\\(\\"${route.path}\\"\\)`));
+  }
+});
diff --git a/tsconfig.test.json b/tsconfig.test.json
new file mode 100644
index 0000000..2332801
--- /dev/null
+++ b/tsconfig.test.json
@@ -0,0 +1,16 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "incremental": false,
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "noEmit": false,
+    "outDir": ".test-dist"
+  },
+  "include": [
+    "app/robots.ts",
+    "app/sitemap.ts",
+    "lib/**/*.ts",
+    "tests/**/*.ts"
+  ]
+}