Understand technology. See how it connects.
TechFlow is an interactive developer knowledge graph. Technologies, concepts, patterns, architectures, comparisons, roadmaps and system designs are nodes in one graph; every page links to the nodes around it, and the diagrams are live (force graphs, animated request flows, interactive decision trees) rather than pictures.
- Next.js 16 (App Router,
output: "export"— plain static HTML inout/), React 19, TypeScript - Tailwind CSS v4 with CSS-variable design tokens (dark default, follows OS, manual toggle)
- Content as Markdown + JSON in
content/— no database, no backend d3-forcefor graph layout; everything else is hand-written SVG- Geist Sans / Geist Mono
pnpm install
pnpm dev # http://localhost:3000
pnpm validate # content, graph links, and the example questions (also runs before build)
pnpm build # static production build
pnpm test # unit tests (vitest) — needs `pnpm gen` once for the generated JSON
pnpm lint && pnpm typecheck
pnpm check:links # after a build: every internal link and sitemap coverage
pnpm check:build # after a build: accessibility, anchors, metadata, page budgets
pnpm e2e # after a build: seven sweeps against the exported site
pnpm gaps # terms the prose leans on with no page, and pages that link
# each other without the graph knowingcontent/ all content — see content/README.md for the authoring guide
technologies/ concepts/ patterns/ Markdown nodes (frontmatter + H2 sections)
architectures/ system-designs/ JSON diagrams (nodes, edges, flows, decisions, versions)
comparisons/ roadmaps/ builds/ comparisons (md), roadmaps + "I want to build" goals (json)
NODES.md master list of node ids
scripts/validate-content.ts content validator (broken links fail the build)
scripts/gen-api.ts writes public/api/*.json and llms.txt
scripts/check-links.ts asserts every link in out/ resolves
src/lib/content/ loader → knowledge graph (edges, neighbours, ego graphs, search index)
src/lib/fences.ts parsers for the visual code fences (steps / sequence / compare / decision / timeline)
src/lib/intent.ts recognises a typed question (goal / why / compare / how / learn) — keyword matching, no model
src/components/md/ Markdown renderer + fence components
src/components/graph/ RelationshipGraph (force layout), MindMap (two-sided radial), lazy loader
src/components/canvas/ ArchitectureCanvas (zoom/pan, ▶ Run, inspector, versions), StepJourney
src/components/detail/ shared detail-page building blocks (levels, learning path, neighbours, TOC)
src/components/radar/ Technology Radar chart
src/components/playground/ browser-only simulators (HTTP, cache, rate limiter, load balancer, transports, JWT)
src/app/ routes: /technology /concept /pattern /architecture /compare /roadmap
/system-design /build /stack /radar /playground /challenge /search /explore
- Pick an id from
content/NODES.md(or add one there). - Copy the closest existing file (
content/technologies/redis.mdis the reference) and followcontent/README.md. - Run
pnpm validate— it fails on unknown ids, missing required sections and unknown fences.
Edges are declared in frontmatter (related) and derived automatically from usedFor,
prerequisites, learningPath, architecture node refs, comparison subjects and roadmap steps.
| Area | Route | What it does |
|---|---|---|
| Knowledge graph | /explore, every detail page |
Force-directed graph of all nodes; hover a neighbourhood, click to open |
| Your progress | /you |
What this browser remembers, crossed against the prerequisite graph: which pages are readable now, which are one page away, and which single page would open the most of them |
| Find a path | /path, ?from=&to= |
Three questions a list of pages cannot answer: how are these two connected (weighted so the route avoids hub pages), what do they share (ranked so a roadmap they both appear on does not win), and what do I need to read first (prerequisites, topologically ordered, against what you have ticked as known). Any of the three copies out as a Markdown list with absolute links |
| Mind map | /map, ?focus=<id> |
One centre, a branch per relationship kind, leaves stacked in columns. Clicking a leaf re-centres without a page load and keeps a trail; copies out as Mermaid |
| Technologies / Concepts / Patterns | /technology, /concept, /pattern |
Three depth levels, trade-offs, prerequisites, learning path, animated diagrams |
| Architecture Explorer | /architecture |
Interactive diagrams: ▶ Run animates a request, inspector per component, version evolution |
| System Design | /system-design |
Step-by-step scale journeys with the reasoning and alternatives at each step |
| Comparisons | /compare |
Feature matrices plus an interactive decision tree, and a "which would you pick" vote |
| Roadmaps | /roadmap |
Ordered learning paths with local progress tracking |
| Real-world stacks | /stack |
Which technologies get combined in practice, layer by layer, with the costs |
| Technology Radar | /radar |
Adopt / Trial / Assess / Caution with dated, sourced reasoning |
| Playground | /playground |
HTTP anatomy, cache, rate limiter, load balancer, real-time transports, JWT — all client-side |
| Design challenges | /challenge |
Multiple-choice design questions that explain every option |
| JSON API | /api-docs, /api/*.json |
The whole graph as static JSON — no key, no rate limit, regenerated every build |
| Search | /search, ⌘K |
Two tiers plus a reading. Names, ids, tags and taglines are matched instantly (abbreviations and one transposed key included). Below them, an inverted index over the prose finds pages by what they say — nothing is called "coordinated omission" and two pages explain it. A typed sentence also gets an answer card: the goal, the comparison or the pages for what it names |
Every technology, concept, pattern, architecture and system design page also carries a Try it section linking to the playgrounds, design challenges, stacks and build goals that reference it — the interactive half of the site reached from the page rather than from an index.
/ or ⌘K search · ⌘⇧D developer mode · on a diagram: space run, → step, f fit.
G then a letter jumps: H home, E explore, T technologies, C concepts, P patterns,
A architecture, S system design, V compare (as in "vs"), R roadmaps, M mind map,
K stacks, D radar, Y playground. The command palette lists them all with their keys.
Every gate runs on pull requests (.github/workflows/ci.yml) and again before deploy:
| Command | What it protects |
|---|---|
pnpm validate |
required sections, graph links and their types, prerequisite cycles, comparison structure and subject coverage, review dates, every visual fence's grammar and the node ids inside it, learning-path steps that look like ids and match nothing, a link whose text names one page and points at another, a challenge option or scale-journey step with no reason given — then the example questions, keyword ranking, one assertion per page name and question form, and that every page is still reachable from every other |
pnpm test |
the pure logic: path finding, learning routes, the frontier, search ranking and typo tolerance, question parsing, the fence grammars, localStorage including private mode, the published API against its own documentation, that untrusted input cannot become markup — and the claims each playground makes, so a simulator that misrepresents a fixed window fails rather than teaches |
pnpm lint / pnpm typecheck |
React compiler rules and types |
pnpm check:links |
every internal link across the build — 23,650 of them — and sitemap coverage |
pnpm check:build |
every page: one h1, no skipped heading levels, no duplicate ids, a name on every link, button and input, and no link to a section that is not there — plus canonical, og:image, description and structured data on every page, each pointing at itself and at a file that exists, a 45KB gzipped page budget and a 420KB JS budget, and that 404.html is ours |
pnpm e2e |
Playwright against the exported site, served the way GitHub Pages resolves it — under /<repo>, as the deploy does. Seven sweeps: pages that must render with an empty console (a hydration mismatch logs and looks fine otherwise); journeys, from the spec's first walk to the 404; every page at phone width, because nothing may scroll the document sideways; every page through axe-core, themes alternating, because contrast belongs to the palette and roles do not change with it; focus order, so the skip link moves focus, the palette hands it back, and a combobox announces what it highlights; layout shift and blocked main thread at 4x CPU throttling; and markup pushed through every input a stranger can reach |
The site is 100% static. pnpm build writes out/, which any static host can serve.
.github/workflows/deploy.yml builds on every push to main and publishes to GitHub Pages.
One repository setting is required first: Settings → Pages → Build and deployment →
Source: GitHub Actions. The workflow token is not allowed to create the Pages site itself,
so until that is set the build job passes and the deploy job fails. For a sub-path host it sets
NEXT_PUBLIC_BASE_PATH=/<repo>; on a custom domain remove that variable and set
NEXT_PUBLIC_SITE_URL to the domain so canonical / sitemap URLs are right.
The graph is published as static JSON next to the pages, so tools can read it without
scraping: /api/graph.json (all nodes and edges plus the relation vocabulary),
/api/nodes/{id}.json (one node with its neighbourhood), /search-index.json,
/search-text.json (an inverted index over the prose), and /llms.txt. /api-docs documents them with curl examples. All of it is regenerated by
pnpm gen on every build, so it can never drift from the site.
The mind map also copies itself out as a Mermaid graph, which pastes straight into a README or a design doc.
/search accepts sentences, not just keywords. "I want to build a chat app but I don't
understand why I need Redis and Kafka" resolves to the real-time chat goal plus the Redis and
Kafka pages. It is keyword matching against the graph in the browser — no model, no network —
and it says so on the card, falling back to ranked results when it cannot read the question.
The path finder in src/lib/path.ts answers the other two shapes of question — a weighted
Dijkstra between any two pages, and a topological sort of a target's prerequisites. Both run
against /api/graph.json in the browser, and both are asserted by pnpm check:intent.
The recognisers live in src/lib/intent.ts; goal keywords are the GOAL_WORDS table and
abbreviations are shared with search in src/lib/aliases.ts. The four questions the product
was specified around — "Why Redis?", "When is Kafka needed?", "WebSocket vs SSE?", "How do I
design a payment system?" — are asserted by pnpm check:intent, along with the keyword
rankings, because three of the four broke once without anyone noticing.
There are no accounts and no backend. Learning-path checkboxes, recently viewed, streak and
theme live in the visitor's localStorage only. /you is the one place that reads all of it
at once — and it can also forget all of it, which is the only honest thing to offer when
there is nothing to log out of.
MIT — see LICENSE. Content is TechFlow's editorial assessment; each page carries a review date and a confidence level, and both should travel with anything you republish.