DEV Community: Scott Waddell

How I Built a Conversation Graph Engine in an Evening

Scott Waddell — Sun, 07 Dec 2025 17:58:23 +0000

Well, sort of. The code took an evening. The thinking took months, two provisional patents, and a lot of wrong turns. But when the architecture finally clicked, shipping it was the easy part.

Every AI conversation is stuck in the past.

Not philosophically. Literally. Every chat system, from ChatGPT to enterprise support bots, treats conversations as flat lists:

Message 1 → Message 2 → Message 3 → Message 4 → ...

This works until it doesn't. And it stops working fast.

The problem shows up everywhere:

You're planning a trip to Paris. Halfway through, you ask about restaurant recommendations. Then you're back to flights. Then hotels. Then you remember you wanted to ask about the restaurants again.

The AI has no idea what you're talking about. It either dumps the entire history into context (expensive, slow, noisy) or loses the thread entirely.

Ask "what did we decide about dinner?" and you'll get a hallucinated answer or a polite "I don't have that information."

Flat lists can't represent how conversations actually work.

Conversations are graphs.

Topics branch. Context shifts. Threads reconnect. A conversation about buying a house naturally splits into financing, locations, schools, commute times, then merges back when you're comparing options.

So I built a system that treats them that way.

driftos-core routes messages to semantic branches:

import { createDriftClient } from '@driftos/client';

const drift = createDriftClient('http://localhost:3000');

// Start a conversation
await drift.route('conv-1', 'I want to buy a house in London');
// → BRANCH: "buying a house in London"

await drift.route('conv-1', 'What areas have good schools?');
// → STAY: same branch (related question)

await drift.route('conv-1', 'What should I cook for dinner?');
// → BRANCH: "cooking and dinner" (new topic)

await drift.route('conv-1', 'Back to houses - what about mortgage rates?');
// → ROUTE: returns to "buying a house in London"

Three routing decisions: STAY, BRANCH, or ROUTE.

The LLM figures out which one, and the system maintains the graph.

Routing is LLM-driven: fast and flexible, not deterministic. The commercial version adds reproducible, auditable decisions for compliance.

Facts come along for the ride.

Each branch extracts structured facts with provenance:

{
  "branchTopic": "buying a house in London",
  "facts": [
    { "key": "destination", "value": "London" },
    { "key": "intention", "value": "buy a house" },
    { "key": "priority", "value": "good schools" }
  ]
}

When you assemble context for an LLM call, you get the relevant branch messages plus facts from related branches. 20 messages instead of 1000. Focused context instead of noise.

The architecture looks simple. That's the point.

Message comes in
LLM classifies: STAY / ROUTE / BRANCH
Message goes to the right branch
Facts extracted on ROUTE / BRANCH
Context assembled on demand

Sub-500ms latency. Fast enough for real-time chat

Why open source this now?

The code is ~2,700 lines. But behind it sits two provisional patents and months of architecting the full system: finite state machines, dual-axis drift detection, semantic overlays, cluster allocation, merge promotion, lens-based visualisation. The complete DriftOS.

Complex systems take time. And I kept waiting for "ready".

So I stripped it back. What's the simplest thing that solves the problem? Route messages to branches. Extract facts. Assemble context. Ship it.

driftos-core isn't DriftOS. It's the core idea, out in the wild. Real users. Real feedback. The commercial version, with the graph mechanics enterprises need for compliance and audit trails, is still coming. But this lets me learn in public instead of building in a vacuum.

What this isn't (yet):

This is an MVP. v0.1.0. It works, but it's raw.

No auth. No multi-tenant. No hosted version. You'll need to run your own Postgres and bring your own Groq API key.

The routing sometimes over-branches. The fact extraction is basic. There's no UI.

But the core works: messages route to branches, facts get extracted, context assembles. The foundation is solid enough to build on.

Try it. Break it. Tell me what's missing.

The best feedback comes from people actually using it. Star it if it's interesting. Open an issue if it's broken. DM me if you want to talk about conversation graphs.

And if you're building something with AI context management, maybe stop fighting flat lists.

Conversations are graphs. Treat them that way.

GitHub: github.com/DriftOS/driftos-core
JS SDK: npm install @driftos/client
Docs: In the README

Patent pending on the advanced graph mechanics. The OSS version is the learning foundation.

Scott Waddell is building DriftOS: conversation infrastructure for AI. Previously product at Antler, IBM, and Queensland Government. Based in London.

BaseOrchestrator: A Pattern for Complex Async Pipelines in Node/Fastify

Scott Waddell — Thu, 04 Dec 2025 01:34:53 +0000

The Problem

You're building a backend that processes requests through multiple stages: validate input, check permissions, create records, send notifications, update analytics.

Each stage can fail. Some failures should stop everything (payment failed), others shouldn't (notification service down). You need per-stage timing for debugging. You need tests that don't require mocking the entire world.

The typical evolution:

Week 1: Clean

async function createOrder(input: OrderInput) {
  validate(input);
  const order = await db.orders.create(input);
  await sendEmail(order);
  return order;
}

Week 8: Reality

async function createOrder(input: OrderInput) {
  try {
    const errors = validate(input);
    if (errors.length) throw new ValidationError(errors);

    let order;
    try {
      order = await db.orders.create(input);
    } catch (dbError) {
      logger.error('DB failed', dbError);
      throw new DatabaseError(dbError);
    }

    try {
      await sendEmail(order);
    } catch (emailError) {
      logger.warn('Email failed', emailError);
      metrics.increment('email_failures');
    }

    try {
      await analytics.track('order_created', order);
    } catch (analyticsError) {
      logger.warn('Analytics failed', analyticsError);
    }

    return order;
  } catch (error) {
    metrics.increment('order_failures');
    throw error;
  }
}

Built this while dealing with a 16-stage pipeline. Extracted the pattern into a starter template.

The Pattern

1. Operations - Functions that do one thing. Validate, fetch, create, notify - pick one. They take context, return context. They can hit the database, call APIs, whatever. But each one owns one job.

export async function createOrder(ctx: OrderContext) {
  if (ctx.errors.length > 0) return ctx;

  const order = await ctx.prisma.order.create({
    data: {
      customerId: ctx.input.customerId,
      items: ctx.input.items,
      total: ctx.input.total,
    },
  });

  return { ...ctx, order };
}

2. Orchestrator - Defines the pipeline. Runs each operation in sequence.

export class CreateOrderOrchestrator extends BaseOrchestrator
  OrderContext,
  Order,
  CreateOrderInput
> {
  protected getPipeline() {
    return [
      { name: 'validate', operation: validateInput, critical: true },
      { name: 'create', operation: createOrder, critical: true },
      { name: 'notify', operation: sendNotification, critical: false },
    ];
  }
}

critical: true means stop if it fails. critical: false means log the error and keep going. Your order gets created even if the notification service is down.

3. Context - Typed object that gets passed through. Operations read from it and add to it.

interface OrderContext extends OperationContext {
  input: CreateOrderInput;
  prisma: PrismaClient;
  order?: Order;
  errors: Error[];
  results: Record<string, unknown>;
}

What You Get

Per-operation timing - Every response includes a breakdown:

{
  "success": true,
  "duration": 45,
  "metrics": {
    "validate": 5,
    "create": 28,
    "notify": 12
  }
}

Swagger docs - TypeBox schemas become OpenAPI. Hit /documentation and your API is documented. No YAML files.

Grafana dashboards - Run npm run generate:dashboards. It reads your orchestrators and builds dashboards with the right Prometheus queries.

Testable operations - Each operation does one thing, so you mock one thing:

it('creates order with correct customer', async () => {
  const mockPrisma = { 
    order: { 
      create: vi.fn().mockResolvedValue({ id: 'order-123' }) 
    } 
  };

  const ctx = { 
    input: { customerId: 'cust-1', items: [], total: 100 },
    prisma: mockPrisma,
    errors: [],
    results: {},
  };

  const result = await createOrder(ctx);

  expect(mockPrisma.order.create).toHaveBeenCalledWith(
    expect.objectContaining({ 
      data: expect.objectContaining({ customerId: 'cust-1' }) 
    })
  );
  expect(result.order.id).toBe('order-123');
});

What's in the Starter

BaseOrchestrator with TypeScript generics
Prometheus metrics per operation
Grafana dashboard generator
Swagger from TypeBox
JWT auth
Prisma + migrations
Tests next to the code they test
CLI to scaffold new services

Run npm run generate, pick "Service", answer the prompts. You get an orchestrator, operations, types, tests, and routes. About 600 lines across 14 files.

When to Skip This

Simple CRUD - If it's just prisma.user.findUnique(), use Prisma directly. Don't add layers you don't need.

One step - If there's no pipeline, don't pretend there is.

The pattern pays off at 3+ stages, or when you need to mix "must succeed" and "nice to have" operations, or when you're debugging and need to know which stage is slow.

Why Not Pure Functions?

I tried "operations return intents, orchestrator executes them." Sounds clean. In practice:

Intent types explode - Every side effect needs a type. The union grows forever.
Context gets weird - The operation knows why it's creating a record, but now it's disconnected from the actual create. Error handling gets awkward.
Read-then-write breaks - What if you need to fetch something, then decide what to write based on what you fetched? Now you need multi-step intents or nested orchestration.

Current approach: operations own their side effects. You get isolation without purity. If you want actual purity, look at Effect-TS or fp-ts. This is for people who want structure without changing how they write TypeScript.

What's wrong with this?

This is my first real backend project - I've been mostly frontend/product before this. Built it to solve a real problem I had, but I'm sure there are patterns I'm missing or things I've overcomplicated.

Repo: github.com/DriftOS/fastify-starter