DEV Community: Marko Mijailović

I Built an AI Knowledge Base in a Weekend. FLXBL Did the Heavy Lifting.

Marko Mijailović — Wed, 04 Mar 2026 15:48:14 +0000

TL;DR: I took FLXBL's new FILE fields, VECTOR fields, and vector search for a spin by building an AI-powered personal knowledge base called BrainLinks. Upload a PDF, and AI extracts concepts, links them to your existing knowledge, and lets you search semantically across everything you've ever saved. The interesting part? Combining vector similarity with graph traversal—a query pattern that's native in a graph database but requires duct tape and prayer in a relational one. The project is open source, so you can try it yourself.

GitHub: github.com/flxbl-dev/brainlinks

The Idea: Obsidian Meets Semantic Search

I've been using Obsidian for years. The graph view—where you see your notes connected through backlinks—is one of those features that makes you think differently about your knowledge. You notice clusters. You spot gaps. You discover connections you didn't know existed.

But Obsidian's graph is manual. You create the links. You decide which concepts connect. And the search? It's keyword-based. If you wrote about "consensus algorithms" in one note and "distributed agreement protocols" in another, Obsidian has no idea they're about the same thing.

So I built BrainLinks: a knowledge base where AI handles the linking and the search understands meaning, not just keywords. Upload a document, and the system extracts concepts, generates embeddings, discovers relationships to your existing knowledge, and builds a graph you can explore visually.

Think Obsidian's graph view meets Notion meets semantic search—except the graph builds itself.

Why This Project Exists (The FLXBL Angle)

If you've read my previous posts, you know I built a Kevin Bacon path-finder and a graph-native CMS on FLXBL. Both showed that graph databases excel when relationships matter. But I kept hearing the same question:

"Cool, but can it do AI stuff?"

Fair question. I'd just shipped two new features in FLXBL—FILE fields (store and serve files directly) and VECTOR fields (store embeddings and run similarity search)—and I needed a project that exercised everything: files, vectors, graph traversal, relationship properties, and the TypeScript SDK. A knowledge base was the perfect storm.

The hypothesis was simple: knowledge is inherently graph-shaped, and combining vector search with graph traversal should be strictly more powerful than vector search alone. BrainLinks is the proof (or the counter-proof—I'm an engineer, not a salesman).

The Schema: 4 Entities, 5 Relationships, Zero Junction Tables

Entity	Purpose	Special Fields
Document	Uploaded files (PDFs, markdown, plain text)	`embedding` (VECTOR, 4096 dims)
Concept	AI-extracted ideas and topics	`embedding` (VECTOR, 4096 dims)
Tag	Organizational labels (AI-suggested + manual)	`color`
Collection	User-created groupings	—

Relationship	Direction	Edge Properties
`MENTIONS`	Document → Concept	`relevanceScore` (0–1)
`RELATED_TO`	Concept → Concept	`strength` (0–1)
`TAGGED_WITH`	Document → Tag	—
`CHILD_OF`	Tag → Tag	—
`IN_COLLECTION`	Document → Collection	—

That's it. Four entities. Five relationships. In a relational database, you'd have at least 9 tables (4 entity tables + 5 junction tables), and two of those junction tables would need extra columns for relevanceScore and strength. In FLXBL, those properties just live on the edges.

But the real power isn't the schema simplicity—it's what you can do with it.

The Upload Pipeline: From PDF to Knowledge Graph

When you upload a document to BrainLinks, a lot happens behind the scenes. Here's the full pipeline:

📄 PDF Upload
   ↓
📝 Text Extraction (pdf-parse)
   ↓
🧮 Embedding Generation (Ollama qwen3-embedding:8b)
   ↓
📦 Document Created in FLXBL (with VECTOR field)
   ↓
🧠 Concept Extraction (Ollama qwen3:8b, JSON mode)
   ↓
🔍 For each concept:
   ├── Generate concept embedding
   ├── Vector search existing concepts (threshold ≥ 0.92)
   ├── Reuse match OR create new Concept
   └── Create MENTIONS edge with relevanceScore
   ↓
🔗 Link related concepts (RELATED_TO edges, strength > 0.7)
   ↓
🏷️ AI suggests tags → create Tags + TAGGED_WITH edges

The interesting design decision here is step 6: concept deduplication via vector similarity. If you upload a paper about "machine learning" and you already have a concept called "ML algorithms," the system recognizes these are the same idea (similarity ≥ 0.92) and reuses the existing concept node. This means your knowledge graph converges—upload 50 documents about different aspects of ML, and they all cluster around the same concept nodes.

Here's the concept matching logic:

for (const extracted of concepts) {
  // Generate embedding for concept name
  const conceptEmbedding = await generateEmbedding(extracted.name);

  // Search existing concepts by vector similarity
  const matches = await flxbl.vectorSearch<Concept>('Concept', {
    field: 'embedding',
    vector: conceptEmbedding,
    topK: 3,
    select: ['name', 'description'],
  });

  let conceptId: string;

  if (matches.length > 0 && matches[0].score >= 0.92) {
    // Reuse existing concept — the graph converges
    conceptId = matches[0].id;
  } else {
    // New concept — the graph grows
    const newConcept = await flxbl.concepts.create({
      name: extracted.name,
      description: extracted.description,
      embedding: conceptEmbedding,
    });
    conceptId = newConcept.id;
  }

  // Create MENTIONS edge with relevance score
  await flxbl.relationships('Document', docId)
    .create('MENTIONS', conceptId, {
      relevanceScore: extracted.relevanceScore,
    });
}

Notice how relevanceScore rides on the edge, not in a separate table. When I later ask "which concepts does this document mention, and how relevant are they?" — that's a single traversal, not a JOIN.

After concept linking, the system also auto-discovers relationships between concepts:

async function linkRelatedConcepts(
  flxbl: FlxblClient,
  conceptId: string,
  embedding: number[]
): Promise<void> {
  const similar = await flxbl.vectorSearch<Concept>('Concept', {
    field: 'embedding',
    vector: embedding,
    topK: 10,
  });

  for (const match of similar) {
    if (match.id === conceptId) continue; // skip self
    if (match.score < 0.7) continue;      // too dissimilar

    await flxbl.relationships('Concept', conceptId)
      .create('RELATED_TO', match.id, {
        strength: match.score,
      });
  }
}

This is where the graph starts doing things a vector database alone can't. After uploading 20 documents, you don't just have 20 embeddings in a flat list—you have a connected knowledge graph where concepts link to each other with measured strength, and documents connect through those concepts.

The Search: Where Graph + Vector Gets Interesting

BrainLinks supports three search modes, and the differences tell a story about why architecture matters.

Mode 1: Semantic Search (What Pinecone Does)

Embed the query, find the nearest document vectors. Standard RAG stuff:

async function semanticSearch(
  flxbl: FlxblClient,
  queryEmbedding: number[],
  limit: number
): Promise<SearchResult[]> {
  return flxbl.vectorSearch<Document>('Document', {
    field: 'embedding',
    vector: queryEmbedding,
    topK: limit,
    select: ['title', 'content', 'type', 'uploadedAt'],
  });
}

This works fine for direct matches. Search "machine learning," find documents about machine learning. Nothing surprising.

Mode 2: Concept Search (What Only a Graph Can Do)

Here's where it gets interesting. Instead of searching documents directly, we search concepts and then traverse the graph to find documents:

async function conceptSearch(
  flxbl: FlxblClient,
  queryEmbedding: number[],
  limit: number
): Promise<SearchResult[]> {
  // Find concepts similar to the query
  const concepts = await flxbl.vectorSearch<Concept>('Concept', {
    field: 'embedding',
    vector: queryEmbedding,
    topK: 20,
  });

  // For each concept, traverse inbound MENTIONS to find documents
  const docScores = new Map<string, { doc: Document; score: number; concepts: string[] }>();

  for (const concept of concepts) {
    const rels = await flxbl.relationships('Concept', concept.id)
      .list('MENTIONS', 'in'); // Documents that mention this concept

    for (const rel of rels) {
      const existing = docScores.get(rel.source.id);
      if (existing) {
        // Document matches MULTIPLE concepts — boost its score
        existing.score += concept.score * rel.properties.relevanceScore;
        existing.concepts.push(concept.name);
      } else {
        docScores.set(rel.source.id, {
          doc: rel.source,
          score: concept.score * rel.properties.relevanceScore,
          concepts: [concept.name],
        });
      }
    }
  }

  // Sort by accumulated score
  return [...docScores.values()]
    .sort((a, b) => b.score - a.score)
    .slice(0, limit);
}

Why does this matter? Because concept search finds documents that don't directly match your query vector but are conceptually related.

If you search for "consensus algorithms for distributed databases," semantic search will find documents where those exact concepts appear in the text. Concept search will also find your document about Raft, your notes on Paxos, and that paper about Byzantine fault tolerance—because the AI extracted "distributed consensus" as a concept from all of them, and those concept nodes are connected in the graph.

This is the query that degrades exponentially in SQL: "find me all documents that share concepts with documents about X." In a graph, it's just... traversal.

Mode 3: Combined Search (The Killer Feature)

Run both searches in parallel, merge the results, and boost documents that appear in both:

async function combinedSearch(
  flxbl: FlxblClient,
  queryEmbedding: number[],
  limit: number
): Promise<SearchResult[]> {
  const [semantic, concept] = await Promise.all([
    semanticSearch(flxbl, queryEmbedding, limit),
    conceptSearch(flxbl, queryEmbedding, limit),
  ]);

  return mergeResults(semantic, concept, limit);
}

function mergeResults(semantic, concept, limit) {
  const merged = new Map();

  for (const r of semantic) merged.set(r.id, { ...r, source: 'semantic' });

  for (const r of concept) {
    const existing = merged.get(r.id);
    if (existing) {
      // Appears in BOTH — boost score
      existing.score = (existing.score + r.score) / 2 + 0.05;
      existing.matchedConcepts = r.matchedConcepts;
    } else {
      merged.set(r.id, { ...r, source: 'concept' });
    }
  }

  return [...merged.values()]
    .sort((a, b) => b.score - a.score)
    .slice(0, limit);
}

And then there's the related documents feature. After finding your search results, BrainLinks extracts all concepts mentioned by those documents and finds other documents that share those concepts:

async function computeRelatedDocs(
  flxbl: FlxblClient,
  resultIds: string[],
  resultConcepts: string[]
): Promise<RelatedDocument[]> {
  const relatedDocs = new Map();

  for (const conceptId of resultConcepts) {
    // Find ALL documents mentioning this concept
    const rels = await flxbl.relationships('Concept', conceptId)
      .list('MENTIONS', 'in');

    for (const rel of rels) {
      if (resultIds.includes(rel.source.id)) continue; // skip already in results

      const existing = relatedDocs.get(rel.source.id);
      if (existing) {
        existing.sharedConceptCount++;
      } else {
        relatedDocs.set(rel.source.id, {
          ...rel.source,
          sharedConceptCount: 1,
        });
      }
    }
  }

  return [...relatedDocs.values()]
    .sort((a, b) => b.sharedConceptCount - a.sharedConceptCount)
    .slice(0, 5);
}

"Show me documents related to my search results through shared concepts" is a multi-hop graph traversal. In SQL with pgvector, you'd need a recursive CTE joining a vector similarity subquery with a junction table. It's possible—but it's the kind of query that makes your ORM file for divorce.

The Honest Comparison: FLXBL vs. The Alternatives

I'm not going to pretend FLXBL is better at everything. Let's be real about the tradeoffs.

Supabase + pgvector

Supabase is excellent. pgvector is genuinely impressive for what it is—vector similarity search bolted onto Postgres. For a straightforward RAG pipeline (embed documents, search by similarity, return results), it's perfectly fine and probably the pragmatic choice for most teams.

Where it falls short for this use case:

Capability	Supabase + pgvector	FLXBL
Vector similarity search	✅ Native (pgvector)	✅ Native (VECTOR fields)
Store embeddings	✅ vector column type	✅ VECTOR field type
Relationship properties	⚠️ Junction tables with extra columns	✅ Native edge properties
Multi-hop traversal	⚠️ Recursive CTEs	✅ Native graph traversal
"Documents sharing concepts"	🔴 Complex self-joins	✅ Single traversal
Concept deduplication	⚠️ Manual via SQL + pgvector	✅ Vector search on Concept entity
Combined vector + graph query	🔴 Two queries + app-level merge with JOINs	✅ Vector search + traversal in one flow
Schema migrations	⚠️ Migration files	✅ Schema publish, instant API
Raw SQL access	✅ Full access	🔴 No direct Cypher

The BrainLinks concept-search pattern — "embed query → find similar concepts → traverse MENTIONS edges → find documents → boost by shared concept count" — is 5 lines of FLXBL SDK calls. In Supabase, you'd write something like:

WITH similar_concepts AS (
  SELECT id, name, 1 - (embedding <=> $query_embedding) as similarity
  FROM concepts
  ORDER BY embedding <=> $query_embedding
  LIMIT 20
),
mentioned_docs AS (
  SELECT
    dm.document_id,
    sc.name as concept_name,
    sc.similarity * dm.relevance_score as weighted_score
  FROM similar_concepts sc
  JOIN document_mentions dm ON dm.concept_id = sc.id
),
ranked AS (
  SELECT
    document_id,
    SUM(weighted_score) as total_score,
    ARRAY_AGG(concept_name) as matched_concepts,
    COUNT(*) as concept_count
  FROM mentioned_docs
  GROUP BY document_id
)
SELECT d.*, r.total_score, r.matched_concepts
FROM ranked r
JOIN documents d ON d.id = r.document_id
ORDER BY r.total_score DESC
LIMIT 10;

That's a perfectly valid query. It works. But it's a lot more to reason about than vectorSearch + relationships().list(). And the moment you want to go one more hop ("find documents related to documents that share concepts with my query")—you're adding another CTE layer and your DBA is asking questions.

Pinecone / Weaviate / Qdrant (Standalone Vector DBs)

Dedicated vector databases are fantastic at one thing: similarity search at scale. If you're building a RAG pipeline with millions of document chunks and need sub-millisecond recall, Pinecone is probably where you should be.

But here's the thing: a vector database gives you a flat list of results. There's no concept of "these two documents are related through shared concepts" because there are no concepts—there are just vectors and metadata filters.

BrainLinks' entire value proposition—the concept graph, the multi-hop discovery, the "related documents" feature—doesn't exist in a pure vector database. You'd need to bolt on a separate database (Postgres? Neo4j?) to store the relationships, and now you're managing two data systems instead of one.

FLXBL gives you vectors and graph in the same system, queried through the same SDK, governed by the same schema.

LangChain / LlamaIndex + Postgres

These frameworks are great for prototyping RAG pipelines, and they have "knowledge graph" modules. But in my experience, their graph implementations tend to be thin wrappers around triple stores or in-memory NetworkX graphs. They're not backed by a production graph database, so you hit walls when you need real graph queries, persistence, or scale.

BrainLinks uses FLXBL as the graph and vector store, with the AI models (Ollama/qwen3) handling extraction and embedding. The framework isn't managing the graph—the database is. That's a meaningful architectural difference.

The Knowledge Graph Visualization

The graph visualization uses react-force-graph to render an interactive force-directed layout:

// Node styling by entity type
const NODE_COLORS = {
  document: '#3B82F6',  // Blue
  concept:  '#10B981',  // Emerald
  tag:      '#F59E0B',  // Amber
  collection: '#8B5CF6', // Violet
};

// Edge properties drive visual weight
function getEdgeWeight(edge: GraphEdge): number {
  if (edge.label === 'MENTIONS') return edge.weight; // relevanceScore
  if (edge.label === 'RELATED_TO') return edge.weight; // strength
  return 0.5; // default for TAGGED_WITH, etc.
}

The API endpoint supports both full-graph queries (up to 100 nodes per entity type) and local subgraph exploration centered on a specific entity. Click a concept node, and you see all the documents that mention it and all the concepts it relates to—a local neighborhood in the knowledge graph.

The RELATED_TO edges render as dashed lines (to distinguish structural relationships from semantic ones), and edge thickness scales with the strength property. You can immediately see which concept connections are strong vs. tenuous.

Proving It: 41 E2E Tests Back the Architecture

I don't just claim graph + vector is better — I wrote 41 Playwright E2E tests that prove it. Not unit tests mocking a database. End-to-end tests that upload real documents, run the full AI pipeline, and assert structural properties of the resulting knowledge graph.

The test suite splits into two halves. The 31 functional tests cover what you'd expect: navigation, upload flow, search modes, graph rendering, document management, collections. Standard stuff. The interesting part is the 10 data-science tests that verify the architectural claims this entire blog post is built on.

Here's what they prove:

Claim	Test
Concept deduplication converges the graph	Upload 6 diverse docs → MENTIONS edges exceed unique concept count
Concepts bridge documents naturally	At least one concept connects 2+ distinct documents
Edge properties are native	Every MENTIONS edge carries `relevanceScore` as weight (0–1), no join table
Concept search uses graph traversal	Results include `matchedConcepts` array — proof of multi-hop query
Combined search synthesizes both modes	Combined results contain docs from both semantic and concept result sets
Subgraph queries work	`?around={docId}&depth=2` returns a focused neighborhood, not the whole graph

The 6 test documents are intentionally diverse — neural networks, philosophy of mind, renewable energy, climate science, internet history, and graph databases — with just enough conceptual overlap to stress-test deduplication. When "neural networks" appears in a paper about AI and in a paper about brain science, the system should recognize them as the same concept. The tests verify it does.

The most telling test is the concept bridge assertion. It fetches the full graph, builds a map of which documents mention which concepts, and asserts that at least one concept is shared across multiple documents:

test('concept nodes act as cross-document bridges', async ({ request }) => {
  const graph = await request.get('/api/graph').then(r => r.json());

  // Map: conceptId -> Set of document IDs that mention it
  const conceptToDocuments = new Map<string, Set<string>>();
  for (const edge of graph.edges) {
    if (edge.label === 'MENTIONS') {
      if (!conceptToDocuments.has(edge.target))
        conceptToDocuments.set(edge.target, new Set());
      conceptToDocuments.get(edge.target)!.add(edge.source);
    }
  }

  // At least one concept must bridge 2+ documents
  const bridges = [...conceptToDocuments.values()].filter(docs => docs.size >= 2);
  expect(bridges.length).toBeGreaterThan(0);
});

If that test passes, the graph isn't just a flat collection of disconnected document-concept pairs. It's a connected knowledge structure where concepts act as bridges — exactly the property that makes graph traversal useful for search. And it does pass. Every time.

Running It Locally (With Ollama)

One deliberate choice: BrainLinks uses Ollama with local models instead of the OpenAI API. The embedding model is qwen3-embedding:8b (4096 dimensions) and concept extraction uses qwen3:8b with JSON output mode.

Why? Two reasons. First, running locally means zero API costs and no data leaving your machine—important for a personal knowledge base. Second, it demonstrates that FLXBL's VECTOR fields are model-agnostic. You're not locked into OpenAI's 1536-dimension embeddings or anyone else's. Swap in whatever model fits your use case, set the dimensions in your schema, and FLXBL handles the rest.

To get started:

# Install Ollama and pull models
ollama pull qwen3-embedding:8b
ollama pull qwen3:8b

# Clone and configure
git clone https://github.com/flxbl-dev/brainlinks
cd brainlinks
cp .env.example .env.local
# Add your FLXBL API key and Ollama config

# Install and run
npm install
npx flxbl generate   # Generate typed client from schema
npm run dev

Upload a PDF, watch the pipeline extract concepts and build relationships, then search semantically across your knowledge base. The graph visualization shows your knowledge taking shape in real time.

The Tech Stack

Layer	Technology	Why
Framework	Next.js 16 (App Router)	Server Components, API routes, React 19
Styling	Tailwind CSS 4	Utility-first, dark mode from day one
Graph Visualization	react-force-graph	Interactive, performant, customizable
File Upload	react-dropzone	Drag-and-drop with validation
PDF Extraction	pdf-parse v2	Reliable text extraction
Embeddings	Ollama (qwen3-embedding:8b)	Local, free, model-agnostic
Concept Extraction	Ollama (qwen3:8b)	JSON mode for structured output
Backend	FLXBL	Graph-native BaaS with FILE + VECTOR fields
Type Generation	@flxbl-dev/cli	Typed client from schema, zero manual types

What I Learned

Building BrainLinks confirmed a few things I suspected and taught me a few things I didn't expect:

Confirmed: Graph traversal + vector search is more powerful than vector search alone. The concept-mediated discovery genuinely surfaces documents that pure similarity search misses. It's not a gimmick—it's a qualitative improvement in search quality.

Confirmed: Relationship properties eliminate a class of data modeling problems. relevanceScore on MENTIONS edges and strength on RELATED_TO edges are natural, queryable, and don't require extra tables.

Learned: Concept deduplication is the design challenge. The 0.92 similarity threshold for reusing existing concepts is a magic number I tuned by trial and error. Too low and you merge unrelated concepts. Too high and you get duplicates. There's probably a smarter approach involving clustering, but the simple threshold works surprisingly well.

Learned: Eventual consistency matters. After creating a document and its relationships, I wait 500ms before querying because Neo4j (under the hood) needs a moment to index the new edges. Not a dealbreaker, but something to account for in your pipeline design.

Learned: The FLXBL TypeScript SDK + codegen is genuinely pleasant. Defining the schema, running npx flxbl generate, and getting typed clients with autocomplete for entities and relationships saved me from an entire category of bugs. When I fat-fingered a relationship name, the compiler caught it.

Try It Yourself

GitHub: github.com/flxbl-dev/brainlinks
FLXBL Platform: platform.flxbl.dev
FLXBL Docs: flxbl.dev/docs

The repo includes the complete upload pipeline, three search modes, graph visualization, collection management, and a dashboard—all built on 4 entities and 5 relationships.

If you're building anything where knowledge, content, or entities are connected by meaningful relationships—and especially if you want to combine semantic search with structural discovery—give FLXBL a look. The graph-native approach isn't just a different way to store data. It's a different way to think about data. And once you start thinking in graphs, junction tables start looking like what they are: a workaround.

What's the most relationship-heavy AI project you've built? Did you end up fighting your database to make it work? I'd love to hear about it in the comments.

Marko Mijailović is the creator of FLXBL. You can find him on LinkedIn, reach out through email, or join the FLXBL Discord.

Content Has Relationships. Your Database Should Too.

Marko Mijailović — Thu, 04 Dec 2025 21:13:40 +0000

Building a Graph-Native CMS: Why Your CMS Has a 3-digit Number Of Tables, And Mine Has 12 Entities

TL;DR: Remember when I showed you how FLXBL could find the shortest path between any two actors in six degrees or less? Cool party trick. Now I've built something practical: a content management system called (of course) Kickass CMS that proves graph databases aren't just for path-finding—they're genuinely better for content-first applications. Here's what I learned building content workflows, revision systems, and hierarchical pages on top of FLXBL.

From Kevin Bacon to Content Management

In my last post, I demonstrated FLXBL's graph-native capabilities by building a movie database that could trace Hollywood connections through shared filmography. It was fun, visually impressive, and made for great cocktail party conversation.

But here's the thing: while "six degrees of separation" is a neat trick, it's not exactly an everyday use case. What is an everyday use case? Content management. And as it turns out, CMSes are absolutely riddled with relationships that make them a perfect candidate for graph-native architecture.

Think about it:

Content belongs to authors (with roles like primary, contributor, editor)
Content has categories (potentially featured, with custom ordering)
Content includes media (featured images, galleries, inline images, attachments)
Content follows workflow states (draft → review → approved → published → archived)
Content has revisions (version history with author attribution)
Pages have sections (which contain content, or reference global blocks)
Pages form hierarchies (parent/child relationships for URL paths)
Categories form hierarchies (nested taxonomies)

In a traditional relational CMS, each of these relationships means yet another junction table. Want to track when an author contributed to a piece? That's a column. Want to mark content as featured in a category? Another column. Want to record the role of media in content? You guessed it.

I've been down that road. The migrations alone will give you nightmares.

The Schema: Thinking in Graphs (Again)

When I started designing Kickass CMS, I approached it the same way I approached the movie database: what are the entities, and how do they connect?

The Core Entities

Entity	Purpose	Key Fields
Content	Posts, articles, landing pages	title, slug, contentType, publishedAt, tags
Author	Content creators	name, email, bio, avatarUrl
Category	Hierarchical organization	name, slug, description
Media	Images, files, videos	filename, url, mimeType, size
ContentBlock	Block-based content structure	blockType, content, position
ContentRevision	Version history snapshots	revisionNumber, blocksSnapshot, isCurrent
WorkflowState	Content lifecycle states	name, slug, allowedTransitions
Page	CMS pages with custom routes	title, path, isPublished, showInNav
PageSection	Modular page content areas	sectionType, config, position
Layout	Reusable page templates	name, regions, template
LayoutPlacement	Content placement in layout regions	region, position, settings
Block	Global reusable widgets	name, blockType, content

That's 12 entities. In a traditional CMS, you'd be looking at at least 20+ tables once you factor in all the junction tables for relationships.

The Relationships (Where FLXBL Shines)

Here's where it gets interesting. Let me show you the relationship model:

Relationship	Direction	Properties
`AUTHORED_BY`	Content → Author	`role` (PRIMARY/CONTRIBUTOR/EDITOR), `byline`
`CATEGORIZED_AS`	Content → Category	`featured`, `position`
`HAS_MEDIA`	Content → Media	`role` (FEATURED/GALLERY/INLINE/ATTACHMENT), `position`, `caption`
`HAS_BLOCK`	Content → ContentBlock	`position`
`HAS_STATE`	Content → WorkflowState	`assignedAt`, `assignedBy`
`HAS_REVISION`	Content → ContentRevision	—
`REVISION_CREATED_BY`	ContentRevision → Author	—
`STATE_TRANSITION`	WorkflowState → WorkflowState	`requiresApproval`, `notifyRoles`
`PAGE_PARENT`	Page → Page	—
`CATEGORY_PARENT`	Category → Category	—
`PAGE_HAS_SECTION`	Page → PageSection	—
`PAGE_FILTERS_CATEGORY`	Page → Category	—
`SECTION_HAS_CONTENT`	PageSection → Content	`position`

Notice something? The relationships carry data. When I attach an author to content, I'm not just recording that connection—I'm recording what kind of author they are. When I assign media, I'm capturing how that media is used.

In SQL, this would be:

CREATE TABLE content_authors (
  content_id UUID REFERENCES content(id),
  author_id UUID REFERENCES authors(id),
  role VARCHAR(20) CHECK (role IN ('PRIMARY', 'CONTRIBUTOR', 'EDITOR')),
  byline VARCHAR(255),
  PRIMARY KEY (content_id, author_id)
);

CREATE TABLE content_media (
  content_id UUID REFERENCES content(id),
  media_id UUID REFERENCES media(id),
  role VARCHAR(20) CHECK (role IN ('FEATURED', 'GALLERY', 'INLINE', 'ATTACHMENT')),
  position INTEGER,
  caption TEXT,
  PRIMARY KEY (content_id, media_id)
);

-- ... repeat for every relationship with properties

In FLXBL, these properties just... exist on the edges. The schema declaration handles it:

{
  "name": "AUTHORED_BY",
  "sourceEntityName": "Content",
  "targetEntityName": "Author",
  "cardinality": "MANY_TO_MANY",
  "fields": [
    { "name": "role", "type": "ENUM", "required": true, "enumValues": ["PRIMARY", "CONTRIBUTOR", "EDITOR"] },
    { "name": "byline", "type": "STRING", "required": false }
  ]
}

When I query for content with its authors, the role comes along for the ride—in a single traversal, not a JOIN.

The Implementation: What Made Life Easier

Let me walk through some real code from Kickass CMS that shows the difference.

Workflow State Machine

One of the most relationship-heavy features in any CMS is the workflow system. Content moves through states: Draft → In Review → Approved → Published → Archived. But the transitions aren't arbitrary—you can't go from Draft directly to Published in a professional editorial workflow.

In FLXBL, I model this with the STATE_TRANSITION relationship:

Draft ──[STATE_TRANSITION]──> In Review
In Review ──[STATE_TRANSITION]──> Approved
In Review ──[STATE_TRANSITION]──> Draft (send back)
Approved ──[STATE_TRANSITION]──> Published
Published ──[STATE_TRANSITION]──> Archived
Archived ──[STATE_TRANSITION]──> Draft (resurrect)

The workflow state entity stores allowed transitions as a simple array, and the actual transitions can carry properties like requiresApproval or notifyRoles.

Here's how I transition content between states:

// src/lib/flxbl/workflow.ts
export async function transitionState(
  client: FlxblClient,
  contentId: string,
  newStateId: string,
  assignedBy?: string
): Promise<void> {
  // Get current state
  const currentStateRel = await getContentState(client, contentId);

  // Delete existing state relationship
  if (currentStateRel) {
    await client.deleteRelationship(
      "Content", contentId, "HAS_STATE", currentStateRel.state.id
    );
  }

  // Create new state relationship with metadata
  await client.createRelationship(
    "Content", contentId, "HAS_STATE", newStateId,
    {
      assignedAt: new Date(),
      assignedBy: assignedBy ?? "system",
    }
  );

  // Auto-set publishedAt when transitioning to published
  const newState = await client.get("WorkflowState", newStateId);
  if (newState.slug === "published") {
    await client.patch("Content", contentId, { publishedAt: new Date() });
  }
}

The HAS_STATE relationship doesn't just connect content to a state—it records when the transition happened and who made it. That's audit logging baked into the data model, not bolted on.

The Revision System

Version control for content is another relationship-heavy feature. Every time you save, you want to capture a snapshot that can be restored later. Each revision needs to track which author created it.

Here's how revisions work in Kickass CMS:

// src/lib/flxbl/revisions.ts
export async function createRevision(
  client: FlxblClient,
  contentId: string,
  authorId: string,
  changeMessage?: string
): Promise<ContentRevision> {
  // Get current blocks
  const blocks = await loadContentBlocks(client, contentId);

  // Get existing revisions to determine revision number
  const existingRels = await client.getRelationships(
    "Content", contentId, "HAS_REVISION", "out", "ContentRevision"
  );

  // Mark all existing revisions as not current
  for (const rel of existingRels) {
    if (rel.target.isCurrent) {
      await client.patch("ContentRevision", rel.target.id, { isCurrent: false });
    }
  }

  // Create snapshot as an object with positions as keys
  const blocksObj: Record<string, unknown> = {};
  for (const b of blocks) {
    blocksObj[String(b.position)] = {
      blockType: b.blockType,
      content: b.content,
      metadata: b.metadata,
    };
  }

  // Create the revision
  const revision = await client.create("ContentRevision", {
    revisionNumber: existingRels.length + 1,
    title: (await client.get("Content", contentId)).title,
    blocksSnapshot: blocksObj,
    changeMessage: changeMessage ?? null,
    isCurrent: true,
  });

  // Link revision to content and author
  await client.createRelationship("Content", contentId, "HAS_REVISION", revision.id, {});
  await client.createRelationship("ContentRevision", revision.id, "REVISION_CREATED_BY", authorId, {});

  return revision;
}

When I restore a revision, I create a new revision that records the restoration:

export async function restoreRevision(
  client: FlxblClient,
  contentId: string,
  revisionId: string,
  authorId: string
): Promise<ContentRevision> {
  const revision = await client.get("ContentRevision", revisionId);

  // Delete existing blocks and recreate from snapshot
  // ... (block restoration code)

  // Create a NEW revision recording this restore
  return createRevision(
    client, contentId, authorId,
    `Restored from revision #${revision.revisionNumber}`
  );
}

This means you can never lose history. If you restore revision #3 from revision #7, you get revision #8 that points back to #3. Time travel without paradoxes. (Doc Brown would be proud.)

Hierarchical Pages

Pages in Kickass CMS support parent/child relationships for building URL hierarchies:

/about                    (root page)
  /about/team             (child)
    /about/team/leadership (grandchild)

The PAGE_PARENT relationship handles this elegantly. When I need to build the navigation tree:

// Get all pages with their parent relationships
const pages = await client.list("Page");
const tree: PageNode[] = [];

for (const page of pages) {
  const parentRels = await client.getRelationships(
    "Page", page.id, "PAGE_PARENT", "out", "Page"
  );
  // If no parent, it's a root page
  if (parentRels.length === 0) {
    tree.push(buildPageTree(page, pages));
  }
}

The path field auto-updates when you change a page's parent. Changing the parent of "team" from "about" to "company" automatically updates its path from /about/team to /company/team. No manual URL rewriting.

The Content Editor: Tiptap + FLXBL

Kickass CMS uses Tiptap 3 for rich text editing. Tiptap outputs a JSON document structure that maps beautifully to graph-native storage.

Here's the conversion layer:

// src/lib/flxbl/blocks.ts
export function tiptapToBlocks(doc: TiptapDoc): CreateContentBlock[] {
  const blocks: CreateContentBlock[] = [];

  doc.content.forEach((node, index) => {
    const blockType = mapTiptapTypeToBlockType(node.type);
    if (!blockType) return;

    const content = tiptapNodeToBlockContent(node, blockType);
    blocks.push({
      blockType,
      content,
      position: index,
      metadata: {},
    });
  });

  return blocks;
}

Each content block becomes its own entity, connected to the parent content via HAS_BLOCK. This means I can:

Query for all content that contains a specific image
Find all code blocks using TypeScript
Build a "related content" feature based on shared block types

These are graph traversals, not full-table scans.

What Made This Easier Than SQL

Let me be specific about the developer experience improvements:

1. No Migration Hell

In a SQL-based CMS, adding a new relationship property means:

ALTER TABLE content_authors ADD COLUMN contribution_percentage DECIMAL(5,2);

And then you need to run migrations, handle null values for existing records, update your ORM models, regenerate types...

In FLXBL, I update the schema definition and publish:

{
  "name": "role",
  "type": "NUMBER",
  "required": false,
  "description": "Contribution percentage"
}

Done. The API immediately accepts the new property.

2. Relationship Properties Are First-Class

When I query content with authors, I get the relationship properties automatically:

const authorRels = await client.getRelationships(
  "Content", contentId, "AUTHORED_BY", "out", "Author"
);

// Each result has both the target entity AND the relationship properties
for (const rel of authorRels) {
  console.log(`${rel.target.name} - ${rel.relationship.properties.role}`);
  // "Jane Smith - PRIMARY"
  // "Bob Jones - CONTRIBUTOR"
}

No JOINs. No separate queries. Just data.

3. Type Safety All The Way Down

I generated Zod schemas from the FLXBL schema using the MCP tool:

export const AuthoredByPropsSchema = z.object({
  role: z.enum(["PRIMARY", "CONTRIBUTOR", "EDITOR"]),
  byline: z.string().nullish(),
});

export type AuthoredByProps = z.infer<typeof AuthoredByPropsSchema>;

The FLXBL client validates responses at runtime. If the API returns something unexpected, Zod catches it immediately—not after it's caused a cryptic error in the UI.

4. Hierarchy Queries Are Trivial

Building a category tree in SQL:

WITH RECURSIVE category_tree AS (
  SELECT id, name, slug, NULL::UUID as parent_id, 0 as depth
  FROM categories WHERE parent_id IS NULL

  UNION ALL

  SELECT c.id, c.name, c.slug, c.parent_id, ct.depth + 1
  FROM categories c
  JOIN category_tree ct ON c.parent_id = ct.id
)
SELECT * FROM category_tree ORDER BY depth, name;

In FLXBL:

const categories = await client.list("Category");
const parentRels = await client.getRelationships(
  "Category", categoryId, "CATEGORY_PARENT", "out", "Category"
);

The graph model means I'm traversing edges, not doing recursive self-joins.

Live Demo (With a Caveat)

You can try Kickass CMS right now:

Live Demo: kickass-cms.vercel.app
GitHub: github.com/flxbl-dev/kickass-cms

A Note on Performance

You might notice the demo isn't blazingly fast. Here's why: it's running on Vercel without ISR caching enabled, and FLXBL is currently running on a single server with rate limits.

This isn't a FLXBL limitation—it's intentional for the public beta. Rate limiting prevents any single demo from DDoSing the shared infrastructure. In a production scenario with dedicated resources and proper caching, response times would be dramatically better.

The demo is about showcasing the architecture and developer experience, not benchmarking cold-start Lambdas against a rate-limited API. Once you're running your own FLXBL tenant with appropriate infrastructure, performance is a non-issue.

The Tech Stack

Layer	Technology	Why
Framework	Next.js 16	App Router, RSC, API routes
UI	React 19 + Tailwind CSS 4	Modern, fast, flexible
Components	shadcn/ui	Accessible primitives
Editor	Tiptap 3	Block-based, extensible, outputs JSON
Validation	Zod	Runtime type safety
Backend	FLXBL	Graph-native BaaS

The entire admin interface is server-rendered. Content management happens via API routes that call the FLXBL client. The public site uses static generation where possible, with dynamic routes for category/author/tag archives.

What's Next

Kickass CMS is a proof of concept—a demonstration that graph-native backends can power real-world applications beyond "find me the shortest path."

Things I'm considering for future iterations:

Real-time previews using FLXBL's GraphQL subscriptions
Multi-tenant support so each customer gets isolated content
Media processing pipeline with automatic image optimization
Full-text search integration with Elasticsearch or Meilisearch
Import/export for migrating from WordPress, Ghost, etc.

Try It Yourself

If you're building something content-heavy and tired of junction table spaghetti:

Sign up at platform.flxbl.dev
Clone the repo: git clone https://github.com/flxbl-dev/kickass-cms
Add your FLXBL credentials to .env.local
Run pnpm dev and start exploring

The codebase includes:

Complete admin interface with content editing
Revision system with restore functionality
Workflow state management
Hierarchical pages with category filtering
Block-based content with Tiptap integration

The Bottom Line

CMSes are fundamentally about content and the relationships between content. Authors write posts. Posts belong to categories. Categories have hierarchies. Media gets attached with specific roles. Workflow moves content through states.

Every one of these is a relationship. And when your database treats relationships as second-class citizens (foreign keys, junction tables, recursive CTEs), you spend more time fighting the data model than building features.

FLXBL's graph-native approach isn't just theoretically cleaner—it's practically faster to develop with. The Kickass CMS schema has 12 entities and 18 relationships. In Postgres, that would be 30+ tables. In FLXBL, it's just... 12 entities and 18 relationships.

What CMS features have you struggled to implement cleanly in a relational database? I'd love to hear about the workarounds you've built—and whether a graph-native approach might have helped.

Marko Mijailović is the creator of FLXBL. You can find him on LinkedIn, reach out through email, or join the FLXBL Discord.

Building "6 Degrees of Kevin Bacon" with a Graph-Native Backend: Why I Created FLXBL

Marko Mijailović — Tue, 02 Dec 2025 21:11:56 +0000

TL;DR: After years of wrestling with recursive CTEs, junction tables, and the existential dread of N+1 queries, I built a graph-native Backend-as-a-Service called FLXBL. To prove it actually works (and isn't just vaporware from a sleep-deprived developer), I built a mock movie discovery platform that finds the shortest path between any two actors. Here's what I learned—and why you might want to ditch your relational database for relationship-heavy applications.

The Problem That Started It All

Have you ever played the Six Degrees of Kevin Bacon game? The premise is beautifully simple: any actor in Hollywood can be connected to Kevin Bacon through their film appearances in six steps or fewer. Tom Hanks was in Apollo 13 with Kevin Bacon—that's one degree. Meryl Streep was in The River Wild with Kevin Bacon—also one degree.

Simple game. Not-so-simple data problem.

The SQL Nightmare

Here's what I realized when I first tried to build this: finding a path between two actors requires either recursive queries or graph traversal—and relational databases are notoriously bad at the former while not supporting the latter at all.

Let me illustrate with some SQL that will give you nightmares:

WITH RECURSIVE actor_path AS (
  -- Base case: start from Actor A
  SELECT 
    p.id as actor_id,
    m.id as movie_id,
    ARRAY[p.id] as path,
    1 as depth
  FROM persons p
  JOIN acted_in ai ON p.id = ai.person_id
  JOIN movies m ON ai.movie_id = m.id
  WHERE p.id = $start_actor_id

  UNION ALL

  -- Recursive case: find co-stars (and pray for your database's soul)
  SELECT 
    p2.id,
    m2.id,
    ap.path || p2.id,
    ap.depth + 1
  FROM actor_path ap
  JOIN acted_in ai1 ON ap.movie_id = ai1.movie_id
  JOIN persons p2 ON ai1.person_id = p2.id
  JOIN acted_in ai2 ON p2.id = ai2.person_id
  JOIN movies m2 ON ai2.movie_id = m2.id
  WHERE NOT (p2.id = ANY(ap.path))  -- Cycle detection
    AND ap.depth < 6
)
SELECT * FROM actor_path WHERE actor_id = $end_actor_id LIMIT 1;

This query has more joins than a yoga class. And it gets exponentially slower as the search depth increases—each hop multiplies the result set by the average number of co-stars (~50 per actor). By hop 3, you're looking at 125,000 potential paths. By hop 6? Your DBA is updating their resume.

The Realization

I kept running into this problem across different projects: social networks (friends-of-friends), recommendation engines (users-who-liked-also-liked), organizational hierarchies (who-reports-to-whom), supply chains (component-dependencies). The pattern was always the same: entities connected by relationships, where the relationships matter as much as the entities themselves.

And every time, I found myself:

Creating junction tables with foreign keys
Writing recursive CTEs that made my eyes bleed
Implementing manual cycle detection
Watching query times go from milliseconds to "let's grab coffee"

That's when I thought: What if the database understood relationships natively?

That's why I built FLXBL.

What is FLXBL?

FLXBL (pronounced "flexible") is a Graph-Native Backend-as-a-Service. You define your schema with entities and relationships using a visual editor, and FLXBL automatically generates production-ready REST and GraphQL APIs.

The magic? Under the hood, your data lives in a graph database where relationships are first-class citizens—not foreign keys bolted onto tables.

The Two-Plane Architecture (AKA "The Clever Bit")

FLXBL uses a two-plane architecture that gives you the best of both worlds:

┌─────────────────────────────────────────────────────────────┐
│                    FLXBL Platform                           │
├──────────────────────────────┬──────────────────────────────┤
│     Control Plane            │      Data Plane              │
│     (PostgreSQL)             │      (Neo4j)                 │
│                              │                              │
│  • Schema definitions        │  • Your actual data          │
│  • User authentication       │  • Relationships as edges    │
│  • API key management        │  • Graph traversal queries   │
│  • Webhook configurations    │  • Blazing fast path-finding │
│  • Migration tracking        │                              │
└──────────────────────────────┴──────────────────────────────┘

PostgreSQL handles all the "boring but important" stuff—users, permissions, schemas, API keys. Neo4j handles your actual application data, storing it as a graph where relationships have equal standing with entities.

Why does this matter? Because when you query "find all actors who worked with Tom Hanks," you're not performing JOINs across junction tables—you're literally traversing edges in a graph. The database was designed for this operation.

How FLXBL Differs from Firebase/Supabase

Feature	Firebase	Supabase	FLXBL
Data Model	Document (NoSQL)	Relational (PostgreSQL)	Graph (Neo4j)
Relationships	Denormalized/manual	Foreign keys + JOINs	First-class edges
Relationship Properties	Stored in documents	Junction tables	Native edge properties
Multi-hop Queries	Manual, N+1 prone	Recursive CTEs (pain)	Native traversal
Visual Schema Editor	No	Limited	Drag-and-drop with live preview
Auto-generated APIs	REST only	REST + GraphQL (via PostGraphile)	REST + GraphQL (native parity)
AI Integration	No	No	MCP tools for AI-assisted editors, standalone AI apps

The biggest differentiator: FLXBL treats relationships as first-class citizens. If your application is relationship-heavy, you're working with the data model instead of fighting against it.

The "6 Degrees of Kevin Bacon" Project

To demonstrate what FLXBL can do (and frankly, to have some fun), I built a complete movie discovery platform: 6 Degrees of Kevin Bacon.

The app lets you select any two actors and finds the shortest path between them through their shared filmography. Behind the scenes, it's running a bi-directional breadth-first search across a graph of ~800 actors and movies—and it finds connections.

Full source code: flxbl-dev/6-degrees-of-bacon

Modeling the Schema: Thinking in Graphs

When you use FLXBL, you think in terms of entities (the nodes) and relationships (the edges connecting them). Coming from a relational mindset, this is both liberating and slightly disorienting—like learning to ride a bike but the bike is made of concepts.

The Entities

I started with six core entities:

Entity	Purpose	Key Fields
Movie	Films in the database	title, releaseYear, posterUrl, tmdbRating
Person	Actors, directors, writers	name, photoUrl, biography
Genre	Categories like Action, Drama	name
User	Platform users	email, username
Review	User ratings and reviews	rating, content
Collection	Movie franchises, curated lists	name, description

The Relationships (Where the Magic Happens)

Here's where FLXBL diverges from relational thinking. In PostgreSQL, you'd model "Actor appeared in Movie" with a junction table:

CREATE TABLE acted_in (
  person_id UUID REFERENCES persons(id),
  movie_id UUID REFERENCES movies(id),
  character VARCHAR(255),
  billing_order INTEGER,
  is_lead_role BOOLEAN,
  PRIMARY KEY (person_id, movie_id)
);

Three extra columns, a primary key constraint, and you still need JOINs to query it. In FLXBL, it's a relationship with properties:

Person --[ACTED_IN]--> Movie
  └── character: "Forrest Gump"
  └── billingOrder: 1
  └── isLeadRole: true

The relationship itself carries data. When I query for Tom Hanks's filmography, I get both the movies AND the characters he played—in a single traversal. No JOINs. No N+1 queries. Just... data.

Here's the complete relationship model for the project:

Relationship	From → To	Properties	Purpose
`ACTED_IN`	Person → Movie	character, billingOrder, isLeadRole	Track who played whom
`DIRECTED`	Person → Movie	—	Directorial credits
`WROTE`	Person → Movie	—	Writing credits
`HAS_GENRE`	Movie → Genre	—	Movie categorization
`WROTE_REVIEW`	User → Review	—	Review authorship
`HAS_REVIEW`	Movie → Review	—	Reviews for movies
`FOLLOWS`	User → User	followedAt	Social graph
`WATCHLIST`	User → Movie	addedAt, priority	User's watch queue
`WATCHED`	User → Movie	watchedAt, rewatchCount	Watch history

Notice FOLLOWS? It connects Users to other Users. Try modeling that elegantly in SQL. Go ahead, I'll wait.

(Spoiler: You'll end up with a self-referential junction table and a recursive CTE that questions your career choices.)

The Code: Graph Queries That Don't Make You Cry

Let me show you the actual difference with code from the project.

Fetching an Actor's Movies (GraphQL)

With FLXBL's auto-generated GraphQL API, I can fetch an actor's movies and their character names in one query:

query GetPersonMovies($personId: ID!) {
  person(id: $personId) {
    name
    photoUrl
    moviesConnection {
      edges {
        character        # ← Relationship property!
        billingOrder
        isLeadRole
        node {
          id
          title
          releaseYear
          posterUrl
        }
      }
    }
  }
}

The moviesConnection returns edges with both the relationship properties (character, billingOrder) and the connected movie nodes. One request. Complete data. Zero existential dread.

The Query DSL: SQL for Graph People

FLXBL also provides a powerful Query DSL for REST that translates to optimized Cypher queries. Here's a real query from the project:

query GetActorFilmography($name: String!) {
  people(where: { name: { equals: $name } }, limit: 1) {
    id
    name
    photoUrl
    bio
    birthPlace

    # Traverse ACTED_IN relationship with edge properties
    moviesConnection {
      edges {
        # Relationship properties
        character
        billingOrder
        isLeadRole

        # Target movie with nested genre traversal
        node {
          id
          title
          releaseYear
          averageRating
          boxOffice
          posterUrl

          # Another traversal: Movie → Genres
          genres {
            name
            iconEmoji
          }
        }
      }
    }
  }
}

This query says: "In a single request, fetch an actor's complete filmography with the characters they played, whether it was a lead role, and each movie's genres - traversing 3 levels of the graph."

In SQL, this would be... let's just say "significantly more verbose."

The Path-Finding Algorithm: Bi-Directional BFS

The signature feature—finding connections between actors—uses bi-directional breadth-first search. Instead of searching from Actor A all the way to Actor B (which explodes exponentially), I search from both ends and meet in the middle:

Tom Hanks ──────────────> <────────────── Meryl Streep
         Forward BFS        Backward BFS
                      ↓
               Meeting Point! 🎉

This reduces complexity from O(b^d) to O(2 × b^(d/2)), where b is the branching factor (~50 co-stars per person) and d is the degrees of separation.

Translation for non-algorithm nerds: Instead of checking millions of paths, we check thousands. Your users get results in seconds instead of never.

Here's a simplified version of the algorithm:

export async function findConnectionPath(
  startPersonId: string,
  endPersonId: string,
  maxDepth: number = 6
): Promise<ConnectionResult | null> {
  // Initialize two frontiers - one from each actor
  const forwardVisited = new Map<string, BFSNode>();
  const backwardVisited = new Map<string, BFSNode>();

  let forwardQueue = [startPersonId];
  let backwardQueue = [endPersonId];

  while (totalDepth < maxDepth) {
    // Expand the smaller frontier (more efficient)
    const expandForward = forwardQueue.length <= backwardQueue.length;

    if (expandForward) {
      // Get co-stars via FLXBL's relationship endpoint
      const result = await expandFrontier(
        forwardQueue,
        forwardVisited,
        backwardVisited  // Check if frontiers have met!
      );

      if (result) {
        // 🎉 Frontiers met - reconstruct path
        return reconstructBidirectionalPath(result.meetingPersonId, ...);
      }
    }
    // ... expand backward frontier similarly
  }

  return { found: false, degrees: -1, path: [] };
}

The getCoStarsOptimized function uses a hybrid approach—GraphQL for fetching movies (gets relationship properties in one call), and parallelized REST calls for fetching movie casts:

export async function getCoStarsOptimized(personId: string): Promise<CostarWithMovie[]> {
  // GraphQL: Get all movies this person acted in (with their characters)
  const movies = await getPersonMoviesGraphQL(personId);

  // REST: Fetch cast for each movie in parallel (FLXBL handles the load)
  const castResults = await Promise.all(
    movies.map(async (movie) => ({
      movie,
      cast: await getMovieCast(movie.id),
    }))
  );

  // Combine into co-star list with movie context
  // No N+1 queries because FLXBL batches relationship traversals
  return results;
}

The Developer Experience: From Zero to API

Let me walk you through what it actually feels like to use FLXBL.

Step 1: Design Your Schema Visually

No YAML files. No migration scripts. Just drag, drop, and connect, fill in the names, the types, the descriptions (if you want to be nice to people that are going to implement what you're doodling).

Step 2: Get Your APIs Instantly

The moment you publish your schema, FLXBL generates:

REST Endpoints (for every entity):

GET    /api/v1/dynamic/Person           # List all
POST   /api/v1/dynamic/Person           # Create
GET    /api/v1/dynamic/Person/:id       # Get one
PUT    /api/v1/dynamic/Person/:id       # Update
DELETE /api/v1/dynamic/Person/:id       # Delete
POST   /api/v1/dynamic/Person/query     # Query DSL

Relationship Endpoints:

POST   /api/v1/dynamic/Person/:id/relationships/ACTED_IN
GET    /api/v1/dynamic/Person/:id/relationships/ACTED_IN?direction=out
DELETE /api/v1/dynamic/Person/:id/relationships/ACTED_IN/:targetId

GraphQL Endpoint:

POST   /api/v1/dynamic-gql/{tenantId}
GET    /api/v1/dynamic-gql/{tenantId}/schema.graphql  # Download SDL

Step 3: Generate Type-Safe Clients

Use the MCP tools (more on this below) or the API to generate TypeScript interfaces, Zod schemas, or Python Pydantic models:

// Auto-generated from your FLXBL schema
interface Person {
  id: string;
  name: string;
  photoUrl?: string;
  biography?: string;
  createdAt: string;
  updatedAt: string;
}

interface ActedInRelationship {
  character?: string;
  billingOrder?: number;
  isLeadRole?: boolean;
}

No more any types. No more runtime surprises. Just... actual type safety.

MCP Integration: AI-Assisted Backend Development

Here's something that made even me double-take: FLXBL has native integration with Model Context Protocol (MCP), which means AI assistants in Cursor, Windsurf, or VS Code can directly interact with your FLXBL schema.

What Can the AI Actually Do?

Tool	What It Does
`validate_schema`	Check your schema for errors before publishing
`publish_schema_version`	Create a new schema version from natural language
`check_migration_status`	Track migration progress
`generate_client_types`	Generate TypeScript, Zod, Python, or API contracts
`list_schema_templates`	Browse pre-built templates for common use cases

Real Example Workflow

Here's an actual conversation I had with Claude in Cursor:

Me: "Add a Reviews entity to my Movie schema. Users should be able to rate movies 1-5 and leave comments."

Claude: reads current schema via flxbl://schema/active

Claude: "I'll add a Review entity with rating (NUMBER, 1-5), content (TEXT), and create relationships: WROTE_REVIEW (User → Review) and HAS_REVIEW (Movie → Review). Should I include a timestamp for when the review was written?"

Me: "Yes, add createdAt as a DATETIME."

Claude: uses publish_schema_version tool

Claude: "Done! Schema version 1.3.0 published. The migration is in progress—I'll check the status."

uses check_migration_status

Claude: "Migration complete. Your new endpoints are ready:

POST /api/v1/dynamic/Review
GET /api/v1/dynamic/Movie/:id/relationships/HAS_REVIEW
..."

No context switching. No documentation diving. Just... chill. (And production-ready APIs.)

IDE Configuration

{
  "mcpServers": {
    "flxbl": {
      "command": "npx",
      "args": ["@flxbl-dev/mcp"],
      "env": {
        "FLXBL_INSTANCE_URL": "https://api.flxbl.dev",
        "FLXBL_API_KEY": "flxbl_your_key_here"
      }
    }
  }
}

Security: Because Your Data Matters

A few things I baked in from day one:

Multi-Tenant Isolation

Every query includes automatic tenant filtering. Your data is your data—there's no universe where a misconfigured query leaks data between tenants.

API Key Security

flxbl_<8-char-prefix>_<48-char-secret>

Prefix for fast lookup without exposing the secret
192 bits of entropy
Bcrypt-hashed in storage
Never logged, never exposed

Webhook Verification

All webhooks include HMAC-SHA256 signatures so you can verify they actually came from FLXBL:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(JSON.stringify(payload));
  return signature === hmac.digest('hex');
}

Try It Yourself

The complete "6 Degrees of Kevin Bacon" project is open source and ready to clone:

Live Demo: 6-degrees-of-bacon.vercel.app
GitHub: flxbl-dev/6-degrees-of-bacon
FLXBL Platform: platform.flxbl.dev
Documentation: flxbl.dev/docs

The repo includes a TMDB seeding script that populates your FLXBL instance with ~50 movies and ~200 actors centered around Kevin Bacon—enough data to demonstrate meaningful path-finding and have some fun discovering unexpected connections.

When Should You Use FLXBL?

FLXBL is ideal for:

Social applications — followers, friends, activity feeds
E-commerce — product relationships, "frequently bought together"
Content platforms — authors, posts, comments, tags
Knowledge graphs — interconnected concepts, research papers
Organizational tools — reporting hierarchies, team dependencies
Recommendation engines — user-item-feature relationships
Anything with "six degrees" problems — and there are more than you think

FLXBL might be overkill for:

Simple CRUD apps with no relationships
Document-centric applications
Time-series data
Applications that need raw SQL access

What's Next?

FLXBL is in public beta, and I'm actively building based on developer feedback. Some things on the roadmap:

More schema templates — CRM, CMS, project management out of the box
Enhanced webhook integrations — Zapier, Slack, and more
Query DSL improvements — aggregations, nested traversals
Real-time subscriptions — GraphQL subscriptions for live updates
Self-hosted option — for those who need it on-prem

If you're building something relationship-heavy and tired of fighting your database, give FLXBL a try. I'd genuinely love to hear what you build—and what pain points you hit. That's how this thing gets better.

The Bottom Line

Every time I see a recursive CTE or a five-table JOIN for a simple "friends of friends" query, a small part of me dies. Relational databases are incredible tools—but they're not the right tool for every job.

If your data is fundamentally about connections, relationships, and paths between things, a graph-native approach isn't just marginally better—it's a different paradigm. Queries that were "theoretically possible but practically insane" become trivial. Data models that required mental gymnastics become intuitive.

FLXBL is my attempt to bring that paradigm to developers without requiring them to become Neo4j experts, Cypher query authors, or DevOps wizards. Define your schema. Get your API. Build something cool.

What's the most relationship-heavy application you've built? How did you model it? Drop a comment below—I'm genuinely curious about the creative solutions people have found (or the pain they've endured).

Marko Mijailović is the creator of FLXBL. You can find him on LinkedIn or reach out through email, or join FLXBL Discord