Graphden documentation

FAQ — Common objections & answers

This document collects the sharp questions a skeptical engineer, reviewer, or investor asks on first contact with Graphden, and the honest answer to each. It is a living document: when a new objection lands, add it here rather than re-arguing it from scratch.

Positioning context lives in README.md (“Why this exists”) and docs/PHILOSOPHY.md; this file is the rebuttal layer on top of them.


1. “One person + AI produced ~100k LOC — is that impressive, or is it AI slop you don’t understand?”

Short answer: Neither. Graphden’s own construction is the first instance of its own thesis, told honestly across the three tiers it defines (PHILOSOPHY § three-tier ecosystem). The volume proves nothing; the coherence proves the human supplied the parts AI does not — judgment, architecture, review — and the app layer already bootstraps onto the substrate.

Detail — the engine is the text-authoring tax, paid once:

Detail — the application layer is the bootstrap dividend:

Framing note (do not deliver as “AI wrote it, be impressed”): the claim is that the engine paid the text tax once under review to earn the substrate, and the app layer riding that substrate is the first small evidence it pays off one tier up. Coherence is the proof, not line count.

Strength: Strong once split by tier (engine = tax paid once; app layer = dividend). Self-defeating if flattened to “AI did it,” which invites both “then it’s not impressive” and “then you don’t understand it.”


2. “You reinvented versioning / types / orchestration instead of using off-the-shelf tools (NIH).”

Short answer: Each build-vs-buy call was researched, and the reasoning is specific, not reflexive. The strongest case is versioning.

Detail — versioning/branching/merge on Postgres:

Detail — type system:

Detail — fleet orchestration:

Strength: Strong for versioning (put the three-line Datomic/XTDB/Dolt dismissal prominently in the ADR). Medium for types (own the novelty, don’t call it “not that custom”). The k8s/Knative framing in the original critique was imprecise — concede that and narrow it to the placement controller.


3. “So much bespoke dev tooling (merge-queue, dev-tour, drift-guards) — process over product.”

Short answer: The tooling was cheap to build (also AI-produced, in parallel), and each piece exists to make AI-directed development on this codebase faster and safer. Low cost defuses the “wasted effort” version of this objection entirely.

Detail:

Strength: Strong on the cost axis. It does not address market validation — keep the two separate and don’t let a good answer here paper over objection 5.


4. “Bus factor is 1, and the paradigm is idiosyncratic — onboarding a second person is expensive.”

Short answer: True that authorship is concentrated; the mitigants are deliberate and partly already in place.

Detail:

Strength: Half-answer as originally phrased (monorepo ≠ bus-factor fix). Strong once re-centered on docs + tests + AI-onboarding + the already-split satellites.


5. “Visual/graph programming is a graveyard — why does this one work?”

Short answer: Graphden is not “Scratch for everything.” It sits on three specific bets that the failed attempts did not have.

Detail — the three differentiators:

  1. We visualize Lisp, which is already ~AST — not control-flow symbols. Scratch-style tools fail trying to render if/for/while as blocks: a forced metaphor over a fundamentally textual, imperative structure. Graphden visualizes a homoiconic, composition-first substrate where the graph is the natural shape of the program, not a costume on top of it. This is the sharpest, least-obvious point — lead with it.
  2. The diff is a graph, and it is editable. Read-only “see your code as a graph” tools exist (e.g. code-as-graph visualizers). Graphden’s unit of value is the editable graph plus a structural diff/merge of changes — review and authorship in the same surface, not a viewer bolted beside a text editor.
  3. The AI-era review bet. As models write more code, humans read less of it, and reviewing prose diffs is tedious and error-prone. The wager is that reviewing a typed, effect-annotated, structurally-valid graph of a change is easier than reviewing text. This is stated as a bet, not a proven fact — it is the central hypothesis the product now needs to test in the market.

Category context: Tools like n8n validate that node-graph composition has real demand — but they operate at coarse integration granularity. Graphden composes fine-grained, typed and effect-tracked functions. The category is alive; the wedge is the substrate + the review ergonomics above.

Strength: Strongest raw material of all seven, but currently a jumble. Structure it as: category is validated → our wedge (Lisp≈AST, editable diff, typed/effect) → the explicit unproven bet. The Lisp-is-already-AST line is the best single sentence in the whole pitch.


6. “Some files are huge (types/check.clj ~2.3k lines) — poor decomposition.”

Short answer: Splitting was attempted and rejected on structural grounds, and the reason is now documented in the file’s own docstring so it is not re-litigated.

Detail:

This was independently re-verified during review; the analysis is captured in the graphden.types.check namespace docstring.

Strength: Strong, and now backed by a verified, in-repo record. This is a falsifiable answer that survived being tested — the best kind.


7. “No load testing — performance is unproven.”

Short answer: Correct: full load/soak testing has not been run yet, and that is a deliberate sequencing choice, not an omission.

Detail:

Strength: Fine as deliberate sequencing. The only failure mode is conflating the microbenchmarks you have with the load testing you don’t — keep them clearly separate.


8. “Why not just use n8n / Zapier / Make / Retool?”

Short answer: Those tools validate the demand for node-graph composition — and stop at coarse integration granularity. Graphden is a programming substrate, not an integration canvas: fine-grained typed functions, a real type system, and version control of the graph itself.

Detail — the concrete differences:

Strength: Strong when granularity + types + versioning are stated together, with the young-ecosystem concession made first — conceding it preempts the rebuttal and frames the category as validated rather than competitive.


9. “What if I outgrow it — am I locked in?”

Short answer: The exits are unusually good for this category, by construction rather than by promise.

Detail — the three exit doors:

The honest residual: the paradigm is the lock-in — fn-defs don’t mechanically transpile to a classical codebase (nothing graph-shaped does; the same is true of n8n workflows, Airtable bases, or spreadsheet logic). The mitigations are structural: base-fns are thin wrappers over ordinary Clojure/libraries, so the impl layer ports; and the graph’s explicit structure — types, effects, named compositions — is exactly the artifact you’d hand an AI to rewrite into text code, far better input than a legacy codebase. State it plainly rather than claiming zero lock-in: the data and the runtime are exit-safe, the program shape is a commitment.

Strength: Strong on data/runtime exits (verifiable, structural). The paradigm-commitment concession must stay in — dropping it turns a credible answer into marketing.


10. “We can’t use AGPL — what are our options?”

Short answer: Most objections to the AGPL do not apply to using Graphden; for the cases that remain there is a commercial licence.

Detail — three cases:

What stays true in every case: the AGPL grant is never withdrawn, the public repository is the only codebase, and the hosted cloud runs that same core with a proprietary multi-tenant addon that is not for sale.

Strength: Strong; it is the standard open-core answer (Metabase, MongoDB before SSPL). Keep the “same code, second grant” framing — a “different enterprise edition” would be a different, weaker answer.