MVC is a pattern for backends. FootPrint is a different pattern — the flowchart pattern — where your business logic is a graph of functions with transactional state. The code becomes self-explainable: AI reads the structure, traces every decision, and explains what happened — no hallucination.

npm install footprintjs

The Problem

Your LLM needs to explain why your code made a decision. Without structure, it reconstructs reasoning from scattered logs — expensive, slow, and hallucinates.

| | MVC / Traditional | Flowchart Pattern (FootPrint) | |---|---|---| | LLM explains a decision | Reconstruct from scattered logs | Read the causal trace directly | | Tool descriptions for agents | Write and maintain by hand | Auto-generated from the graph | | State management | Global/manual, race-prone | Transactional scope with atomic commits | | Debugging | console.log + guesswork | Time-travel replay to any stage |

How It Works

A loan pipeline rejects Bob. The user asks: "Why was I rejected?"

The runtime auto-generates this trace from what the code actually did:

Stage 1: The process began with ReceiveApplication.
  Step 1: Write app = {applicantName, annualIncome, monthlyDebts, creditScore, ...}
Stage 2: Next, it moved on to PullCreditReport.
  Step 1: Read app = {applicantName, annualIncome, monthlyDebts, creditScore, ...}
  Step 2: Write creditTier = "fair"
Stage 3: Next, it moved on to CalculateDTI.
  Step 1: Read app = {applicantName, annualIncome, monthlyDebts, creditScore, ...}
  Step 2: Write dtiRatio = 0.6
  Step 3: Write dtiStatus = "excessive"
Stage 4: Next, it moved on to AssessRisk.
  Step 1: Read creditTier = "fair"
  Step 2: Read dtiStatus = "excessive"
  Step 3: Write riskTier = "high"
[Condition]: A decision was made, and the path taken was RejectApplication.

The LLM backtracks: riskTier="high" ← dtiStatus="excessive" ← dtiRatio=0.6 ← app.monthlyDebts=2100. Every variable links to its cause:

LLM: "Your application was rejected because your debt-to-income ratio of 60% exceeds the 43% maximum, your credit score of 580 falls in the 'fair' tier, and your self-employment tenure of 1 year is below the 2-year minimum."

That answer came from the trace — not from the LLM's imagination.

Quick Start

import { flowChart, FlowChartExecutor, ScopeFacade } from 'footprintjs';

const chart = flowChart('FetchUser', (scope: ScopeFacade) => {
    scope.setValue('user', { name: 'Alice', tier: 'premium' });
  }, 'fetch-user')
  .addFunction('ApplyDiscount', (scope: ScopeFacade) => {
    const user = scope.getValue('user') as any;
    const discount = user.tier === 'premium' ? 0.2 : 0.05;
    scope.setValue('discount', discount);
  }, 'apply-discount')
  .addDeciderFunction('Route', (scope: ScopeFacade): string => {
    return (scope.getValue('discount') as number) > 0.1 ? 'vip' : 'standard';
  }, 'route')
    .addFunctionBranch('vip', 'VIPCheckout', (scope: ScopeFacade) => {
      scope.setValue('lane', 'VIP express');
    })
    .addFunctionBranch('standard', 'StandardCheckout', (scope: ScopeFacade) => {
      scope.setValue('lane', 'Standard');
    })
    .setDefault('standard')
    .end()
  .setEnableNarrative()
  .build();

const executor = new FlowChartExecutor(chart);
await executor.run();

console.log(executor.getNarrative());
// Stage 1: The process began with FetchUser.
//   Step 1: Write user = {name: "Alice", tier: "premium"}
// Stage 2: Next, it moved on to ApplyDiscount.
//   Step 1: Read user = {name: "Alice", tier: "premium"}
//   Step 2: Write discount = 0.2
// Stage 3: A decision was made, and the path taken was VIPCheckout.
//   Step 1: Write lane = "VIP express"

Try it in the browser — no install needed

Browse 25+ examples — patterns, recorders, and a full loan underwriting demo

Features

| Feature | Description | |---------|-------------| | Causal Traces | Every read/write captured — LLMs backtrack through variables to find causes | | Auto Narrative | Build-time descriptions for tool selection, runtime traces for explanation | | 7 Patterns | Linear, parallel fork, conditional, multi-select, subflow, streaming, loops — guide | | Transactional State | Atomic commits, safe merges, time-travel replay — guide | | PII Redaction | Per-key or declarative RedactionPolicy with audit trail — guide | | Flow Recorders | 8 narrative strategies for loop compression — guide | | Contracts | I/O schemas (Zod/JSON Schema) + OpenAPI 3.1 generation — guide | | Cancellation | AbortSignal, timeout, early termination via breakFn() — guide |

AI Coding Tool Support

FootPrint ships with built-in instructions for every major AI coding assistant. Your AI tool understands the API, patterns, and anti-patterns out of the box.

npx footprintjs-setup

| Tool | What gets installed | |------|-------------------| | Claude Code | .claude/skills/footprint/SKILL.md + CLAUDE.md | | OpenAI Codex | AGENTS.md | | GitHub Copilot | .github/copilot-instructions.md | | Cursor | .cursor/rules/footprint.md | | Windsurf | .windsurfrules | | Cline | .clinerules | | Kiro | .kiro/rules/footprint.md |

Documentation

| Resource | Link | |----------|------| | Guides | Patterns · Scope · Execution · Errors · Flow Recorders · Contracts | | Reference | API Reference · Performance Benchmarks | | Architecture | Internals — six independent libraries, each with its own README | | Try it | Interactive Playground · Live Demo · 25+ Examples |

MIT © Sanjay Krishna Anbalagan