Note: BJJGraph is under active development. Content is being expanded daily. Contributions welcome!
Brazilian Jiu-Jitsu knowledge graph and state machine as a static site. The project's ontology models BJJ as a state machine: positions are states, transitions are states too, and edges are the probabilistic outcomes between them.
Production: bjjgraph.org | Dev Preview: dev.bjjgraph.pages.dev
- 137+ Positions - BJJ positions as state-machine nodes (top/bottom role pages)
- 1000+ Transitions - Techniques as probabilistic edges between states
- 350+ Submissions - Terminal states and finishing techniques (with attacker/defender role pages)
- 47 Expert Systems - Systematic approaches (Danaher, Gordon Ryan, Eddie Bravo, etc.)
- 59 Principles - Fundamental BJJ principles (base, posture, framing, …)
- 22 Learning Articles - Strategy, training methods, and competition tactics
- Graph Data - Download graph.json — the full knowledge graph as structured data (also available as
.gz)
- Background graph - The entire knowledge graph sits behind every page as a swipeable drawer. Scroll up (or tap the top stripe) to expand it; click a node to crossfade to that page.
- Training mode - Spaced-repetition flashcards (SM-2 algorithm) drawn from per-technique Q&A. Daily-goal driven, with deck filters: due / reviewing / mastered / suggested / recently explored.
- Roll mode - Simulate a journey through positions: pick a starting position, then roll dice against transition probabilities. Tracks your journey for a post-roll victory display + lifetime stats.
- Optional Supabase sync - Sign in with Google to sync flashcard progress and roll history across devices. Anonymous use is fully supported (everything lives in
localStorage).
npm install # Installs root + source/ deps via postinstall (Node 20+)
npm run dev # Build + serve at http://localhost:8080 (~10 min cold build)For iterative work, edit JSON sources in content/, run a targeted regenerate step (npm run regenerate:md for markdown only, or npm run regenerate for the full pipeline), then npm run build. The serve step alone is npm run serve.
| Command | Description |
|---|---|
npm run validate:json |
Validate JSON sources against templates/ schemas |
npm run validate:graph |
Validate graph integrity (referential consistency, probability sums) |
npm run regenerate:issues |
List content files that need fixes |
npm run regenerate:json |
Fill TODOs / fix validation errors in JSON via Claude API |
npm run regenerate:explode |
Expand graph connections (derive opponent transitions, etc.) |
npm run regenerate:md |
Regenerate markdown from JSON via Jinja2 templates |
npm run regenerate:hubs |
Generate category hub pages (Positions.md, Transitions.md, …) |
npm run regenerate:votes |
Generate community voting data |
npm run regenerate:graph |
Generate graph.json (the runtime data feed) |
npm run regenerate |
All 7 regenerate steps in order |
npm run build |
Build the static site (~10 min, ~5700 files) |
npm run regenerate:build |
Regenerate + build (full workflow) |
npm run serve |
Serve source/public on port 8080 (no rebuild) |
npm run dev |
build then serve |
npm run proofread |
Recurring LLM audit of graph edges + probabilities (intermittent use; not part of regenerate) |
npm run regenerate:build # Full validation, generation, and build
cd source && npm run check # Type checkingBJJGraph uses a JSON-first content system:
- Edit JSON source files in
content/(e.g.,content/Positions/Mount.json) - Validate & Regenerate with
npm run regenerate - Test build with
npm run dev
Never edit .md files in content/ directly — they are generated from the .json source files.
| Doc | Purpose |
|---|---|
| CLAUDE.md | AI development workflow |
| docs/Architecture.md | JSON pipeline, Position model |
| docs/Content.md | Content standards, validation rules |
| docs/SEO.md | Schema markup, keywords, analytics |
Built on Quartz 4.0 with:
- Graph rendering: PixiJS (WebGL) for the full-viewport background graph + D3-force for layout. node2vec + UMAP precompute global node positions at build time for instant first paint.
- Search: Flexsearch full-text index, lazily fetched (gzipped) on first open.
- Training (SRS): Client-side SM-2 spaced repetition. State lives in
localStorage(bjj-srs-cards,bjj-settings,bjj-daily-progress, …); optional Supabase sync for signed-in users. - Auth: Optional Supabase Auth (email/password + Google OAuth). Anonymous use is fully supported.
- SPA navigation: Micromorph-style page swaps + the CSS View Transitions API for crossfades and training-session carousel slides.
- Analytics: PostHog (skipped-flashcard events, navigation patterns, feature flags).
- SEO: Schema markup on every page (HowTo, FAQ, etc.) — generated by Jinja2 templates.
- Mobile: Touch gestures (swipe-up reveals graph, pinch-zoom + drag pan the graph).
bjjgraph/
├── content/ # *.json = SOURCE data, *.md = GENERATED output
│ ├── Positions/ # 137+ positions (hub + Top/Bottom role pages)
│ ├── Transitions/ # 1000+ transitions (hub + Attacker/Defender role pages)
│ ├── Submissions/ # 350+ submissions (hub + Attacker/Defender role pages)
│ ├── Systems/ # Expert systems
│ ├── Principles/ # Fundamental principles
│ └── Learning/ # Strategy & training articles
├── templates/ # JSON schemas + Jinja2 templates (NOT source data)
├── graph.json # Generated graph data feed (committed for releases)
├── source/ # Quartz static site generator
│ └── quartz/ # Components, plugins, styles
├── scripts/ # Validation, regeneration, content-bot tooling
├── docs/ # Project documentation
├── branding/ # Logo + favicon assets
├── tests/ # Test artifacts and validation reports
└── .github/workflows/ # CI: deploy (main/dev), content-improvement-bot,
# analytics-content-improvement, keepalives
BJJGraph is building the most comprehensive, systematic breakdown of grappling ever assembled. Our mission is to democratize high-level BJJ knowledge so anyone with the interest can truly study the game.
We're looking for partners who share this vision—BJJ apps, gear companies, academies, and training platforms who want to help advance the sport and make world-class instruction accessible to all.
Contact: Diogo Seca on LinkedIn
Hosted on Cloudflare Pages. Deploys are triggered by GitHub Actions.
| Branch | URL | Workflow |
|---|---|---|
main |
bjjgraph.org | .github/workflows/deploy.yaml |
dev |
dev.bjjgraph.pages.dev | .github/workflows/deploy-dev.yaml |
Preview deployments for dev are also available at unique URLs (e.g., <hash>.bjjgraph.pages.dev) visible in the Cloudflare Pages dashboard.
- PostHog: https://us.posthog.com/project/236155
- SEO: Schema markup on all content pages
When maintaining content, pay attention to two feedback channels:
- Most-skipped flashcards — every time a user hits Skip on a flashcard, the runtime fires a
flashcard_skippedPostHog event with{ page, technique, question }. Aggregate these in PostHog (group byquestion) to find the questions users find broken, unclear, or off-topic — those are the first ones to rewrite. - Issues raised by open-source collaborators — GitHub issues and PRs from the community are the highest-signal source of content problems. Triage them before adding new content.
PolyForm Noncommercial 1.0.0 - Free for personal, educational, and non-commercial use. Commercial use requires permission. See LICENSE
- Site: https://bjjgraph.org
- Repository: https://github.com/diogoseca/bjjgraph
- Quartz Docs: https://quartz.jzhao.xyz/