Initial scaffold: Visioning Lab Systems Development Tool

Next.js 14 + TypeScript + Tailwind app implementing the Define -> Structure
-> Insight -> Action workflow with Anthropic Claude for extraction and
generation, editable cards throughout, and PDF/JSON export.

Includes a static-export build path for GitHub Pages (AI features disabled
in that mode) and a Pages deploy workflow.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Jessica Symons

.env.example

@@ -0,0 +1,2 @@
+ANTHROPIC_API_KEY=sk-ant-...
+ANTHROPIC_MODEL=claude-sonnet-4-6

.github/workflows/pages.yml

@@ -0,0 +1,56 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install
+        run: npm ci
+
+      - name: Strip server-only API routes (incompatible with static export)
+        run: rm -rf app/api
+
+      - name: Build static site
+        env:
+          STATIC_EXPORT: "1"
+        run: npm run build
+
+      - name: Add .nojekyll
+        run: touch out/.nojekyll
+
+      - uses: actions/configure-pages@v5
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: out
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -0,0 +1,10 @@
+node_modules
+.next
+out
+dist
+.env
+.env.local
+.DS_Store
+*.log
+.vercel
+next-env.d.ts

README.md

@@ -0,0 +1,96 @@
+# Systems Development Framework
+
+Visioning Lab has developed a Systems Development framework to help organisations work through complex problems in a structured, transparent way.
+
+The approach moves from defining inputs through to action, enabling clearer thinking, better decisions and ongoing system insight.
+
+## Framework Overview
+Define → Structure → Insight → Action
+
+## Define
+
+Capture and clarify what matters across multiple sources and perspectives.
+
+- Documents, meetings, data, stakeholder inputs
+- Structured into clear points
+- Identification of assumptions and implications
+
+## Structure
+
+Organise relationships, options and decision logic.
+
+- Linking points into models
+- Defining options and trade-offs
+- Making reasoning explicit and comparable
+
+## Insight
+
+Identify patterns, signals and system-level implications.
+
+- Recurring issues across inputs
+- Hidden assumptions
+- Emerging risks and opportunities
+
+## Action
+
+Translate insight into interventions and next steps.
+
+- Decisions and action plans
+- Policy or operational changes
+- Feedback into future cycles
+
+## What this enables
+- Structured understanding of complex systems
+- Transparent and explainable decision-making
+- Comparability across cases and organisations
+- Continuous learning over time
+
+## Interactive Tool
+
+An interactive Next.js implementation of the framework lives in this repo.
+It walks the user through Define → Structure → Insight → Action, with
+LLM-assisted extraction at each step and editable outputs throughout.
+
+### Setup
+
+```bash
+npm install
+cp .env.example .env.local   # add your ANTHROPIC_API_KEY
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000).
+
+### Stack
+
+- Next.js 14 (App Router) + TypeScript + Tailwind
+- Anthropic Claude (`claude-sonnet-4-6` by default) for extraction & generation
+- `zod` schemas for the Point / Option / Insight / Action data model
+- `jspdf` for the PDF export
+- Session state autosaved to `localStorage` (no server storage)
+
+### Project layout
+
+- [app/page.tsx](app/page.tsx) — landing
+- [app/tool/](app/tool/) — the four-step flow + export page
+- [app/api/](app/api/) — LLM endpoints (one per step)
+- [lib/schema.ts](lib/schema.ts) — data model
+- [lib/prompts.ts](lib/prompts.ts) — system prompts per step
+- [lib/anthropic.ts](lib/anthropic.ts) — Claude client + JSON helper
+- [lib/session.tsx](lib/session.tsx) — React context + localStorage autosave
+- [lib/pdf.ts](lib/pdf.ts) — PDF + JSON export
+
+## Applications
+- Infrastructure and environmental systems (e.g. water, energy)
+- Policy and regulatory decision-making
+- Research and interdisciplinary projects
+- Complex programme design
+
+## Relationship to Existing Work
+
+This project builds on Visioning Lab’s previous work, including:
+
+- Ontology Maker (structured terminology and relationships)
+- Water Decisions (decision support for infrastructure systems)
+
+It brings these together into a single, integrated framework.

app/api/extract-points/route.ts

@@ -0,0 +1,24 @@
+import { NextResponse } from "next/server";
+import { completeJSON, LLMError } from "@/lib/anthropic";
+import { EXTRACT_POINTS_SYSTEM } from "@/lib/prompts";
+
+export const runtime = "nodejs";
+
+export async function POST(req: Request) {
+  try {
+    const { input } = (await req.json()) as { input?: string };
+    if (!input || !input.trim()) {
+      return NextResponse.json({ error: "Input is required" }, { status: 400 });
+    }
+    const data = await completeJSON<{ points: unknown[] }>({
+      system: EXTRACT_POINTS_SYSTEM,
+      user: input,
+      maxTokens: 2048,
+    });
+    return NextResponse.json(data);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    const status = e instanceof LLMError ? 502 : 500;
+    return NextResponse.json({ error: msg }, { status });
+  }
+}

app/api/generate-actions/route.ts

@@ -0,0 +1,21 @@
+import { NextResponse } from "next/server";
+import { completeJSON, LLMError } from "@/lib/anthropic";
+import { GENERATE_ACTIONS_SYSTEM } from "@/lib/prompts";
+
+export const runtime = "nodejs";
+
+export async function POST(req: Request) {
+  try {
+    const body = await req.json();
+    const data = await completeJSON<{ actions: unknown[] }>({
+      system: GENERATE_ACTIONS_SYSTEM,
+      user: JSON.stringify(body, null, 2),
+      maxTokens: 2048,
+    });
+    return NextResponse.json(data);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    const status = e instanceof LLMError ? 502 : 500;
+    return NextResponse.json({ error: msg }, { status });
+  }
+}

app/api/generate-insights/route.ts

@@ -0,0 +1,21 @@
+import { NextResponse } from "next/server";
+import { completeJSON, LLMError } from "@/lib/anthropic";
+import { GENERATE_INSIGHTS_SYSTEM } from "@/lib/prompts";
+
+export const runtime = "nodejs";
+
+export async function POST(req: Request) {
+  try {
+    const body = await req.json();
+    const data = await completeJSON<{ insights: unknown[] }>({
+      system: GENERATE_INSIGHTS_SYSTEM,
+      user: JSON.stringify(body, null, 2),
+      maxTokens: 2048,
+    });
+    return NextResponse.json(data);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    const status = e instanceof LLMError ? 502 : 500;
+    return NextResponse.json({ error: msg }, { status });
+  }
+}

app/api/generate-structure/route.ts

@@ -0,0 +1,24 @@
+import { NextResponse } from "next/server";
+import { completeJSON, LLMError } from "@/lib/anthropic";
+import { GENERATE_STRUCTURE_SYSTEM } from "@/lib/prompts";
+
+export const runtime = "nodejs";
+
+export async function POST(req: Request) {
+  try {
+    const { points } = (await req.json()) as { points: unknown[] };
+    if (!Array.isArray(points) || points.length === 0) {
+      return NextResponse.json({ error: "Points are required" }, { status: 400 });
+    }
+    const data = await completeJSON<{ options: unknown[]; criteria: unknown[] }>({
+      system: GENERATE_STRUCTURE_SYSTEM,
+      user: JSON.stringify({ points }, null, 2),
+      maxTokens: 2048,
+    });
+    return NextResponse.json(data);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    const status = e instanceof LLMError ? 502 : 500;
+    return NextResponse.json({ error: msg }, { status });
+  }
+}

app/globals.css

@@ -0,0 +1,28 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+html, body { background: #fafaf7; color: #1a1a1a; }
+
+@layer components {
+  .btn {
+    @apply inline-flex items-center justify-center rounded-md border border-line bg-white px-4 py-2 text-sm font-medium text-ink shadow-sm transition hover:border-ink/40 hover:shadow disabled:cursor-not-allowed disabled:opacity-50;
+  }
+  .btn-primary {
+    @apply inline-flex items-center justify-center rounded-md bg-accent px-4 py-2 text-sm font-medium text-white shadow-sm transition hover:bg-accent/90 disabled:cursor-not-allowed disabled:opacity-50;
+  }
+  .card {
+    @apply rounded-lg border border-line bg-white p-4 shadow-sm;
+  }
+  .label {
+    @apply mb-1 block text-xs font-medium uppercase tracking-wide text-ink/60;
+  }
+  .input, .textarea {
+    @apply w-full rounded-md border border-line bg-white px-3 py-2 text-sm text-ink placeholder:text-ink/40 focus:border-accent focus:outline-none focus:ring-1 focus:ring-accent;
+  }
+}
+
+@media print {
+  .no-print { display: none !important; }
+  body { background: white; }
+}

app/layout.tsx

@@ -0,0 +1,17 @@
+import "./globals.css";
+import type { Metadata } from "next";
+import type { ReactNode } from "react";
+
+export const metadata: Metadata = {
+  title: "Visioning Lab — Systems Development Tool",
+  description:
+    "Work through complex problems using the Visioning Lab Systems Development framework: Define → Structure → Insight → Action.",
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body className="min-h-screen bg-paper text-ink antialiased">{children}</body>
+    </html>
+  );
+}