@@ -147,7 +156,7 @@ export function Sidebar({ projectId, onNavigate, onClose }: SidebarProps) {
icon={LayoutGrid}
label="Browse"
active={view === "browse"}
- onClick={() => setView("browse")}
+ onClick={openBrowse}
/>
= Object.fromEntries(
+ Object.entries(AUDIT_ISSUE_TYPES).map(([key, value]) => [key, value.title]),
+);
+
+export function GscCard({
+ projectId,
+ connected,
+}: {
+ projectId: string;
+ connected: boolean;
+}) {
+ const reportQuery = useQuery({
+ queryKey: ["dashboardGscReport", projectId],
+ queryFn: () =>
+ getSearchPerformanceReport({
+ data: { projectId, dateRange: "last_28_days" },
+ }),
+ enabled: connected,
+ });
+
+ // Not connected (or a dead grant discovered by the report call): the
+ // connection card sells and runs the whole flow itself.
+ if (!connected || (reportQuery.data && !reportQuery.data.connected)) {
+ return (
+
+
+ );
+ }
+
+ const report = reportQuery.data;
+
+ return (
+
+ More details
+
+ }
+ >
+ {reportQuery.isPending ? (
+
+ {Array.from({ length: 4 }, (_, i) => (
+
+ ))}
+
+ Couldn’t load Search Console data. Try again shortly.
+
+ ) : report?.connected ? (
+
+
+ }
+ />
+
+ }
+ />
+
+
+
+ );
+}
+
+export function RankMovementCard({
+ projectId,
+ rank,
+}: {
+ projectId: string;
+ rank: DashboardRankSummary | null;
+}) {
+ if (!rank) {
+ return (
+
+
+ Track your first keyword
+
+ }
+ />
+
+ );
+ }
+
+ return (
+
+ More details
+
+ }
+ >
+
+ 0 ? "success" : undefined}
+ />
+ 0 ? "error" : undefined}
+ />
+
+
+ );
+}
+
+export function AuditHealthCard({
+ projectId,
+ audit,
+}: {
+ projectId: string;
+ audit: DashboardAuditSummary | null;
+}) {
+ if (!audit) {
+ return (
+
+
+ Run an audit
+
+ }
+ />
+
+ );
+ }
+
+ return (
+
+ More details
+
+ }
+ >
+ {audit.topIssues.length === 0 ? (
+
+
+ ) : (
+
+ {audit.topIssues.map((issue) => (
+
+
+
+ {issueTitles[issue.issueType] ?? issue.issueType}
+
+
+
+ {issue.count} {issue.count === 1 ? "page" : "pages"}
+
+
+ ))}
+ {audit.totalIssueTypes > audit.topIssues.length ? (
+
+ + {audit.totalIssueTypes - audit.topIssues.length} more issue
+ {audit.totalIssueTypes - audit.topIssues.length === 1 ? "" : "s"}
+
+ ) : null}
+
+ )}
+
+ );
+}
+
+export function BacklinkPulseCard({
+ projectId,
+ backlinks,
+ refreshing,
+}: {
+ projectId: string;
+ backlinks: DashboardBacklinkSummary | null;
+ refreshing: boolean;
+}) {
+ if (!backlinks && refreshing) {
+ return (
+
+
+ {Array.from({ length: 4 }, (_, i) => (
+
+ ))}
+
+ );
+ }
+
+ if (!backlinks) {
+ return (
+
+
+ We’ll snapshot who links to your domain — nothing to set up.
+
+
+ );
+ }
+
+ return (
+
+ More details
+
+ }
+ >
+
+ 0
+ ? "success"
+ : undefined
+ }
+ />
+ 0
+ ? "error"
+ : undefined
+ }
+ />
+
+
+ );
+}
diff --git a/src/client/features/dashboard/DashboardPage.tsx b/src/client/features/dashboard/DashboardPage.tsx
new file mode 100644
index 0000000..4058ba4
--- /dev/null
+++ b/src/client/features/dashboard/DashboardPage.tsx
@@ -0,0 +1,376 @@
+import { useEffect, useRef, useState } from "react";
+import { Link, useNavigate } from "@tanstack/react-router";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { toast } from "sonner";
+import { ChevronLeft, ChevronRight, Check } from "lucide-react";
+import { captureClientEvent } from "@/client/lib/posthog";
+import {
+ computeNextStep,
+ isStepDone,
+ STEP_ORDER,
+} from "@/client/features/dashboard/dashboardSteps";
+import {
+ AuditHealthCard,
+ BacklinkPulseCard,
+ GscCard,
+ RankMovementCard,
+} from "@/client/features/dashboard/DashboardCards";
+import { McpConnectCard } from "@/client/features/dashboard/McpConnectCard";
+import { getStandardErrorMessage } from "@/client/lib/error-messages";
+import type { DashboardActivation } from "@/server/features/dashboard/services/DashboardService";
+import {
+ getDashboardActivation,
+ getDashboardOverview,
+ markDashboardCompetitorClicked,
+ refreshDashboardBacklinkSnapshot,
+} from "@/serverFunctions/dashboard";
+import { setProjectDomain } from "@/serverFunctions/projects";
+import type { DashboardHeroStep } from "@/types/schemas/dashboard";
+
+const HERO_COPY: Record<
+ DashboardHeroStep,
+ { title: string; body: string; cta: string }
+> = {
+ domain: {
+ title: "What site are you working on?",
+ body: "Set your project's domain and every card on this page starts working for it — backlinks, audits, rank tracking.",
+ cta: "Save",
+ },
+ mcp: {
+ title: "Connect your AI agent",
+ body: "OpenSEO is built to be used from agents like Claude. Connect once, then ask it to use OpenSEO to help build your SEO strategy.",
+ cta: "Show me how",
+ },
+ gsc: {
+ title: "Connect Search Console",
+ body: "Your real queries and clicks, straight from Google.",
+ cta: "Connect",
+ },
+ competitor: {
+ title: "Size up a competitor",
+ body: "Paste a competitor's domain to see what they rank for and who links to them.",
+ cta: "Open domain lookup",
+ },
+};
+
+function scrollToCard(id: string) {
+ document.getElementById(id)?.scrollIntoView({
+ behavior: "smooth",
+ block: "center",
+ });
+}
+
+// Users paste full URLs; store the bare host like settings expects.
+function normalizeDomainInput(value: string): string {
+ return value
+ .trim()
+ .replace(/^https?:\/\//i, "")
+ .replace(/\/.*$/, "");
+}
+
+function OnboardingChecklist({
+ projectId,
+ activation,
+}: {
+ projectId: string;
+ activation: DashboardActivation;
+}) {
+ const navigate = useNavigate();
+ const queryClient = useQueryClient();
+ const [domainInput, setDomainInput] = useState("");
+ // null = follow the first actionable step; set once the user pages with ‹ ›.
+ const [viewedIndex, setViewedIndex] = useState(null);
+ const invalidateActivation = () =>
+ void queryClient.invalidateQueries({
+ queryKey: ["dashboardActivation", projectId],
+ });
+
+ const competitorClickMutation = useMutation({
+ mutationFn: () => markDashboardCompetitorClicked({ data: { projectId } }),
+ onSuccess: invalidateActivation,
+ });
+ const domainMutation = useMutation({
+ mutationFn: (domain: string) =>
+ setProjectDomain({ data: { projectId, domain } }),
+ onSuccess: () => {
+ invalidateActivation();
+ void queryClient.invalidateQueries({
+ queryKey: ["dashboardOverview", projectId],
+ });
+ void queryClient.invalidateQueries({ queryKey: ["projects"] });
+ },
+ onError: (error) =>
+ toast.error(
+ getStandardErrorMessage(error, "Couldn't save the domain. Try again."),
+ ),
+ });
+
+ // Hidden once every step is done.
+ const nextStep = computeNextStep(activation);
+ if (!nextStep) return null;
+
+ const index = viewedIndex ?? STEP_ORDER.indexOf(nextStep);
+ const step = STEP_ORDER[index];
+ const copy = HERO_COPY[step];
+ const done = isStepDone(activation, step);
+
+ const page = (delta: number) =>
+ setViewedIndex(Math.min(Math.max(index + delta, 0), STEP_ORDER.length - 1));
+
+ const onSubmitDomain = () => {
+ const domain = normalizeDomainInput(domainInput);
+ if (!domain) return;
+ captureClientEvent("dashboard:next_move_click", { step: "domain" });
+ domainMutation.mutate(domain);
+ };
+
+ // Only the gsc/competitor steps use the fallback CTA button — domain
+ // renders an inline form and mcp renders a Link.
+ const onCta = () => {
+ captureClientEvent("dashboard:next_move_click", { step });
+ if (step === "gsc") {
+ scrollToCard("connect-gsc");
+ } else if (step === "competitor") {
+ competitorClickMutation.mutate();
+ void navigate({ to: "/p/$projectId/domain", params: { projectId } });
+ }
+ };
+
+ return (
+
+
+
+ Onboarding checklist
+
+
+ page(-1)}
+ >
+
+
+ {index + 1} / {STEP_ORDER.length}
+
+ page(1)}
+ >
+
+
+
+
+
+
{copy.title}
+
+ {copy.body}
+
+
+
+ {done ? (
+
+
+ ) : step === "domain" ? (
+
+ ) : step === "mcp" ? (
+
+ {copy.cta}
+
+ )}
+
+
+
+
+ {getStandardErrorMessage(activationQuery.error)}
+
+
+
+
Dashboard
+
+
+
+ {/* Every card is half width on large screens (only the checklist spans).
+ Cards with data render before setup pitches and empty states. */}
+
+ {[
+ // Array order is the within-bucket order after the data-first sort:
+ // the MCP pitch leads the setup cards.
+ ...(activation.mcp.firstToolCallAt || activation.mcp.cardDismissedAt
+ ? []
+ : [
+ {
+ key: "mcp",
+ hasData: false,
+ node: (
+
+ ),
+ },
+ ]),
+ {
+ key: "gsc",
+ hasData: gscConnected,
+ node:
,
+ },
+ {
+ key: "rank",
+ hasData: overview?.rank != null,
+ node: (
+
+ ),
+ },
+ {
+ key: "audit",
+ hasData: overview?.audit != null,
+ node: (
+
+ ),
+ },
+ ...(showBacklinks
+ ? [
+ {
+ key: "backlinks",
+ hasData:
+ overview?.backlinks != null || refreshMutation.isPending,
+ node: (
+
+ ),
+ },
+ ]
+ : []),
+ ]
+ .toSorted((a, b) => Number(b.hasData) - Number(a.hasData))
+ .map((card) => (
+
{card.node}
+ ))}
+
+
+
+
+
+ Connect your AI agent
+
+
+ {connected ? (
+
+ Connected
+
+ ) : null}
+ {
+ captureClientEvent("dashboard:mcp_already_connected");
+ dismissMutation.mutate();
+ }}
+ >
+ I already connected
+
+
+
+
+ {connected ? (
+ <>
+
+ Your agent is connected. Try asking it:
+
+
+ {firstPrompts(activation.domain).map((prompt) => (
+
+
+ {prompt}
+
+
+ captureClientEvent("dashboard:mcp_prompt_copy")
+ }
+ />
+
+ ))}
+
+
+ Waiting for your first call — this card disappears once your agent
+ talks to OpenSEO.
+
+
+ ) : (
+ <>
+
+
+ OpenSEO is designed to give your AI agent the data it needs to
+ build a great SEO strategy and help you execute it.
+
+
+ This way you aren’t limited on “AI credits”.
+
+
+ You can work with your agent to figure out what automations make
+ sense for you and it can help you write content too.
+
+
+
captureClientEvent("dashboard:mcp_setup_open")}
+ >
+ Set up in AI & MCP →
+
+
+ )}
+
+
+
+
{title}
+ {action}
+
+
+ {children}
+ {stamp ? (
+
{stamp}
+ ) : null}
+
+
+
+ {label}
+
+
+ {value}
+
+ {sub}
+
+ {rounded > 0 ? "▲" : rounded < 0 ? "▼" : ""} {Math.abs(rounded)}%
+
+ );
+}
+
+export const moreDetailsClass = "btn btn-ghost btn-xs";
+
+export function newLost(value: number | null): string {
+ return value === null ? "—" : String(value);
+}
+
+export function formatDay(timestamp: string): string {
+ const ms = Date.parse(
+ // SQLite's current_timestamp default has no timezone marker; treat it as
+ // UTC rather than letting the browser parse it as local time.
+ /^\d{4}-\d{2}-\d{2} /.test(timestamp)
+ ? `${timestamp.replace(" ", "T")}Z`
+ : timestamp,
+ );
+ if (Number.isNaN(ms)) return timestamp;
+ return new Date(ms).toLocaleDateString(undefined, {
+ month: "short",
+ day: "numeric",
+ });
+}
diff --git a/src/client/features/dashboard/dashboardSteps.ts b/src/client/features/dashboard/dashboardSteps.ts
new file mode 100644
index 0000000..aae78f2
--- /dev/null
+++ b/src/client/features/dashboard/dashboardSteps.ts
@@ -0,0 +1,42 @@
+import type { DashboardActivation } from "@/server/features/dashboard/services/DashboardService";
+import type { DashboardHeroStep } from "@/types/schemas/dashboard";
+
+export const STEP_ORDER: DashboardHeroStep[] = [
+ "domain",
+ "mcp",
+ "gsc",
+ "competitor",
+];
+
+// A step is "done" when the underlying product state exists, regardless of
+// how it got there. The MCP hero step completes at authorization (the card
+// below owns the connected-but-no-call-yet coaching) or when the user said
+// "I already connected".
+export function isStepDone(
+ activation: DashboardActivation,
+ step: DashboardHeroStep,
+): boolean {
+ switch (step) {
+ case "domain":
+ return activation.domain !== null;
+ case "mcp":
+ return (
+ activation.mcp.authorizedAt !== null ||
+ activation.mcp.cardDismissedAt !== null
+ );
+ case "gsc":
+ return activation.gsc.connected;
+ case "competitor":
+ return activation.competitorClickedAt !== null;
+ }
+}
+
+/** The single step the hero should coach next; null = coaching is over. */
+export function computeNextStep(
+ activation: DashboardActivation,
+): DashboardHeroStep | null {
+ for (const step of STEP_ORDER) {
+ if (!isStepDone(activation, step)) return step;
+ }
+ return null;
+}
diff --git a/src/client/features/gsc/SearchConsoleConnectionCard.tsx b/src/client/features/gsc/SearchConsoleConnectionCard.tsx
index 251f434..ae70698 100644
--- a/src/client/features/gsc/SearchConsoleConnectionCard.tsx
+++ b/src/client/features/gsc/SearchConsoleConnectionCard.tsx
@@ -96,6 +96,14 @@ export function SearchConsoleConnectionCard({
void queryClient.invalidateQueries({
queryKey: ["searchPerformanceTable", projectId],
});
+ // The dashboard embeds this card and swaps it for the Search
+ // performance stats card once activation reports the connection.
+ void queryClient.invalidateQueries({
+ queryKey: ["dashboardActivation", projectId],
+ });
+ void queryClient.invalidateQueries({
+ queryKey: ["dashboardGscReport", projectId],
+ });
},
onError: (error) => toast.error(getStandardErrorMessage(error)),
});
@@ -116,6 +124,12 @@ export function SearchConsoleConnectionCard({
void queryClient.invalidateQueries({
queryKey: ["searchPerformanceTable", projectId],
});
+ void queryClient.invalidateQueries({
+ queryKey: ["dashboardActivation", projectId],
+ });
+ void queryClient.invalidateQueries({
+ queryKey: ["dashboardGscReport", projectId],
+ });
},
onError: (error) => toast.error(getStandardErrorMessage(error)),
});
@@ -177,7 +191,8 @@ export function SearchConsoleConnectionCard({
) : (
- Connect your Google Search Console to get insights in OpenSEO.
+ Connect GSC to see how your website is actually performing in Google
+ Search.
void;
onBack: () => void;
onSkip: () => void;
- onFinish: (mcpSetupIntent: "yes" | "no") => void;
+ onFinish: () => void;
isSaving: boolean;
accountMenu: ReactNode;
};
@@ -122,27 +122,20 @@ export function PostSignupOnboarding({
otherValue={answers.sourceOther}
onOtherChange={(sourceOther) => updateAnswers({ sourceOther })}
/>
- ) : step === 3 ? (
- onFinish("yes")}
- onSkip={() => onFinish("no")}
- />
+
-
- Back
-
+
+
+ Back
+
+ {step < ONBOARDING_LAST_STEP ? (
-
- ) : null}
+ ) : (
+
+ Finish
+
+ )}
+
);
}
-function McpRecommendation({
- isSaving,
- onBack,
- onSetup,
- onSkip,
-}: {
- isSaving: boolean;
- onBack: () => void;
- onSetup: () => void;
- onSkip: () => void;
-}) {
- const capabilities = [
- "Keyword research",
- "Competitor research",
- "Link prospecting",
- ];
-
- return (
-
-
-
-
Set up OpenSEO MCP?
-
- The most powerful way to use OpenSEO — use AI to supercharge your SEO
- skills.
-
-
-
- {capabilities.map((capability) => (
-
-
-
- {capability}
-
- ))}
-
-
-
- Yes, set up MCP
-
-
- Not now
-
-
- );
-}
-
function OnboardingChoiceGroup({
title,
description,
diff --git a/src/client/features/onboarding/onboardingModel.ts b/src/client/features/onboarding/onboardingModel.ts
index 32bbb10..81080fd 100644
--- a/src/client/features/onboarding/onboardingModel.ts
+++ b/src/client/features/onboarding/onboardingModel.ts
@@ -1,7 +1,7 @@
import { queryOptions } from "@tanstack/react-query";
import { getOnboardingAnswers } from "@/serverFunctions/onboarding";
-export const ONBOARDING_LAST_STEP = 4;
+export const ONBOARDING_LAST_STEP = 3;
export const INTEREST_OPTIONS = [
"AI workflows with Claude or Codex (MCP)",
@@ -32,6 +32,7 @@ export const CLIENT_WEBSITE_COUNT_OPTIONS = [
] as const;
export const SOURCE_OPTIONS = [
+ "Product Hunt",
"Google",
"Reddit",
"X / Twitter",
@@ -110,7 +111,7 @@ export function restoreOnboardingAnswers(
export function buildOnboardingPayload(
answers: OnboardingAnswers,
step: number,
- extra: { mcpSetupIntent?: "yes" | "no"; completed?: boolean } = {},
+ extra: { completed?: boolean } = {},
) {
const interestedFeatures = answers.selectedInterests.map((value) =>
value === "Other" && answers.interestOther.trim()
diff --git a/src/client/features/projects/ProjectSwitcher.tsx b/src/client/features/projects/ProjectSwitcher.tsx
index 1da25d2..6350632 100644
--- a/src/client/features/projects/ProjectSwitcher.tsx
+++ b/src/client/features/projects/ProjectSwitcher.tsx
@@ -30,7 +30,7 @@ export function ProjectSwitcher({
if (project.id === activeProjectId) return;
setLastProjectId(project.id);
void navigate({
- to: "/p/$projectId/keywords",
+ to: "/p/$projectId",
params: { projectId: project.id },
});
};
diff --git a/src/client/navigation/items.ts b/src/client/navigation/items.ts
index 8964635..b27d53e 100644
--- a/src/client/navigation/items.ts
+++ b/src/client/navigation/items.ts
@@ -3,6 +3,7 @@ import {
Bot,
ClipboardCheck,
Globe,
+ LayoutDashboard,
Link2,
MessageSquare,
Search,
@@ -13,6 +14,14 @@ import { linkOptions } from "@tanstack/react-router";
import { GoogleGlyphMuted } from "@/client/features/gsc/GoogleGlyph";
const projectNavItems = [
+ {
+ to: "/p/$projectId" as const,
+ label: "Dashboard",
+ icon: LayoutDashboard,
+ // Without exact matching, the index path is a prefix of every project
+ // route and the Dashboard item would render active everywhere.
+ activeOptions: { exact: true, includeSearch: false },
+ },
{
to: "/p/$projectId/keywords" as const,
label: "Keyword Research",
@@ -90,6 +99,10 @@ export function getProjectNavGroups(projectId: string) {
all.find((i) => i.to === path)!;
return [
+ {
+ label: "Overview",
+ items: [byPath("/p/$projectId")],
+ },
{
label: "Research",
items: [
diff --git a/src/db/app.schema.ts b/src/db/app.schema.ts
index 542868f..6709dad 100644
--- a/src/db/app.schema.ts
+++ b/src/db/app.schema.ts
@@ -350,3 +350,71 @@ export const rankSnapshots = sqliteTable(
),
],
);
+
+// Dashboard activation milestones. Organization-scoped: MCP OAuth grants are
+// user-level, so any member connecting an external MCP client satisfies the
+// milestone for the whole organization. Timestamps are first-occurrence only
+// and never move once set.
+export const organizationActivationState = sqliteTable(
+ "organization_activation_state",
+ {
+ organizationId: text("organization_id")
+ .primaryKey()
+ .references(() => organization.id, { onDelete: "cascade" }),
+ firstMcpAuthorizedAt: text("first_mcp_authorized_at"),
+ firstMcpToolCallAt: text("first_mcp_tool_call_at"),
+ updatedAt: text("updated_at")
+ .notNull()
+ .default(sql`(current_timestamp)`),
+ },
+);
+
+// Per-project state for the dashboard's onboarding checklist. Most steps
+// complete via real product state (projects.domain, gsc_connections, MCP
+// activation); the competitor step completes on click-through.
+export const projectActivationState = sqliteTable("project_activation_state", {
+ projectId: text("project_id")
+ .primaryKey()
+ .references(() => projects.id, { onDelete: "cascade" }),
+ competitorStepClickedAt: text("competitor_step_clicked_at"),
+ // "I already connected" on the MCP card: hides the card for this project
+ // without faking the org-level first-tool-call milestone, which stays
+ // truthful and self-heals when a real external call lands.
+ mcpCardDismissedAt: text("mcp_card_dismissed_at"),
+ updatedAt: text("updated_at")
+ .notNull()
+ .default(sql`(current_timestamp)`),
+});
+
+// Point-in-time backlink profile summaries for the project's own domain,
+// written by the dashboard's visit-triggered refresh. DataForSEO's summary
+// already carries new/lost counts, so one snapshot renders a full card;
+// rows accumulate into history for future trend views. The domain is stored
+// per row so a later project-domain change doesn't rewrite history.
+export const backlinkSnapshots = sqliteTable(
+ "backlink_snapshots",
+ {
+ id: integer("id").primaryKey({ autoIncrement: true }),
+ projectId: text("project_id")
+ .notNull()
+ .references(() => projects.id, { onDelete: "cascade" }),
+ domain: text("domain").notNull(),
+ rank: integer("rank"),
+ backlinks: integer("backlinks"),
+ referringDomains: integer("referring_domains"),
+ brokenBacklinks: integer("broken_backlinks"),
+ newBacklinks: integer("new_backlinks"),
+ lostBacklinks: integer("lost_backlinks"),
+ newReferringDomains: integer("new_referring_domains"),
+ lostReferringDomains: integer("lost_referring_domains"),
+ capturedAt: text("captured_at")
+ .notNull()
+ .default(sql`(current_timestamp)`),
+ },
+ (table) => [
+ index("backlink_snapshots_project_captured_idx").on(
+ table.projectId,
+ table.capturedAt,
+ ),
+ ],
+);
diff --git a/src/db/pg/app.schema.ts b/src/db/pg/app.schema.ts
index dc5e046..f673cfd 100644
--- a/src/db/pg/app.schema.ts
+++ b/src/db/pg/app.schema.ts
@@ -343,3 +343,65 @@ export const rankSnapshots = pgTable(
),
],
);
+
+// Dashboard activation milestones. Organization-scoped: MCP OAuth grants are
+// user-level, so any member connecting an external MCP client satisfies the
+// milestone for the whole organization. Timestamps are first-occurrence only
+// and never move once set.
+export const organizationActivationState = pgTable(
+ "organization_activation_state",
+ {
+ organizationId: text("organization_id")
+ .primaryKey()
+ .references(() => organization.id, { onDelete: "cascade" }),
+ firstMcpAuthorizedAt: timestampColumn("first_mcp_authorized_at"),
+ firstMcpToolCallAt: timestampColumn("first_mcp_tool_call_at"),
+ updatedAt: timestampColumn("updated_at").notNull().default(isoNow),
+ },
+);
+
+// Per-project state for the dashboard's onboarding checklist. Most steps
+// complete via real product state (projects.domain, gsc_connections, MCP
+// activation); the competitor step completes on click-through.
+export const projectActivationState = pgTable("project_activation_state", {
+ projectId: text("project_id")
+ .primaryKey()
+ .references(() => projects.id, { onDelete: "cascade" }),
+ competitorStepClickedAt: timestampColumn("competitor_step_clicked_at"),
+ // "I already connected" on the MCP card: hides the card for this project
+ // without faking the org-level first-tool-call milestone, which stays
+ // truthful and self-heals when a real external call lands.
+ mcpCardDismissedAt: timestampColumn("mcp_card_dismissed_at"),
+ updatedAt: timestampColumn("updated_at").notNull().default(isoNow),
+});
+
+// Point-in-time backlink profile summaries for the project's own domain,
+// written by the dashboard's visit-triggered refresh. DataForSEO's summary
+// already carries new/lost counts, so one snapshot renders a full card;
+// rows accumulate into history for future trend views. The domain is stored
+// per row so a later project-domain change doesn't rewrite history.
+export const backlinkSnapshots = pgTable(
+ "backlink_snapshots",
+ {
+ id: serial("id").primaryKey(),
+ projectId: text("project_id")
+ .notNull()
+ .references(() => projects.id, { onDelete: "cascade" }),
+ domain: text("domain").notNull(),
+ rank: integer("rank"),
+ backlinks: integer("backlinks"),
+ referringDomains: integer("referring_domains"),
+ brokenBacklinks: integer("broken_backlinks"),
+ newBacklinks: integer("new_backlinks"),
+ lostBacklinks: integer("lost_backlinks"),
+ newReferringDomains: integer("new_referring_domains"),
+ lostReferringDomains: integer("lost_referring_domains"),
+ capturedAt: timestampColumn("captured_at").notNull().default(isoNow),
+ },
+ (table) => [
+ index("backlink_snapshots_project_captured_idx").on(
+ table.projectId,
+ table.capturedAt,
+ ),
+ ],
+);
diff --git a/src/db/schema.ts b/src/db/schema.ts
index b00c368..58af2a0 100644
--- a/src/db/schema.ts
+++ b/src/db/schema.ts
@@ -72,6 +72,9 @@ export const {
rankTrackingKeywords,
rankCheckRuns,
rankSnapshots,
+ organizationActivationState,
+ projectActivationState,
+ backlinkSnapshots,
audits,
auditPages,
auditLinks,
diff --git a/src/routes/_app/index.tsx b/src/routes/_app/index.tsx
index d4b0c74..e939fd8 100644
--- a/src/routes/_app/index.tsx
+++ b/src/routes/_app/index.tsx
@@ -40,7 +40,7 @@ function IndexRedirect() {
}
void navigate({
- to: "/p/$projectId/keywords",
+ to: "/p/$projectId",
params: { projectId: (target ?? data[0]).id },
});
}, [data, navigate]);
diff --git a/src/routes/_authenticated.onboarding.index.tsx b/src/routes/_authenticated.onboarding.index.tsx
index 244cb3c..2ffee34 100644
--- a/src/routes/_authenticated.onboarding.index.tsx
+++ b/src/routes/_authenticated.onboarding.index.tsx
@@ -81,10 +81,7 @@ function OnboardingFlow({
const [answers, setAnswers] = useState
(initialAnswers);
const saveMutation = useMutation({
- mutationFn: (extra: {
- mcpSetupIntent?: "yes" | "no";
- completed?: boolean;
- }) =>
+ mutationFn: (extra: { completed?: boolean }) =>
saveOnboardingAnswers({
data: buildOnboardingPayload(answers, step, extra),
}),
@@ -113,9 +110,9 @@ function OnboardingFlow({
goToStep(step + 1);
};
- const handleFinish = async (mcpSetupIntent: "yes" | "no") => {
+ const handleFinish = async () => {
try {
- await saveMutation.mutateAsync({ mcpSetupIntent, completed: true });
+ await saveMutation.mutateAsync({ completed: true });
// Refresh the shared cache so the destination's onboarding-redirect guard
// sees the completed state and doesn't bounce the user back here.
await queryClient.invalidateQueries({ queryKey: ["onboardingAnswers"] });
@@ -126,13 +123,9 @@ function OnboardingFlow({
interests: answers.selectedInterests,
work_for: answers.workFor,
source: answers.source,
- wants_mcp_setup: mcpSetupIntent === "yes",
});
- if (mcpSetupIntent === "yes") {
- void navigate({ to: "/ai", replace: true });
- } else {
- void navigate({ to: "/", replace: true });
- }
+ // The dashboard's onboarding checklist owns MCP coaching now.
+ void navigate({ to: "/", replace: true });
};
return (
diff --git a/src/routes/_project/p/$projectId/index.tsx b/src/routes/_project/p/$projectId/index.tsx
index 8a24560..368671c 100644
--- a/src/routes/_project/p/$projectId/index.tsx
+++ b/src/routes/_project/p/$projectId/index.tsx
@@ -1,10 +1,11 @@
-import { createFileRoute, redirect } from "@tanstack/react-router";
+import { createFileRoute } from "@tanstack/react-router";
+import { DashboardPage } from "@/client/features/dashboard/DashboardPage";
export const Route = createFileRoute("/_project/p/$projectId/")({
- beforeLoad: ({ params }) => {
- throw redirect({
- to: "/p/$projectId/keywords",
- params: { projectId: params.projectId },
- });
- },
+ component: DashboardRoute,
});
+
+function DashboardRoute() {
+ const { projectId } = Route.useParams();
+ return ();
+
+/**
+ * Milestone writes for the dashboard's MCP activation card. Both are awaited
+ * inline by their callers (not waitUntil) so the upsert runs inside the
+ * request's DB client scope, and both swallow errors: activation tracking
+ * must never fail an OAuth flow or a tool call.
+ */
+export async function recordMcpAuthorized(
+ organizationId: string,
+): Promise {
+ try {
+ await ActivationRepository.recordFirstMcpAuthorized(organizationId);
+ } catch (error) {
+ console.error("activation: recordMcpAuthorized failed", error);
+ }
+}
+
+export async function recordExternalMcpToolCall(
+ organizationId: string,
+): Promise {
+ if (recordedToolCallOrgs.has(organizationId)) return;
+ recordedToolCallOrgs.add(organizationId);
+ try {
+ await ActivationRepository.recordFirstMcpToolCall(organizationId);
+ } catch (error) {
+ // Allow a retry on a later call rather than losing the milestone.
+ recordedToolCallOrgs.delete(organizationId);
+ console.error("activation: recordExternalMcpToolCall failed", error);
+ }
+}
diff --git a/src/server/features/activation/repositories/ActivationRepository.ts b/src/server/features/activation/repositories/ActivationRepository.ts
new file mode 100644
index 0000000..870b2a9
--- /dev/null
+++ b/src/server/features/activation/repositories/ActivationRepository.ts
@@ -0,0 +1,99 @@
+import { eq, sql } from "drizzle-orm";
+import { db } from "@/db";
+import {
+ organizationActivationState,
+ projectActivationState,
+} from "@/db/schema";
+
+type OrganizationActivationState =
+ typeof organizationActivationState.$inferSelect;
+type ProjectActivationState = typeof projectActivationState.$inferSelect;
+
+async function getOrganizationActivation(
+ organizationId: string,
+): Promise {
+ const rows = await db
+ .select()
+ .from(organizationActivationState)
+ .where(eq(organizationActivationState.organizationId, organizationId))
+ .limit(1);
+ return rows[0] ?? null;
+}
+
+async function getProjectActivation(
+ projectId: string,
+): Promise {
+ const rows = await db
+ .select()
+ .from(projectActivationState)
+ .where(eq(projectActivationState.projectId, projectId))
+ .limit(1);
+ return rows[0] ?? null;
+}
+
+// First-occurrence timestamps only: concurrent writers race harmlessly because
+// COALESCE keeps whichever value landed first.
+async function recordFirstMcpAuthorized(organizationId: string): Promise {
+ const now = new Date().toISOString();
+ await db
+ .insert(organizationActivationState)
+ .values({ organizationId, firstMcpAuthorizedAt: now, updatedAt: now })
+ .onConflictDoUpdate({
+ target: organizationActivationState.organizationId,
+ set: {
+ firstMcpAuthorizedAt: sql`coalesce(${organizationActivationState.firstMcpAuthorizedAt}, ${now})`,
+ updatedAt: now,
+ },
+ });
+}
+
+async function recordFirstMcpToolCall(organizationId: string): Promise {
+ const now = new Date().toISOString();
+ await db
+ .insert(organizationActivationState)
+ .values({ organizationId, firstMcpToolCallAt: now, updatedAt: now })
+ .onConflictDoUpdate({
+ target: organizationActivationState.organizationId,
+ set: {
+ firstMcpToolCallAt: sql`coalesce(${organizationActivationState.firstMcpToolCallAt}, ${now})`,
+ updatedAt: now,
+ },
+ });
+}
+
+async function markCompetitorStepClicked(projectId: string): Promise {
+ const now = new Date().toISOString();
+ await db
+ .insert(projectActivationState)
+ .values({ projectId, competitorStepClickedAt: now, updatedAt: now })
+ .onConflictDoUpdate({
+ target: projectActivationState.projectId,
+ set: {
+ competitorStepClickedAt: sql`coalesce(${projectActivationState.competitorStepClickedAt}, ${now})`,
+ updatedAt: now,
+ },
+ });
+}
+
+async function markMcpCardDismissed(projectId: string): Promise {
+ const now = new Date().toISOString();
+ await db
+ .insert(projectActivationState)
+ .values({ projectId, mcpCardDismissedAt: now, updatedAt: now })
+ .onConflictDoUpdate({
+ target: projectActivationState.projectId,
+ set: {
+ mcpCardDismissedAt: sql`coalesce(${projectActivationState.mcpCardDismissedAt}, ${now})`,
+ updatedAt: now,
+ },
+ });
+}
+
+export const ActivationRepository = {
+ getOrganizationActivation,
+ getProjectActivation,
+ recordFirstMcpAuthorized,
+ recordFirstMcpToolCall,
+ markCompetitorStepClicked,
+ markMcpCardDismissed,
+};
diff --git a/src/server/features/audit/repositories/auditSummaryQueries.ts b/src/server/features/audit/repositories/auditSummaryQueries.ts
new file mode 100644
index 0000000..6ac6bb9
--- /dev/null
+++ b/src/server/features/audit/repositories/auditSummaryQueries.ts
@@ -0,0 +1,21 @@
+import { countDistinct, eq } from "drizzle-orm";
+import { db } from "@/db";
+import { auditIssues } from "@/db/schema";
+
+/**
+ * Distinct-page counts per issue type for one audit — link-level issues
+ * write one row per occurrence, and consumers phrase this as "N pages".
+ * Lives beside AuditRepository (same pattern as rank-tracking's
+ * snapshotQueries) to keep the main repository under the file-size limit.
+ */
+export async function getIssueTypePageCountsForAudit(auditId: string) {
+ return db
+ .select({
+ issueType: auditIssues.issueType,
+ severity: auditIssues.severity,
+ pages: countDistinct(auditIssues.pageUrl),
+ })
+ .from(auditIssues)
+ .where(eq(auditIssues.auditId, auditId))
+ .groupBy(auditIssues.issueType, auditIssues.severity);
+}
diff --git a/src/server/features/dashboard/repositories/BacklinkSnapshotRepository.ts b/src/server/features/dashboard/repositories/BacklinkSnapshotRepository.ts
new file mode 100644
index 0000000..977129e
--- /dev/null
+++ b/src/server/features/dashboard/repositories/BacklinkSnapshotRepository.ts
@@ -0,0 +1,34 @@
+import { desc, eq } from "drizzle-orm";
+import { db } from "@/db";
+import { backlinkSnapshots } from "@/db/schema";
+
+type BacklinkSnapshot = typeof backlinkSnapshots.$inferSelect;
+
+async function getLatestForProject(
+ projectId: string,
+): Promise {
+ const rows = await db
+ .select()
+ .from(backlinkSnapshots)
+ .where(eq(backlinkSnapshots.projectId, projectId))
+ // id, not capturedAt: autoincrement is monotonic and immune to the
+ // sqlite-vs-pg timestamp text-format difference.
+ .orderBy(desc(backlinkSnapshots.id))
+ .limit(1);
+ return rows[0] ?? null;
+}
+
+async function insert(
+ values: typeof backlinkSnapshots.$inferInsert,
+): Promise {
+ const [row] = await db.insert(backlinkSnapshots).values(values).returning();
+ if (!row) {
+ throw new Error("Failed to insert backlink_snapshot");
+ }
+ return row;
+}
+
+export const BacklinkSnapshotRepository = {
+ getLatestForProject,
+ insert,
+};
diff --git a/src/server/features/dashboard/services/DashboardService.ts b/src/server/features/dashboard/services/DashboardService.ts
new file mode 100644
index 0000000..cecbb99
--- /dev/null
+++ b/src/server/features/dashboard/services/DashboardService.ts
@@ -0,0 +1,273 @@
+import type { BillingCustomerContext } from "@/server/billing/subscription";
+import { ActivationRepository } from "@/server/features/activation/repositories/ActivationRepository";
+import { AuditRepository } from "@/server/features/audit/repositories/AuditRepository";
+import { getIssueTypePageCountsForAudit } from "@/server/features/audit/repositories/auditSummaryQueries";
+import { BacklinkSnapshotRepository } from "@/server/features/dashboard/repositories/BacklinkSnapshotRepository";
+import { GscConnectionRepository } from "@/server/features/gsc/repositories/GscConnectionRepository";
+import { RankTrackingRepository } from "@/server/features/rank-tracking/repositories/RankTrackingRepository";
+import { getLatestResults } from "@/server/features/rank-tracking/services/rankTrackingResults";
+import {
+ createDataforseoClient,
+ normalizeBacklinksTarget,
+} from "@/server/lib/dataforseo";
+
+// Daily cadence: fresh numbers each visit without per-visit spend; a dormant
+// project costs nothing because refreshes are visit-triggered.
+const SNAPSHOT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+// Bounds the per-config result reads on the overview path; projects rarely
+// have more than a couple of configs.
+const MAX_CONFIGS_FOR_OVERVIEW = 5;
+
+export type DashboardActivation = {
+ domain: string | null;
+ gsc: { connected: boolean; siteUrl: string | null };
+ mcp: {
+ authorizedAt: string | null;
+ firstToolCallAt: string | null;
+ cardDismissedAt: string | null;
+ };
+ competitorClickedAt: string | null;
+};
+
+export type DashboardRankSummary = {
+ trackedKeywords: number;
+ improved: number;
+ declined: number;
+ top10: number;
+ lastCheckedAt: string | null;
+};
+
+export type DashboardAuditSummary = {
+ status: "running" | "completed" | "failed";
+ pagesCrawled: number;
+ startedAt: string;
+ // Top issue types by severity then affected-page count, for the card's list.
+ topIssues: {
+ issueType: string;
+ severity: "critical" | "warning" | "info";
+ count: number;
+ }[];
+ totalIssueTypes: number;
+};
+
+export type DashboardBacklinkSummary = {
+ domain: string;
+ rank: number | null;
+ backlinks: number | null;
+ referringDomains: number | null;
+ newBacklinks: number | null;
+ lostBacklinks: number | null;
+ newReferringDomains: number | null;
+ lostReferringDomains: number | null;
+ capturedAt: string;
+ stale: boolean;
+};
+
+type DashboardOverview = {
+ rank: DashboardRankSummary | null;
+ audit: DashboardAuditSummary | null;
+ backlinks: DashboardBacklinkSummary | null;
+};
+
+async function getActivation(input: {
+ projectId: string;
+ organizationId: string;
+ domain: string | null;
+}): Promise {
+ const [gsc, orgActivation, projectActivation] = await Promise.all([
+ GscConnectionRepository.getByProjectId(input.projectId),
+ ActivationRepository.getOrganizationActivation(input.organizationId),
+ ActivationRepository.getProjectActivation(input.projectId),
+ ]);
+
+ return {
+ domain: input.domain,
+ gsc: { connected: gsc !== null, siteUrl: gsc?.siteUrl ?? null },
+ mcp: {
+ authorizedAt: orgActivation?.firstMcpAuthorizedAt ?? null,
+ firstToolCallAt: orgActivation?.firstMcpToolCallAt ?? null,
+ cardDismissedAt: projectActivation?.mcpCardDismissedAt ?? null,
+ },
+ competitorClickedAt: projectActivation?.competitorStepClickedAt ?? null,
+ };
+}
+
+async function getOverview(input: {
+ projectId: string;
+ domain: string | null;
+}): Promise {
+ const [rank, audit, backlinks] = await Promise.all([
+ getRankSummary(input.projectId),
+ getAuditSummary(input.projectId),
+ getBacklinkSummary(input.projectId, input.domain),
+ ]);
+ return { rank, audit, backlinks };
+}
+
+async function getRankSummary(
+ projectId: string,
+): Promise {
+ const configs = await RankTrackingRepository.getConfigsForProject(projectId);
+ if (configs.length === 0) return null;
+
+ const results = await Promise.all(
+ configs
+ .slice(0, MAX_CONFIGS_FOR_OVERVIEW)
+ .map((config) => getLatestResults(config.id, projectId, "7d")),
+ );
+
+ const summary: DashboardRankSummary = {
+ trackedKeywords: 0,
+ improved: 0,
+ declined: 0,
+ top10: 0,
+ lastCheckedAt: null,
+ };
+
+ for (const result of results) {
+ summary.trackedKeywords += result.rows.length;
+ if (
+ result.run &&
+ (!summary.lastCheckedAt ||
+ result.run.lastCheckedAt > summary.lastCheckedAt)
+ ) {
+ summary.lastCheckedAt = result.run.lastCheckedAt;
+ }
+ for (const row of result.rows) {
+ for (const device of ["desktop", "mobile"] as const) {
+ const { position, previousPosition } = row[device];
+ if (position !== null && position <= 10) summary.top10 += 1;
+ if (position === null || previousPosition === null) continue;
+ // Lower position number = better ranking.
+ if (position < previousPosition) summary.improved += 1;
+ else if (position > previousPosition) summary.declined += 1;
+ }
+ }
+ }
+
+ return summary;
+}
+
+async function getAuditSummary(
+ projectId: string,
+): Promise {
+ const audit = await AuditRepository.getLatestAuditForProject(projectId);
+ if (!audit) return null;
+
+ const typeRows = await getIssueTypePageCountsForAudit(audit.id);
+
+ const severityRank = { critical: 0, warning: 1, info: 2 };
+ const sorted = typeRows
+ .map((row) => ({
+ issueType: row.issueType,
+ severity: row.severity,
+ count: row.pages,
+ }))
+ .toSorted(
+ (a, b) =>
+ severityRank[a.severity] - severityRank[b.severity] ||
+ b.count - a.count,
+ );
+
+ return {
+ status: audit.status,
+ pagesCrawled: audit.pagesCrawled,
+ startedAt: audit.startedAt,
+ topIssues: sorted.slice(0, 3),
+ totalIssueTypes: sorted.length,
+ };
+}
+
+function isSnapshotFresh(capturedAt: string): boolean {
+ const capturedMs = Date.parse(capturedAt);
+ if (Number.isNaN(capturedMs)) return false;
+ return Date.now() - capturedMs < SNAPSHOT_MAX_AGE_MS;
+}
+
+async function getBacklinkSummary(
+ projectId: string,
+ domain: string | null,
+): Promise {
+ if (!domain) return null;
+ const snapshot =
+ await BacklinkSnapshotRepository.getLatestForProject(projectId);
+ if (!snapshot || snapshot.domain !== domain) return null;
+ return {
+ domain: snapshot.domain,
+ rank: snapshot.rank,
+ backlinks: snapshot.backlinks,
+ referringDomains: snapshot.referringDomains,
+ newBacklinks: snapshot.newBacklinks,
+ lostBacklinks: snapshot.lostBacklinks,
+ newReferringDomains: snapshot.newReferringDomains,
+ lostReferringDomains: snapshot.lostReferringDomains,
+ capturedAt: snapshot.capturedAt,
+ stale: !isSnapshotFresh(snapshot.capturedAt),
+ };
+}
+
+/**
+ * Visit-triggered snapshot refresh. Fetches only the DataForSEO backlinks
+ * summary (not the history endpoint the backlinks page also pays for) and is
+ * a no-op while the latest snapshot for the current domain is under a day
+ * old. Concurrent loads racing the freshness check can each pay a metered
+ * call — every call is metered, so the race duplicates customer spend on
+ * identical data but never leaks revenue; accepted for now. On a fetch
+ * failure with a stale snapshot in hand, the stale snapshot is returned
+ * rather than surfacing an error card.
+ */
+async function ensureBacklinkSnapshot(input: {
+ projectId: string;
+ domain: string | null;
+ billingCustomer: BillingCustomerContext;
+}): Promise {
+ const { projectId, domain } = input;
+ if (!domain) return null;
+
+ const latest =
+ await BacklinkSnapshotRepository.getLatestForProject(projectId);
+ const latestMatchesDomain = latest !== null && latest.domain === domain;
+ if (latest && latestMatchesDomain && isSnapshotFresh(latest.capturedAt)) {
+ return getBacklinkSummary(projectId, domain);
+ }
+
+ const normalized = normalizeBacklinksTarget(domain, { scope: "domain" });
+ const dataforseo = createDataforseoClient(input.billingCustomer);
+
+ try {
+ const summary = await dataforseo.backlinks.summary({
+ target: normalized.apiTarget,
+ });
+ await BacklinkSnapshotRepository.insert({
+ projectId,
+ domain,
+ rank: summary.rank ?? null,
+ backlinks: summary.backlinks ?? null,
+ referringDomains: summary.referring_domains ?? null,
+ brokenBacklinks: summary.broken_backlinks ?? null,
+ newBacklinks: summary.new_backlinks ?? null,
+ lostBacklinks: summary.lost_backlinks ?? null,
+ newReferringDomains:
+ summary.new_referring_domains ?? summary.new_reffering_domains ?? null,
+ lostReferringDomains:
+ summary.lost_referring_domains ??
+ summary.lost_reffering_domains ??
+ null,
+ capturedAt: new Date().toISOString(),
+ });
+ } catch (error) {
+ if (latestMatchesDomain) {
+ console.error("dashboard: backlink snapshot refresh failed", error);
+ return getBacklinkSummary(projectId, domain);
+ }
+ throw error;
+ }
+
+ return getBacklinkSummary(projectId, domain);
+}
+
+export const DashboardService = {
+ getActivation,
+ getOverview,
+ ensureBacklinkSnapshot,
+};
diff --git a/src/server/features/projects/repositories/ProjectRepository.ts b/src/server/features/projects/repositories/ProjectRepository.ts
index f76b7b9..ab05869 100644
--- a/src/server/features/projects/repositories/ProjectRepository.ts
+++ b/src/server/features/projects/repositories/ProjectRepository.ts
@@ -101,6 +101,31 @@ async function updateProject(
return row;
}
+// Writes only the domain column, for the dashboard's inline domain input.
+async function updateProjectDomain(
+ projectId: string,
+ organizationId: string,
+ domain: string,
+) {
+ const [row] = await db
+ .update(projects)
+ .set({ domain })
+ .where(
+ and(
+ eq(projects.id, projectId),
+ eq(projects.organizationId, organizationId),
+ isNull(projects.archivedAt),
+ ),
+ )
+ .returning();
+
+ if (!row) {
+ throw new AppError("NOT_FOUND");
+ }
+
+ return row;
+}
+
// Writes only the market columns. Onboarding sets the project's market before
// the user has named the project or picked a domain, so it must not go through
// updateProject, whose `domain: input.domain ?? null` would clear the domain.
@@ -197,6 +222,7 @@ export const ProjectRepository = {
getProjectById,
createProject,
updateProject,
+ updateProjectDomain,
updateProjectMarket,
tryCreateDefaultProject,
archiveProject,
diff --git a/src/server/features/projects/services/ProjectService.ts b/src/server/features/projects/services/ProjectService.ts
index 5489f4c..e34f44f 100644
--- a/src/server/features/projects/services/ProjectService.ts
+++ b/src/server/features/projects/services/ProjectService.ts
@@ -6,6 +6,7 @@ import {
listProjects,
listProjectsEnsuringOne,
restoreProject,
+ setProjectDomain,
setProjectMarket,
updateProject,
} from "@/server/features/projects/services/projects";
@@ -15,6 +16,7 @@ export const ProjectService = {
listProjectsEnsuringOne,
createProject,
updateProject,
+ setProjectDomain,
setProjectMarket,
archiveProject,
restoreProject,
diff --git a/src/server/features/projects/services/projects.test.ts b/src/server/features/projects/services/projects.test.ts
index ac8b460..745ce96 100644
--- a/src/server/features/projects/services/projects.test.ts
+++ b/src/server/features/projects/services/projects.test.ts
@@ -3,6 +3,7 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
const mocks = vi.hoisted(() => ({
createProject: vi.fn(),
updateProject: vi.fn(),
+ updateProjectDomain: vi.fn(),
archiveProject: vi.fn(),
restoreProject: vi.fn(),
countProjects: vi.fn(),
@@ -208,6 +209,51 @@ describe("project service", () => {
});
});
+ describe("setProjectDomain", () => {
+ it("canonicalizes a pasted URL to the bare host before writing", async () => {
+ mocks.updateProjectDomain.mockResolvedValue(namedProject);
+ const { setProjectDomain } = await import("./projects");
+
+ await setProjectDomain("org_1", {
+ projectId: "project_acme",
+ domain: "https://www.Acme.com/pricing?ref=x",
+ });
+
+ expect(mocks.updateProjectDomain).toHaveBeenCalledWith(
+ "project_acme",
+ "org_1",
+ "acme.com",
+ );
+ });
+
+ it("rejects junk that the backlink fetch would later refuse", async () => {
+ const { setProjectDomain } = await import("./projects");
+
+ await expect(
+ setProjectDomain("org_1", {
+ projectId: "project_acme",
+ domain: "not a domain",
+ }),
+ ).rejects.toThrow("Enter a valid domain");
+ expect(mocks.updateProjectDomain).not.toHaveBeenCalled();
+ });
+ });
+
+ describe("updateProject domain validation", () => {
+ it("rejects a junk domain instead of storing it", async () => {
+ const { updateProject } = await import("./projects");
+
+ await expect(
+ updateProject("org_1", {
+ projectId: "project_acme",
+ name: "Acme",
+ domain: "999.999.999.999",
+ }),
+ ).rejects.toThrow("Enter a valid domain");
+ expect(mocks.updateProject).not.toHaveBeenCalled();
+ });
+ });
+
describe("setProjectMarket", () => {
it("writes only the market columns, leaving name and domain untouched", async () => {
// Onboarding sets the market before the project is named or given a
diff --git a/src/server/features/projects/services/projects.ts b/src/server/features/projects/services/projects.ts
index dcfd8b8..27d0209 100644
--- a/src/server/features/projects/services/projects.ts
+++ b/src/server/features/projects/services/projects.ts
@@ -2,10 +2,12 @@ import type {
ArchiveProjectInput,
CreateProjectInput,
RestoreProjectInput,
+ SetProjectDomainInput,
SetProjectMarketInput,
UpdateProjectInput,
} from "@/types/schemas/projects";
import { ProjectRepository } from "@/server/features/projects/repositories/ProjectRepository";
+import { normalizeBacklinksTarget } from "@/server/lib/dataforseoBacklinksTarget";
import { AppError } from "@/server/lib/errors";
import { assertLanguageForLocation } from "@/server/lib/market";
import { getLanguageCode } from "@/shared/keyword-locations";
@@ -83,6 +85,24 @@ export async function listProjectsEnsuringOne(organizationId: string) {
return listProjects(organizationId);
}
+/**
+ * Validates and canonicalizes a project domain (lowercase bare host, www and
+ * protocol/path stripped) with the same rules the backlink fetch will apply
+ * later, so junk fails at save time instead of at the first paid call.
+ * Undefined passes through — updateProject uses that to clear the domain.
+ */
+function normalizeProjectDomain(domain: string | undefined) {
+ if (domain === undefined) return undefined;
+ try {
+ return normalizeBacklinksTarget(domain, { scope: "domain" }).apiTarget;
+ } catch {
+ throw new AppError(
+ "VALIDATION_ERROR",
+ "Enter a valid domain, like acme.com.",
+ );
+ }
+}
+
export async function createProject(
organizationId: string,
input: CreateProjectInput,
@@ -91,7 +111,7 @@ export async function createProject(
const row = await ProjectRepository.createProject(
organizationId,
input.name,
- input.domain,
+ normalizeProjectDomain(input.domain),
resolveMarketInput(input),
);
return mapProject(row);
@@ -113,7 +133,7 @@ export async function updateProject(
organizationId,
{
name: input.name,
- domain: input.domain,
+ domain: normalizeProjectDomain(input.domain),
market: resolveMarketInput(input),
},
);
@@ -126,6 +146,27 @@ export async function updateProject(
}
}
+/**
+ * Sets a project's domain on its own, for the dashboard hero's inline input.
+ * Writing just this column keeps the write from echoing a name/market the
+ * caller never edited.
+ */
+export async function setProjectDomain(
+ organizationId: string,
+ input: SetProjectDomainInput,
+) {
+ const domain = normalizeProjectDomain(input.domain);
+ if (domain === undefined) {
+ throw new AppError("VALIDATION_ERROR", "Enter a valid domain.");
+ }
+ const row = await ProjectRepository.updateProjectDomain(
+ input.projectId,
+ organizationId,
+ domain,
+ );
+ return mapProject(row);
+}
+
/**
* Sets a project's default market on its own, for surfaces that only ask for
* the market (onboarding). Writing just these two columns keeps the write from
diff --git a/src/server/mcp/instrumentation.test.ts b/src/server/mcp/instrumentation.test.ts
index 463d290..bcf0881 100644
--- a/src/server/mcp/instrumentation.test.ts
+++ b/src/server/mcp/instrumentation.test.ts
@@ -11,6 +11,7 @@ import { AppError } from "@/server/lib/errors";
const mocks = vi.hoisted(() => ({
captureServerError: vi.fn(),
captureServerEvent: vi.fn(),
+ recordExternalMcpToolCall: vi.fn(),
incrementSelfHostMcpToolCallCount: vi.fn(),
}));
@@ -24,6 +25,12 @@ vi.mock("@/server/lib/posthog", () => ({
captureServerEvent: mocks.captureServerEvent,
}));
+// The real module pulls in @/db (cloudflare:workers env) — mock it out and
+// assert the milestone hook at this boundary instead.
+vi.mock("@/server/features/activation/mcpActivation", () => ({
+ recordExternalMcpToolCall: mocks.recordExternalMcpToolCall,
+}));
+
vi.mock("@/server/lib/self-host-telemetry", () => ({
incrementSelfHostMcpToolCallCount: mocks.incrementSelfHostMcpToolCallCount,
}));
@@ -56,6 +63,7 @@ describe("instrumentMcpToolHandler", () => {
beforeEach(() => {
mocks.captureServerError.mockReset();
mocks.captureServerEvent.mockReset();
+ mocks.recordExternalMcpToolCall.mockReset();
mocks.incrementSelfHostMcpToolCallCount.mockReset();
});
@@ -172,5 +180,45 @@ describe("instrumentMcpToolHandler", () => {
await wrapped({}, toolExtra);
expect(mocks.captureServerEvent).not.toHaveBeenCalled();
+ expect(mocks.recordExternalMcpToolCall).not.toHaveBeenCalled();
+ });
+
+ it("records the activation milestone for a successful external call", async () => {
+ const { instrumentMcpToolHandler } = await import("./instrumentation");
+ const wrapped = instrumentMcpToolHandler("demo", outputSchema, async () =>
+ okResult({ items: [] }),
+ );
+
+ await runWithMcpToolAuthContext(authContext, () => wrapped({}, toolExtra));
+
+ expect(mocks.recordExternalMcpToolCall).toHaveBeenCalledExactlyOnceWith(
+ "org-1",
+ );
+ });
+
+ it("skips the activation milestone for first-party (null clientId) calls", async () => {
+ const { instrumentMcpToolHandler } = await import("./instrumentation");
+ const wrapped = instrumentMcpToolHandler("demo", outputSchema, async () =>
+ okResult({ items: [] }),
+ );
+
+ await runWithMcpToolAuthContext({ ...authContext, clientId: null }, () =>
+ wrapped({}, toolExtra),
+ );
+
+ expect(mocks.recordExternalMcpToolCall).not.toHaveBeenCalled();
+ });
+
+ it("skips the activation milestone when the call fails", async () => {
+ const { instrumentMcpToolHandler } = await import("./instrumentation");
+ const wrapped = instrumentMcpToolHandler("demo", outputSchema, async () => {
+ throw new AppError("NOT_FOUND");
+ });
+
+ await expect(
+ runWithMcpToolAuthContext(authContext, () => wrapped({}, toolExtra)),
+ ).rejects.toThrow("NOT_FOUND");
+
+ expect(mocks.recordExternalMcpToolCall).not.toHaveBeenCalled();
});
});
diff --git a/src/server/mcp/instrumentation.ts b/src/server/mcp/instrumentation.ts
index 9df401a..c297f08 100644
--- a/src/server/mcp/instrumentation.ts
+++ b/src/server/mcp/instrumentation.ts
@@ -8,6 +8,7 @@ import {
type ZodRawShapeCompat,
} from "@modelcontextprotocol/sdk/server/zod-compat.js";
import { asAppError } from "@/server/lib/errors";
+import { recordExternalMcpToolCall } from "@/server/features/activation/mcpActivation";
import { captureServerError, captureServerEvent } from "@/server/lib/posthog";
import { shouldCaptureAppErrorCode } from "@/shared/error-codes";
import { getAuth, type ToolExtra } from "@/server/mcp/context";
@@ -114,6 +115,21 @@ export function instrumentMcpToolHandler(
? { success: false, errorCode: "MCP_OUTPUT_VALIDATION" }
: { success: !result.isError },
);
+ // Dashboard activation milestone: a successful call from an external
+ // MCP client (OAuth clientId; SAM and the self-hosted transport are
+ // first-party with clientId null). Awaited so the write stays inside
+ // the request's DB scope; a per-isolate memo keeps this off the hot
+ // path after the first call.
+ if (!result.isError && !outputValidationFailed) {
+ try {
+ const auth = getAuth(extra);
+ if (auth.clientId) {
+ await recordExternalMcpToolCall(auth.organizationId);
+ }
+ } catch {
+ // no auth context — skip milestone tracking
+ }
+ }
return result;
} catch (error) {
const appError = asAppError(error);
diff --git a/src/server/mcp/oauth-provider.ts b/src/server/mcp/oauth-provider.ts
index 9c35fb3..5026c58 100644
--- a/src/server/mcp/oauth-provider.ts
+++ b/src/server/mcp/oauth-provider.ts
@@ -13,6 +13,7 @@ import {
MCP_SCOPE,
} from "@/lib/oauth-resource";
import { asAppError } from "@/server/lib/errors";
+import { recordMcpAuthorized } from "@/server/features/activation/mcpActivation";
import { captureServerEvent } from "@/server/lib/posthog";
import {
createWorkersOAuthMcpProps,
@@ -366,6 +367,8 @@ async function handleOAuthConsentResponse(
props,
});
+ await recordMcpAuthorized(context.organizationId);
+
waitUntil(
captureServerEvent({
distinctId: context.userId,
diff --git a/src/serverFunctions/dashboard.ts b/src/serverFunctions/dashboard.ts
new file mode 100644
index 0000000..ef9b5cf
--- /dev/null
+++ b/src/serverFunctions/dashboard.ts
@@ -0,0 +1,63 @@
+import { createServerFn } from "@tanstack/react-start";
+import { ActivationRepository } from "@/server/features/activation/repositories/ActivationRepository";
+import { DashboardService } from "@/server/features/dashboard/services/DashboardService";
+import { requireProjectContext } from "@/serverFunctions/middleware";
+import { dashboardProjectInputSchema } from "@/types/schemas/dashboard";
+
+export const getDashboardActivation = createServerFn({ method: "POST" })
+ .middleware(requireProjectContext)
+ .validator(dashboardProjectInputSchema)
+ .handler(({ context }) =>
+ DashboardService.getActivation({
+ projectId: context.projectId,
+ organizationId: context.organizationId,
+ domain: context.project.domain,
+ }),
+ );
+
+export const getDashboardOverview = createServerFn({ method: "POST" })
+ .middleware(requireProjectContext)
+ .validator(dashboardProjectInputSchema)
+ .handler(({ context }) =>
+ DashboardService.getOverview({
+ projectId: context.projectId,
+ domain: context.project.domain,
+ }),
+ );
+
+// Visit-triggered: the client calls this when the overview reports a missing
+// or stale backlink snapshot. Metered against org credits at most once per
+// project per day (the service re-checks freshness server-side).
+export const refreshDashboardBacklinkSnapshot = createServerFn({
+ method: "POST",
+})
+ .middleware(requireProjectContext)
+ .validator(dashboardProjectInputSchema)
+ .handler(({ context }) =>
+ DashboardService.ensureBacklinkSnapshot({
+ projectId: context.projectId,
+ domain: context.project.domain,
+ billingCustomer: context,
+ }),
+ );
+
+export const markDashboardCompetitorClicked = createServerFn({
+ method: "POST",
+})
+ .middleware(requireProjectContext)
+ .validator(dashboardProjectInputSchema)
+ .handler(async ({ context }) => {
+ await ActivationRepository.markCompetitorStepClicked(context.projectId);
+ return { ok: true as const };
+ });
+
+// "I already connected" on the MCP card. Hides the card for this project;
+// the org-level milestone stays untouched and self-corrects on the next
+// real external tool call.
+export const dismissDashboardMcpCard = createServerFn({ method: "POST" })
+ .middleware(requireProjectContext)
+ .validator(dashboardProjectInputSchema)
+ .handler(async ({ context }) => {
+ await ActivationRepository.markMcpCardDismissed(context.projectId);
+ return { ok: true as const };
+ });
diff --git a/src/serverFunctions/projects.ts b/src/serverFunctions/projects.ts
index a8da794..90378cc 100644
--- a/src/serverFunctions/projects.ts
+++ b/src/serverFunctions/projects.ts
@@ -8,6 +8,7 @@ import {
archiveProjectSchema,
createProjectSchema,
restoreProjectSchema,
+ setProjectDomainSchema,
setProjectMarketSchema,
updateProjectSchema,
} from "@/types/schemas/projects";
@@ -35,6 +36,13 @@ export const updateProject = createServerFn({ method: "POST" })
ProjectService.updateProject(context.organizationId, data),
);
+export const setProjectDomain = createServerFn({ method: "POST" })
+ .middleware(requireProjectContext)
+ .validator(setProjectDomainSchema)
+ .handler(async ({ data, context }) =>
+ ProjectService.setProjectDomain(context.organizationId, data),
+ );
+
export const setProjectMarket = createServerFn({ method: "POST" })
.middleware(requireProjectContext)
.validator(setProjectMarketSchema)
diff --git a/src/types/schemas/dashboard.ts b/src/types/schemas/dashboard.ts
new file mode 100644
index 0000000..29b7690
--- /dev/null
+++ b/src/types/schemas/dashboard.ts
@@ -0,0 +1,13 @@
+import { z } from "zod";
+
+export const dashboardHeroStepSchema = z.enum([
+ "domain",
+ "mcp",
+ "gsc",
+ "competitor",
+]);
+export type DashboardHeroStep = z.infer;
+
+export const dashboardProjectInputSchema = z.object({
+ projectId: z.string().min(1),
+});
diff --git a/src/types/schemas/projects.ts b/src/types/schemas/projects.ts
index 98180a1..31a29b8 100644
--- a/src/types/schemas/projects.ts
+++ b/src/types/schemas/projects.ts
@@ -63,6 +63,13 @@ export const updateProjectSchema = z
})
.refine(hasLocationForLanguage, marketPairMessage);
+// Domain on its own, for the dashboard hero's inline input. Same loose shape
+// as updateProjectSchema's domain field, but required.
+export const setProjectDomainSchema = z.object({
+ projectId: z.string().min(1),
+ domain: z.string().trim().min(1).max(255),
+});
+
// Market-only update (onboarding). Both halves are required: the caller picks
// them together, so the service can validate the pair without a stored row.
export const setProjectMarketSchema = z.object({
@@ -89,6 +96,7 @@ export const restoreProjectSchema = z.object({
export type CreateProjectInput = z.infer;
export type UpdateProjectInput = z.infer;
+export type SetProjectDomainInput = z.infer;
export type SetProjectMarketInput = z.infer;
export type ArchiveProjectInput = z.infer;
export type RestoreProjectInput = z.infer;