Arkaik
A product graph browser built with React Flow on Next.js. Map your product's anatomy — from user flows down to API endpoints — in one navigable, local-first graph.
What is arkaik?
Existing tools silo product knowledge across Jira, Figma, Notion, dbdiagram, and Swagger. arkaik lets you traverse across all these layers fluidly — from a user flow down to the API payload it touches, or from a data model up to which screens render its data, across platforms.
It's not a task tracker, not a wiki, not a design tool. It's a navigable, multi-dimensional map of a product's full anatomy.
Features
- 6-species graph — flows, views, data models, API endpoints, acceptances, and decisions as first-class node types (the taxonomy is the source of truth)
- Playlist composition — flows contain ordered sequences of views and sub-flows, with condition and junction branching
- Per-platform tracking — Web, iOS, Android variants with independent statuses and notes per view
- 7 lifecycle statuses — idea, discovery, backlog, development, releasing, live, archived — plus a
blocked_by flag for nodes stalled by a dependency
- Journal & changelog — an append-only event log records how the graph changed; releases, timelines, and a backlog are derived from it
- Local-first — all data in your browser (IndexedDB), works offline, no account required; optional Synk backups with a free account
- Publish & share — Publik snapshots (
arkaik.app/p/{id}) and full JSON import/export for backup, sharing, and self-hosting
- Agent-native — an
arkaik CLI, an arkaik-mcp MCP server, a Claude Code plugin/skill for coding agents that maintain the map as a side effect of development, and machine-readable schema surfaces (/llms.txt)
- Seed example — ships with a "Pebbles" example project to explore immediately
- ⌘K palette — jump to any map, library, board or setting by typing it, with Tab completion; the same palette searches the docs
- Dark mode — light/dark theme toggle
Quick Start
git clone https://github.com/alexisbohns/arkaik.git
cd arkaik
npm install
npm run dev
Open http://localhost:4242 — create a project or load the seed example from the projects page.
Folder Structure
app/
layout.tsx # Root layout: fonts, theme, global CSS
page.tsx # Home / landing page (signed in → /projects)
projects/page.tsx # Project list, create, import, seed, restore
project/[id]/ # The project shell — page.tsx redirects to overview/
overview/ # Dashboard: coverage, gauges, release pulse, backlog
maps/ + maps/[mapId]/ # Maps index and renderer (journey, system, custom)
canvas/ # Redirect to maps/journey — old links keep working
library/ # Filterable node browser (gallery + directory)
delivery/ # Board of (node × platform) items by status
acceptances/ # Acceptance matrix
decisions/ # Decision log
pyramid/ # Value-elements aggregation
changelog/ + history/ # Releases + backlog, and the raw event log
settings/ # Project settings, products, linked repos
settings/tokens/ # Account-level `ark_` API token management
p/[id]/ # Publik snapshot preview
generate/ # Prompt builder for LLM-assisted bundle generation
api/ # graph (hosted projects), tokens, publik, synk, auth,
# github/webhook (acceptance promotion from PRs)
components/
graph/
Canvas.tsx # React Flow wrapper + node/edge type registry
JourneyCanvas.tsx # Journey graph → ELK → Canvas, props only (JourneyMap is the controller)
SystemCanvas.tsx # System graph → ELK → Canvas, props only (SystemMap is the controller)
nodes/ # FlowNode, ViewNode, DataModelNode, ApiEndpointNode
edges/ # ComposeEdge, CrossLayerEdge, FloatingDottedEdge
maps/ # JourneyMap, SystemMap, map cards + editor dialog
overview/ delivery/ acceptances/ decisions/ pyramid/ journal/ values/
layout/ # ProjectSidebar, ProjectSwitcher, CommandPalette, StatusBadge, etc.
panels/ # PanelStack, NodeDetailPanel, NewNodeForm, PlaylistEditor, etc.
publik/ sync/ settings/ # Share dialog, Synk status, product/repo/token managers
ui/ # shadcn/ui primitives (button, card, dialog, etc.)
lib/
config/ # Label/order arrays for the ids in @arkaik/schema (see docs/conventions.md)
data/ # DataProvider interface + local (Dexie), remote, seed and routing providers,
# and the query cache the hooks observe (project-queries.ts)
hooks/ # useNodes, useEdges, useProject, useJournal, etc.
services/ # Server-side: hosted graph store, publik, synk, github app
utils/ # export, layout, cycle detection, platform-status rollups
packages/
schema/ # @arkaik/schema — canonical zod model, validation, projections (MIT)
cli/ # arkaik — init, validate, log, release, deliverable, sync, pack,
# open, push, link, restore, bootstrap (MIT)
mcp/ # arkaik-mcp — stdio MCP server over a bundle (MIT)
plugin/ # Claude Code plugin: the agent skill + generated assets (MIT)
seed/
pebbles.json # Example project data
arkaik-self-map.json # Arkaik's own map — the built-in public seed project
docs/ # Architecture, graph model, data layer, conventions, vision, specs
Tech Stack
| Layer | Choice |
|---|
| Framework | Next.js 16 (App Router) |
| UI | React 19 |
| Graph canvas | React Flow (@xyflow/react 12) |
| Styling | Tailwind CSS 4 + shadcn/ui + CVA |
| Storage | IndexedDB via Dexie (local-first, the default); optional Postgres-backed services (Publik, Synk, hosted projects) |
| Schema | @arkaik/schema — canonical zod model, generated JSON Schema + validator |
Documentation
See docs/ for detailed documentation:
- Architecture — system design, component map, data flow
- Graph Model — the taxonomy's source of truth: species, composition, statuses, and edge types (including the decision-only
supersedes, generates, impacts)
- Data Layer — DataProvider interface, local storage, import/export
- Hosted Projects — put a project in your account, point a coding agent at it, and let pull requests move acceptances
- Bootstrap — onboarding an existing repo onto Arkaik in one run
- Conventions — coding patterns, file organization, state management
- Vision — product strategy: the four layers (format, toolchain, app, services), the core product ("one graph, many maps"), modes & tiers, roadmap
- Specs — normative specifications: bundle format v2, event journal, toolchain, services, maps, MCP server
- Contributing — license split, how to submit changes
Running Example: Pebbles
Product: Pebbles
Scenario: Record a Pebble
- Flow: Create the record → Views: Set the time, Set the intensity
- Flow: Shape an emotion → Views: Open emotion wheel, Select primary, Refine secondary
- Flow: Relate souls → Views: Search contacts, Select soul, Confirm
- Flow: Add a card → Views: Choose card type, Write content, Attach
Data Models: events (pebble), pearl, event_pearl, pearl_emotions, souls, event_souls, profiles, cards, event_cards
API Endpoints:
GET /pebbles/:id → Consolidated pebble (full relations)GET /pebbles → List of compact pebbles (lighter)POST /pebbles → Create a new pebblePUT /pebbles/:id/emotions → Attach emotions to a pebble
Credits
arkaik is built on top of these great projects:
