next-arch-map 0.1.25 → 0.1.26

package/dist/analyzers/prismaSchema.d.ts

@@ -0,0 +1,5 @@
+import type { Edge, Node } from "../model.js";
+export declare function analyzePrismaSchema(projectRoot: string): Promise<{
+    nodes: Node[];
+    edges: Edge[];
+}>;

package/dist/analyzers/prismaSchema.js

@@ -0,0 +1,284 @@
+import fs from "node:fs";
+import path from "node:path";
+const MODEL_BLOCK_PATTERN = /^model\s+(\w+)\s*\{/;
+const ENUM_BLOCK_PATTERN = /^enum\s+(\w+)\s*\{/;
+const SCALAR_TYPES = new Set([
+    "String",
+    "Int",
+    "Float",
+    "Boolean",
+    "DateTime",
+    "Json",
+    "Bytes",
+    "Decimal",
+    "BigInt",
+]);
+export async function analyzePrismaSchema(projectRoot) {
+    const schemaPath = path.join(projectRoot, "prisma", "schema.prisma");
+    if (!fs.existsSync(schemaPath)) {
+        return { nodes: [], edges: [] };
+    }
+    let content;
+    try {
+        content = fs.readFileSync(schemaPath, "utf8");
+    }
+    catch {
+        return { nodes: [], edges: [] };
+    }
+    const models = parseModels(content);
+    const enumNames = parseEnumNames(content);
+    const nodes = [];
+    const edges = [];
+    const edgeKeys = new Set();
+    // Build a map from lowercase model name to the camelCase form used by Prisma client
+    const modelIdMap = new Map();
+    for (const model of models) {
+        const camelCase = model.name.charAt(0).toLowerCase() + model.name.slice(1);
+        modelIdMap.set(model.name, camelCase);
+    }
+    for (const model of models) {
+        const camelName = modelIdMap.get(model.name) ?? model.name;
+        const nodeId = `db:${camelName}`;
+        nodes.push({
+            id: nodeId,
+            type: "db",
+            label: model.name,
+            meta: {
+                filePath: "prisma/schema.prisma",
+                model: model.name,
+                columns: model.columns,
+            },
+        });
+        for (const relation of model.relations) {
+            if (relation.isList) {
+                // Skip list relations — the "belongs-to" side will create the edge
+                continue;
+            }
+            const fromId = nodeId;
+            const relatedCamelName = modelIdMap.get(relation.relatedModel) ?? relation.relatedModel;
+            const toId = `db:${relatedCamelName}`;
+            const edgeKey = `${fromId}::${toId}::db-relation`;
+            if (edgeKeys.has(edgeKey)) {
+                continue;
+            }
+            edgeKeys.add(edgeKey);
+            edges.push({
+                from: fromId,
+                to: toId,
+                kind: "db-relation",
+                meta: {
+                    field: relation.foreignKey ?? relation.field,
+                    foreignKey: "id",
+                },
+            });
+        }
+    }
+    return {
+        nodes: nodes.sort((a, b) => a.id.localeCompare(b.id)),
+        edges: edges.sort((a, b) => a.kind.localeCompare(b.kind) ||
+            a.from.localeCompare(b.from) ||
+            a.to.localeCompare(b.to)),
+    };
+}
+function parseEnumNames(content) {
+    const names = new Set();
+    const lines = content.split("\n");
+    for (const line of lines) {
+        const match = ENUM_BLOCK_PATTERN.exec(line.trim());
+        if (match) {
+            names.add(match[1]);
+        }
+    }
+    return names;
+}
+function parseModels(content) {
+    const models = [];
+    const lines = content.split("\n");
+    const modelNames = new Set();
+    const enumNames = parseEnumNames(content);
+    // First pass: collect all model names
+    for (const line of lines) {
+        const match = MODEL_BLOCK_PATTERN.exec(line.trim());
+        if (match) {
+            modelNames.add(match[1]);
+        }
+    }
+    let currentModel = null;
+    let braceDepth = 0;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!currentModel) {
+            const match = MODEL_BLOCK_PATTERN.exec(trimmed);
+            if (match) {
+                currentModel = { name: match[1], columns: [], relations: [] };
+                braceDepth = 1;
+            }
+            continue;
+        }
+        // Track brace depth
+        for (const ch of trimmed) {
+            if (ch === "{")
+                braceDepth++;
+            if (ch === "}")
+                braceDepth--;
+        }
+        if (braceDepth <= 0) {
+            models.push(currentModel);
+            currentModel = null;
+            continue;
+        }
+        // Skip comments, empty lines, and @@-level attributes
+        if (!trimmed || trimmed.startsWith("//") || trimmed.startsWith("@@")) {
+            continue;
+        }
+        const field = parseField(trimmed, modelNames, enumNames);
+        if (!field) {
+            continue;
+        }
+        if (field.kind === "relation") {
+            currentModel.relations.push(field.relation);
+        }
+        else {
+            currentModel.columns.push(field.column);
+        }
+    }
+    if (currentModel) {
+        models.push(currentModel);
+    }
+    return models;
+}
+function parseField(line, modelNames, enumNames) {
+    // Tokenize: split on whitespace but respect parentheses content
+    const tokens = tokenizeLine(line);
+    if (tokens.length < 2) {
+        return null;
+    }
+    const fieldName = tokens[0];
+    let rawType = tokens[1];
+    // Skip if field name starts with @ (attribute line)
+    if (fieldName.startsWith("@")) {
+        return null;
+    }
+    const isList = rawType.endsWith("[]");
+    const isOptional = rawType.endsWith("?");
+    if (isList) {
+        rawType = rawType.slice(0, -2);
+    }
+    else if (isOptional) {
+        rawType = rawType.slice(0, -1);
+    }
+    const isRequired = !isOptional && !isList;
+    // Check if it's a relation field (type references another model)
+    if (modelNames.has(rawType)) {
+        const relation = {
+            field: fieldName,
+            relatedModel: rawType,
+            isList,
+        };
+        // Extract @relation fields/references
+        const relationAttr = extractAttribute(tokens, "@relation");
+        if (relationAttr) {
+            const fields = extractArrayParam(relationAttr, "fields");
+            const references = extractArrayParam(relationAttr, "references");
+            if (fields && fields.length > 0) {
+                relation.foreignKey = fields[0];
+            }
+            if (!relation.foreignKey && references && references.length > 0) {
+                // fallback
+            }
+        }
+        return { kind: "relation", relation };
+    }
+    // It's a column
+    const column = {
+        name: fieldName,
+        type: rawType,
+        isId: false,
+        isRequired,
+        isUnique: false,
+    };
+    const restTokens = tokens.slice(2);
+    const restLine = restTokens.join(" ");
+    if (restLine.includes("@id")) {
+        column.isId = true;
+    }
+    if (restLine.includes("@unique")) {
+        column.isUnique = true;
+    }
+    const defaultMatch = /@default\(([^)]*)\)/.exec(restLine);
+    if (defaultMatch) {
+        column.default = defaultMatch[1];
+    }
+    const mapMatch = /@map\("([^"]*)"\)/.exec(restLine);
+    if (mapMatch) {
+        column.map = mapMatch[1];
+    }
+    return { kind: "column", column };
+}
+function tokenizeLine(line) {
+    const tokens = [];
+    let current = "";
+    let parenDepth = 0;
+    let inString = false;
+    let stringChar = "";
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (inString) {
+            current += ch;
+            if (ch === stringChar) {
+                inString = false;
+            }
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            inString = true;
+            stringChar = ch;
+            current += ch;
+            continue;
+        }
+        if (ch === "(") {
+            parenDepth++;
+            current += ch;
+            continue;
+        }
+        if (ch === ")") {
+            parenDepth--;
+            current += ch;
+            continue;
+        }
+        if (/\s/.test(ch) && parenDepth === 0) {
+            if (current) {
+                tokens.push(current);
+                current = "";
+            }
+            continue;
+        }
+        current += ch;
+    }
+    if (current) {
+        tokens.push(current);
+    }
+    return tokens;
+}
+function extractAttribute(tokens, attrName) {
+    for (const token of tokens) {
+        if (token.startsWith(attrName + "(")) {
+            return token;
+        }
+        if (token === attrName) {
+            return token;
+        }
+    }
+    return null;
+}
+function extractArrayParam(attrString, paramName) {
+    const pattern = new RegExp(`${paramName}:\\s*\\[([^\\]]*)]`);
+    const match = pattern.exec(attrString);
+    if (!match) {
+        return null;
+    }
+    return match[1]
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}

package/dist/cli.js

@@ -3,11 +3,23 @@ import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { analyzeProject, diffGraphs } from "./index.js";
+import { generateDescribeContext } from "./describe.js";
 import { captureScreenshots, generateParamsTemplate, } from "./screenshot.js";
 import { serve } from "./serve.js";
 import { readJsonFile, writeJsonFile } from "./utils.js";
 async function main() {
     const [commandOrArg, ...rest] = process.argv.slice(2);
+    if (commandOrArg === "describe") {
+        const options = parseDescribeArgs(rest);
+        const result = generateDescribeContext({
+            graphPath: path.resolve(options.graphPath),
+            outPath: path.resolve(options.outPath),
+            onlyMissing: !options.all,
+        });
+        console.log(`describe context written to ${options.outPath} (${result.nodeCount} nodes)`);
+        console.log(`Tell your AI: "Read ${options.outPath} and update the descriptions in ${options.graphPath}"`);
+        return;
+    }
     if (commandOrArg === "dev") {
         const options = parseDevArgs(rest);
         await runDev(options);
@@ -261,6 +273,34 @@ function parseScreenshotArgs(args) {
     }
     return { baseUrl, graphPath, outDir, paramsPath, generateParams };
 }
+function parseDescribeArgs(args) {
+    let graphPath = "arch/graph.full.json";
+    let outPath = "arch/describe-context.md";
+    let all = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === "--graph" && args[index + 1]) {
+            graphPath = args[index + 1];
+            index += 1;
+            continue;
+        }
+        if (argument === "--out" && args[index + 1]) {
+            outPath = args[index + 1];
+            index += 1;
+            continue;
+        }
+        if (argument === "--all") {
+            all = true;
+            continue;
+        }
+        if (argument === "--help" || argument === "-h") {
+            printHelp();
+            process.exit(0);
+        }
+        throw new Error(`Unknown argument: ${argument}`);
+    }
+    return { graphPath, outPath, all };
+}
 async function runDev(options) {
     const children = [];
     const cleanup = () => {
@@ -361,6 +401,7 @@ function logScreenshotSummary(result) {
 function printHelp() {
     console.log(`next-arch-map analyze [options]
 next-arch-map diff --before <path> --after <path> [--out <path>]
+next-arch-map describe [options]
 next-arch-map screenshot [options]
 next-arch-map serve [options]
 next-arch-map dev [options]
@@ -375,6 +416,11 @@ Diff options:
   --after <path>         Path to the updated graph JSON.
   --out <path>           Output diff JSON path. Defaults to arch/graph.diff.json.
 
+Describe options:
+  --graph <path>         Path to graph JSON. Defaults to arch/graph.full.json.
+  --out <path>           Output context file. Defaults to arch/describe-context.md.
+  --all                  Include all nodes, not just those missing descriptions.
+
 Screenshot options:
   --base-url <url>       Base URL of the running app (e.g. http://localhost:3000).
   --graph <path>         Path to graph JSON. Defaults to arch/graph.full.json.

package/dist/describe.d.ts

@@ -0,0 +1,9 @@
+export type DescribeOptions = {
+    graphPath: string;
+    outPath: string;
+    onlyMissing: boolean;
+};
+export declare function generateDescribeContext(options: DescribeOptions): {
+    contextPath: string;
+    nodeCount: number;
+};

package/dist/describe.js

@@ -0,0 +1,66 @@
+import fs from "node:fs";
+import path from "node:path";
+import { ensureDirectory, readJsonFile } from "./utils.js";
+function needsDescription(node, onlyMissing) {
+    if (!onlyMissing)
+        return true;
+    return !node.meta?.description;
+}
+function readSourceSafe(filePath) {
+    try {
+        if (fs.existsSync(filePath)) {
+            return fs.readFileSync(filePath, "utf8");
+        }
+    }
+    catch {
+        // ignore
+    }
+    return null;
+}
+export function generateDescribeContext(options) {
+    const graph = readJsonFile(options.graphPath);
+    const nodes = graph.nodes.filter((node) => needsDescription(node, options.onlyMissing));
+    const lines = [
+        "# Describe Architecture Graph Nodes",
+        "",
+        `Update the node descriptions in \`${options.graphPath}\`.`,
+        "",
+        "For **every** node listed below, read the source code and add two fields to its `meta` object:",
+        "",
+        "- `meta.description` — A single sentence (under 80 characters). Displayed inside the node box in the viewer.",
+        "- `meta.descriptionLong` — 2-3 sentences with more context. Shown in the details panel when clicking the node.",
+        "",
+        "## Style guide",
+        "",
+        "- Present tense, third person (\"Displays...\", \"Handles...\", \"Stores...\").",
+        "- Be specific — prefer \"Displays paginated user list with search\" over \"Shows users\".",
+        "- Don't repeat the node label — add information beyond what the name already tells you.",
+        "",
+        `## Nodes (${nodes.length})`,
+        "",
+    ];
+    for (const node of nodes) {
+        const filePath = node.meta?.filePath ? String(node.meta.filePath) : null;
+        const source = filePath ? readSourceSafe(filePath) : null;
+        lines.push(`### ${node.id}`);
+        lines.push("");
+        lines.push(`- **Type:** ${node.type}`);
+        lines.push(`- **Label:** ${node.label}`);
+        if (filePath) {
+            lines.push(`- **File:** ${filePath}`);
+        }
+        if (node.meta?.description) {
+            lines.push(`- **Current description:** ${String(node.meta.description)}`);
+        }
+        if (source) {
+            lines.push("");
+            lines.push("```typescript");
+            lines.push(source.trimEnd());
+            lines.push("```");
+        }
+        lines.push("");
+    }
+    ensureDirectory(path.dirname(options.outPath));
+    fs.writeFileSync(options.outPath, lines.join("\n"), "utf8");
+    return { contextPath: options.outPath, nodeCount: nodes.length };
+}

package/dist/index.d.ts

@@ -14,6 +14,8 @@ export type { DiffStatus, EdgeDiff, GraphDiff, NodeDiff } from "./diff.js";
 export type { Edge, EdgeKind, Graph, Node, NodeType } from "./model.js";
 export { analyzePagesToEndpoints } from "./analyzers/pagesToEndpoints.js";
 export { analyzeEndpointsToDb } from "./analyzers/endpointsToDb.js";
+export { analyzePrismaSchema } from "./analyzers/prismaSchema.js";
 export { mergeGraphs, mergePartial } from "./merge.js";
 export { getDbModelsForPage, getEndpointsForPage, getPagesForDbModel } from "./query.js";
+export { generateDescribeContext } from "./describe.js";
 export { captureScreenshots, generateParamsTemplate } from "./screenshot.js";

package/dist/index.js

@@ -1,5 +1,6 @@
 import { analyzeEndpointsToDb } from "./analyzers/endpointsToDb.js";
 import { analyzePagesToEndpoints } from "./analyzers/pagesToEndpoints.js";
+import { analyzePrismaSchema } from "./analyzers/prismaSchema.js";
 import { mergePartial } from "./merge.js";
 export async function analyzeProject(options) {
     const pagesToEndpoints = await analyzePagesToEndpoints({
@@ -14,11 +15,14 @@ export async function analyzeProject(options) {
         apiDirs: options.apiDirs,
         dbClientIdentifiers: options.dbClientIdentifiers,
     });
-    return mergePartial(pagesToEndpoints, endpointsToDb);
+    const prismaSchema = await analyzePrismaSchema(options.projectRoot);
+    return mergePartial(mergePartial(pagesToEndpoints, endpointsToDb), prismaSchema);
 }
 export { diffGraphs } from "./diff.js";
 export { analyzePagesToEndpoints } from "./analyzers/pagesToEndpoints.js";
 export { analyzeEndpointsToDb } from "./analyzers/endpointsToDb.js";
+export { analyzePrismaSchema } from "./analyzers/prismaSchema.js";
 export { mergeGraphs, mergePartial } from "./merge.js";
 export { getDbModelsForPage, getEndpointsForPage, getPagesForDbModel } from "./query.js";
+export { generateDescribeContext } from "./describe.js";
 export { captureScreenshots, generateParamsTemplate } from "./screenshot.js";

package/dist/model.d.ts

@@ -5,7 +5,7 @@ export type Node = {
     label: string;
     meta?: Record<string, any>;
 };
-export type EdgeKind = "page-endpoint" | "endpoint-db" | "endpoint-handler" | "page-action" | "action-endpoint";
+export type EdgeKind = "page-endpoint" | "endpoint-db" | "endpoint-handler" | "page-action" | "action-endpoint" | "db-relation";
 export type Edge = {
     from: string;
     to: string;

package/dist/serve.d.ts

@@ -2,5 +2,6 @@ export type ServeOptions = {
     projectRoot: string;
     port?: number;
     appDirs?: string[];
+    graphPath?: string;
 };
 export declare function serve(options: ServeOptions): Promise<void>;

package/dist/serve.js

@@ -1,16 +1,53 @@
+import fs from "node:fs";
 import http from "node:http";
 import path from "node:path";
 import chokidar from "chokidar";
 import { analyzeProject } from "./index.js";
 import { diffGraphs } from "./diff.js";
 import { getDbModelsForPage, getEndpointsForPage, getPagesForDbModel } from "./query.js";
+import { readJsonFile, writeJsonFile } from "./utils.js";
+const PRESERVED_META_KEYS = ["description", "descriptionLong", "screenshot"];
+function preserveMetaFields(freshGraph, existingGraph) {
+    const existingById = new Map();
+    for (const node of existingGraph.nodes) {
+        existingById.set(node.id, node);
+    }
+    for (const node of freshGraph.nodes) {
+        const existing = existingById.get(node.id);
+        if (!existing?.meta)
+            continue;
+        for (const key of PRESERVED_META_KEYS) {
+            if (key in existing.meta) {
+                if (!node.meta)
+                    node.meta = {};
+                // Only carry forward if the fresh analysis didn't set it
+                if (!(key in node.meta)) {
+                    node.meta[key] = existing.meta[key];
+                }
+            }
+        }
+    }
+}
 export async function serve(options) {
     const projectRoot = path.resolve(options.projectRoot);
     const port = options.port ?? 4321;
+    const graphPath = path.resolve(projectRoot, options.graphPath ?? "arch/graph.full.json");
     let currentGraph = null;
     let previousGraph = null;
     let isAnalyzing = false;
     let rerunRequested = false;
+    let suppressGraphFileWatch = false;
+    function readExistingGraph() {
+        try {
+            if (fs.existsSync(graphPath)) {
+                return readJsonFile(graphPath);
+            }
+        }
+        catch {
+            // ignore corrupt file
+        }
+        return null;
+    }
     async function runAnalysis() {
         if (isAnalyzing) {
             rerunRequested = true;
@@ -22,8 +59,20 @@ export async function serve(options) {
                 projectRoot,
                 appDirs: options.appDirs,
             });
+            // Preserve descriptions/screenshots from the existing graph file
+            const existingGraph = readExistingGraph();
+            if (existingGraph) {
+                preserveMetaFields(nextGraph, existingGraph);
+            }
             previousGraph = currentGraph;
             currentGraph = nextGraph;
+            // Write to disk so AI tools and the CLI can read/edit it
+            suppressGraphFileWatch = true;
+            writeJsonFile(graphPath, currentGraph);
+            // Release suppression after a short delay for the watcher to settle
+            setTimeout(() => {
+                suppressGraphFileWatch = false;
+            }, 500);
             const pageCount = currentGraph.nodes.filter((node) => node.type === "page").length;
             const endpointCount = currentGraph.nodes.filter((node) => node.type === "endpoint").length;
             const handlerCount = currentGraph.nodes.filter((node) => node.type === "handler").length;
@@ -52,13 +101,26 @@ export async function serve(options) {
         }
     }
     await runAnalysis();
-    const watcher = chokidar.watch(projectRoot, {
+    // Watch source files for re-analysis
+    const sourceWatcher = chokidar.watch(projectRoot, {
         ignored: ["**/node_modules/**", "**/.git/**", "**/.next/**", "**/arch/**"],
         ignoreInitial: true,
     });
-    watcher.on("all", () => {
+    sourceWatcher.on("all", () => {
         void runAnalysis();
     });
+    // Watch the graph file for external edits (e.g. AI adding descriptions)
+    const graphWatcher = chokidar.watch(graphPath, { ignoreInitial: true });
+    graphWatcher.on("change", () => {
+        if (suppressGraphFileWatch)
+            return;
+        const updated = readExistingGraph();
+        if (updated) {
+            previousGraph = currentGraph;
+            currentGraph = updated;
+            console.log("mode=serve graph file updated externally, reloaded");
+        }
+    });
     const server = http.createServer((req, res) => {
         res.setHeader("Access-Control-Allow-Origin", "*");
         res.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
@@ -144,7 +206,8 @@ export async function serve(options) {
         });
     });
     const close = async () => {
-        await watcher.close();
+        await sourceWatcher.close();
+        await graphWatcher.close();
         await new Promise((resolve, reject) => {
             server.close((error) => {
                 if (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-arch-map",
-  "version": "0.1.25",
+  "version": "0.1.26",
   "description": "Static analyzer that builds a multi-layer architecture graph for Next.js-style apps.",
   "type": "module",
   "bin": {

package/viewer/src/App.tsx

@@ -15,6 +15,7 @@ const ALL_EDGE_KINDS: EdgeKind[] = [
   "page-endpoint",
   "endpoint-db",
   "endpoint-handler",
+  "db-relation",
 ];
 
 
@@ -498,6 +499,7 @@ function buildFocusedSubgraph(graph: Graph, route: string): Graph {
     "page-endpoint",
     "endpoint-handler",
     "endpoint-db",
+    "db-relation",
   ]);
   const reachableNodeIds = new Set<string>([pageId]);
   const worklist = [pageId];

package/viewer/src/GraphView.tsx

@@ -44,6 +44,9 @@ const EDGE_COLOR: Record<EdgeKind, string> = {
   "page-endpoint": "#06b6d4",
   "endpoint-db": "#f97316",
   "endpoint-handler": "#22c55e",
+  "page-action": "#8b5cf6",
+  "action-endpoint": "#a855f7",
+  "db-relation": "#94a3b8",
 };
 
 const DIFF_BORDER_COLOR: Record<DiffStatus, string> = {
@@ -182,6 +185,102 @@ function PageNode({ data }: NodeProps) {
   );
 }
 
+type DbColumn = {
+  name: string;
+  type: string;
+  isId?: boolean;
+  isRequired?: boolean;
+  isUnique?: boolean;
+  default?: string;
+};
+
+function DbTableNode({ data }: NodeProps) {
+  const d = data as Record<string, unknown>;
+  const label = String(d.label ?? "");
+  const columns = (d.columns as DbColumn[] | undefined) ?? [];
+
+  return (
+    <div
+      style={{
+        background: "#ffffff",
+        border: "1px solid #cbd5e1",
+        borderRadius: 6,
+        overflow: "hidden",
+        fontFamily: "'Inter', -apple-system, sans-serif",
+        fontSize: 11,
+        minWidth: 220,
+      }}
+    >
+      <Handle type="target" position={Position.Left} style={{ visibility: "hidden" }} />
+      {/* Header */}
+      <div
+        style={{
+          background: "#991b1b",
+          color: "#ffffff",
+          padding: "6px 10px",
+          fontWeight: 700,
+          fontSize: 12,
+          letterSpacing: "0.01em",
+        }}
+      >
+        {label}
+      </div>
+      {/* Columns */}
+      {columns.map((col, i) => (
+        <div
+          key={col.name}
+          style={{
+            display: "flex",
+            alignItems: "center",
+            gap: 6,
+            padding: "3px 10px",
+            borderTop: i === 0 ? "none" : "1px solid #f1f5f9",
+            color: "#334155",
+          }}
+        >
+          {col.isId && (
+            <span style={{ fontSize: 10, color: "#eab308" }} title="Primary Key">
+              🔑
+            </span>
+          )}
+          {!col.isId && col.isUnique && (
+            <span style={{ fontSize: 9, color: "#94a3b8" }} title="Unique">
+              U
+            </span>
+          )}
+          {!col.isId && !col.isUnique && (
+            <span style={{ width: 12, display: "inline-block" }} />
+          )}
+          <span style={{ fontWeight: 500, flex: 1 }}>{col.name}</span>
+          <span
+            style={{
+              fontFamily: "'JetBrains Mono', 'Fira Code', monospace",
+              fontSize: 10,
+              color: "#64748b",
+            }}
+          >
+            {col.type}
+          </span>
+          {col.isRequired === false && (
+            <span
+              style={{
+                fontSize: 9,
+                background: "#f1f5f9",
+                color: "#94a3b8",
+                borderRadius: 3,
+                padding: "0 3px",
+              }}
+            >
+              ?
+            </span>
+          )}
+        </div>
+      ))}
+      <Handle type="source" position={Position.Right} style={{ visibility: "hidden" }} />
+    </div>
+  );
+}
+
 function DescribedNode({ data }: NodeProps) {
   const d = data as Record<string, unknown>;
   const description = d.description as string | undefined;
@@ -201,6 +300,7 @@ function DescribedNode({ data }: NodeProps) {
 const nodeTypes = {
   pageNode: PageNode,
   describedNode: DescribedNode,
+  dbTableNode: DbTableNode,
 };
 
 export function GraphView(props: GraphViewProps) {
@@ -263,9 +363,17 @@ export function GraphView(props: GraphViewProps) {
     );
     const pageRowHeight = hasScreenshots ? 140 : defaultRowHeight;
 
+    // Compute max db column count for row height
+    const dbNodes = nodesByType.get("db") ?? [];
+    const maxDbColumns = dbNodes.reduce((max, n) => {
+      const cols = Array.isArray(n.meta?.columns) ? (n.meta?.columns as unknown[]).length : 0;
+      return Math.max(max, cols);
+    }, 0);
+    const dbRowHeight = maxDbColumns > 0 ? Math.max(defaultRowHeight, 30 + maxDbColumns * 22) : defaultRowHeight;
+
     activeTypeOrder.forEach((type, columnIndex) => {
       const nodes = nodesByType.get(type) ?? [];
-      const rowHeight = type === "page" ? pageRowHeight : defaultRowHeight;
+      const rowHeight = type === "page" ? pageRowHeight : type === "db" ? dbRowHeight : defaultRowHeight;
       nodes.forEach((node, rowIndex) => {
         const isSelected = node.id === selectedNodeId;
         const status = nodeStatusById?.get(node.id) ?? "unchanged";
@@ -275,12 +383,18 @@ export function GraphView(props: GraphViewProps) {
         const screenshot = isPage ? (node.meta?.screenshot as string | undefined) : undefined;
         const description = node.meta?.description as string | undefined;
         const isDarkText = false;
+        const isDbTable = node.type === "db" && Array.isArray(node.meta?.columns) && (node.meta?.columns as unknown[]).length > 0;
+        const dbColumns = isDbTable ? (node.meta?.columns as DbColumn[]) : undefined;
+
+        const nodeType = isDbTable
+          ? "dbTableNode"
+          : isPage
+            ? "pageNode"
+            : description
+              ? "describedNode"
+              : undefined;
 
-        const nodeType = isPage
-          ? "pageNode"
-          : description
-            ? "describedNode"
-            : undefined;
+        const nodeWidth = isDbTable ? 240 : 200;
 
         flowNodes.push({
           id: node.id,
@@ -290,6 +404,7 @@ export function GraphView(props: GraphViewProps) {
             ...(screenshot ? { screenshot } : {}),
             ...(description ? { description } : {}),
             ...(isDarkText ? { dark: true } : {}),
+            ...(dbColumns ? { columns: dbColumns } : {}),
           },
           position: {
             x: 80 + columnIndex * columnWidth,
@@ -298,27 +413,39 @@ export function GraphView(props: GraphViewProps) {
           sourcePosition: Position.Right,
           targetPosition: Position.Left,
           selectable: true,
-          style: {
-            width: 200,
-            borderRadius: 12,
-            border: `2px ${borderStyle} ${borderColor}`,
-            padding: "10px 14px",
-            background: NODE_COLOR[node.type],
-            color: "#ffffff",
-            fontSize: 12,
-            fontWeight: 600,
-            fontFamily: "'Inter', -apple-system, sans-serif",
-            letterSpacing: "-0.01em",
-            opacity: status === "removed" ? 0.65 : 1,
-            boxShadow: isSelected
-              ? `0 0 0 3px rgba(30, 41, 59, 0.15), 0 8px 24px rgba(0, 0, 0, 0.12)`
-              : status === "added"
-                ? `0 0 0 3px rgba(34, 197, 94, 0.2)`
-                : status === "removed"
-                  ? `0 0 0 3px rgba(239, 68, 68, 0.15)`
+          style: isDbTable
+            ? {
+                width: nodeWidth,
+                borderRadius: 6,
+                padding: 0,
+                background: "transparent",
+                opacity: status === "removed" ? 0.65 : 1,
+                boxShadow: isSelected
+                  ? `0 0 0 3px rgba(30, 41, 59, 0.15), 0 8px 24px rgba(0, 0, 0, 0.12)`
                   : `0 1px 3px rgba(0, 0, 0, 0.06), 0 4px 12px rgba(0, 0, 0, 0.04)`,
-            transition: "opacity 0.15s ease, box-shadow 0.15s ease, border-color 0.15s ease",
-          },
+                transition: "opacity 0.15s ease, box-shadow 0.15s ease",
+              }
+            : {
+                width: nodeWidth,
+                borderRadius: 12,
+                border: `2px ${borderStyle} ${borderColor}`,
+                padding: "10px 14px",
+                background: NODE_COLOR[node.type],
+                color: "#ffffff",
+                fontSize: 12,
+                fontWeight: 600,
+                fontFamily: "'Inter', -apple-system, sans-serif",
+                letterSpacing: "-0.01em",
+                opacity: status === "removed" ? 0.65 : 1,
+                boxShadow: isSelected
+                  ? `0 0 0 3px rgba(30, 41, 59, 0.15), 0 8px 24px rgba(0, 0, 0, 0.12)`
+                  : status === "added"
+                    ? `0 0 0 3px rgba(34, 197, 94, 0.2)`
+                    : status === "removed"
+                      ? `0 0 0 3px rgba(239, 68, 68, 0.15)`
+                      : `0 1px 3px rgba(0, 0, 0, 0.06), 0 4px 12px rgba(0, 0, 0, 0.04)`,
+                transition: "opacity 0.15s ease, box-shadow 0.15s ease, border-color 0.15s ease",
+              },
         });
       });
     });

package/viewer/src/types.ts

@@ -16,7 +16,8 @@ export type EdgeKind =
   | "endpoint-db"
   | "endpoint-handler"
   | "page-action"
-  | "action-endpoint";
+  | "action-endpoint"
+  | "db-relation";
 
 export type Edge = {
   from: string;