How FarkiBot Works

FarkiBot is Farkitect’s AI assistant. This page is about why it behaves the way it does — the decisions behind it, and what they cost.

If you want to use it, start with How to set up FarkiBot.

The problem with AI in a modelling tool

A model is a claim about reality that people make decisions with. That makes it a bad place for confident fabrication.

Ask a general-purpose chatbot about your enterprise architecture and it will answer. It will name systems, describe dependencies, and identify risks — fluently, plausibly, and with no way for you to tell which parts came from your model and which came from the several thousand architecture documents in its training data.

The output is indistinguishable from a good answer. That’s the problem. You can’t audit it, you can’t cite it, and you can’t hand it to someone who will act on it.

So FarkiBot is built around a single constraint: an answer must be traceable to something you can check.

Grounded by default

FarkiBot answers only from your model and your attachments. When the model doesn’t record something, it says so rather than filling the gap.

This makes FarkiBot less impressive in a demo and more useful in practice. “Your model doesn’t record system owners” is a worse-looking answer than a tidy table of owners, and an immeasurably better one — because the first is a finding about your model and the second is fiction.

It also means a FarkiBot answer has a property most AI output doesn’t: you can check it. Every claim points at named model content you can go and look at.

The exception, made explicit

Some questions genuinely need the outside world — whether a technology is still supported, what a standard requires now, how your portfolio compares to current practice.

Web research is therefore opt-in per question, never on by default. When it’s on:

Your model stays authoritative. Web results are evidence about the world, compared against your model — never a substitute for reading it, and never reported as being in it.
Every web claim carries an inline citation you can follow.
If the search couldn’t answer something, FarkiBot says so rather than guessing.
The answer carries a Web badge, so you always know which kind of answer you’re reading.

The distinction being preserved is between what your model says and what the world says. Blurring those two is how architecture documents become untrustworthy.

Bring your own key

FarkiBot doesn’t resell you AI. You bring an API key for a provider you choose, and Farkitect uses it on your behalf.

There are three reasons, and they’re worth separating.

1. Your content doesn’t touch our servers

Your API key and your model content go directly from your browser to your provider. Farkitect’s servers are never in the path.

This isn’t a policy promise — it’s an architectural fact, and you can verify it yourself: open your browser’s network inspector and watch a run. You’ll see requests to your provider and none to Farkitect carrying your content.

Inviting inspection is the strongest trust signal available, because it converts a promise into something checkable. It’s the same principle as the rest of FarkiBot.

The property is enforced in code by a strict Content-Security-Policy: a browser-level allow-list of which hosts the app may contact at all. Farkitect’s pages can reach its own backend and the AI providers, and nothing else — the browser itself refuses everything not on the list. There’s a permanent test in the codebase that fails if anyone widens that list, because the most likely way this guarantee dies is a well-meaning contributor “fixing” a network error.

2. No lock-in

One OpenRouter key reaches 300+ models from every major lab. If a better model ships next month, you switch to it in a dropdown. If your organisation standardises on Claude, or on a self-hosted model behind an internal gateway, FarkiBot uses that instead.

A tool that bundled its own AI would be making that choice for you permanently, and would have every incentive to keep making it.

3. No margin on tokens

We don’t mark up your AI usage, because we never touch it. You pay your provider directly, at their price, and you can see exactly what a run cost.

This also means we have no incentive to make FarkiBot chatty. A feature that made money per token would be designed differently, and you’d be able to tell.

The cost of this decision is real: setting up FarkiBot takes five minutes and an account with someone else. We think that’s the right trade for a tool that reads your architecture.

Your key, at rest

If you tick Remember on this browser, your key is stored encrypted (AES-256), wrapped by a key the browser holds internally that no website code — including Farkitect’s — can export. It is never written in the clear. Anyone inspecting the browser’s storage sees ciphertext.

This is deliberately stronger than the norm: most BYOK web tools persist API keys in plaintext localStorage.

The honest limit: no browser or desktop application can protect a secret from malicious code running as the application itself. Nothing can. The defences that remain meaningful in that case are the Content-Security-Policy — a stolen key has nowhere to be sent — and the capped, dedicated key we recommend you create. A cap is the one control that holds no matter what else fails.

Nothing is written until you say so

Generated packages are staged, not written. FarkiBot produces a .farki file, validates it, and hands you a card. Your project is untouched until you click Import.

Between generation and import sits a review step that shows the package as a tree — every element, relationship and diagram, with references resolved to names rather than internal ids, so you’re reading a model rather than a file. A Source tab shows the raw bytes. They’re the same bytes Import sends, so what you reviewed is provably what you imported.

The alternative — writing directly and offering an undo — was rejected. Undo is a worse guarantee than “it never happened”, and a review you have to perform after the fact is a review most people skip.

Validated against your metamodel, not just parsed

A generated M1 is checked against the real importer and against the governing metamodel. Element types must exist; relationships must satisfy the constraints the metamodel declares. Failures are fed back to the model for repair, up to three attempts.

This is why a generated model tends to be correct rather than plausible. It isn’t accepted unless it conforms. A chatbot producing JSON has no equivalent check — it produces something that looks like a model, and you find out later.

Why modification rewrites the whole model

Modify M1 doesn’t edit your model in place. It regenerates the entire model with your change applied, then replaces the old one.

That sounds heavy-handed, and it buys two things worth having:

The change is atomic. There’s no half-applied state where three of five renames landed.
The change is reviewable as a diff, because there are two complete versions to compare.

The cost is equally real: the LLM has to faithfully reproduce everything you didn’t ask about. Preservation, not the change itself, is the hard part — which is why Modify M1 is more demanding than generating the same model from scratch, and why it wants a strong model.

The diff is the control that makes this safe. Removals are listed first and in red, because a removal on a request that asked only for additions is precisely the failure this feature exists to surface. Read the removals and you’ve done the review.

And why it won’t touch a metamodel

The Model dropdown lists M1 models only. This is deliberate.

An M1 instance holds a hard reference to the M2 class it’s an instance of. Replacing a metamodel deletes those classes and recreates them as new ones — orphaning every instance built on it.

The damage would land in other packages, which means neither the diff nor the snapshot would show it to you. A safety control that can’t see the failure mode isn’t a safety control. So the task excludes M2 rather than warning about it.

Metamodels are edited directly instead. See How to use the M2 lifecycle.

The snapshot, and refusing to bluff

Before a model is replaced, FarkiBot saves a snapshot of the current version — a .farki file you can import to restore it.

If that save doesn’t happen — you cancel the dialog, or it fails — FarkiBot stops and tells you nothing has been replaced. It does not proceed on the assumption that you probably meant to.

There’s a specific reason this is spelled out. A browser’s file-save API is allowed to report success it cannot actually guarantee, and in some browsers a download that started is all the app can observe. Rather than present a guarantee the platform can’t back, FarkiBot names the limit: in Chrome and Edge it can confirm the write; in Firefox and Safari it can’t, and it says so.

A safety net you believe in but that isn’t there is worse than no safety net.

Why .farki makes this possible

None of this would work with a proprietary binary format.

The .farki format is human-readable JSON that mirrors the model’s logical structure. That makes it something an LLM can genuinely read and write — not through a special API, but because the format is self-describing enough to reason about.

It’s also what makes the review honest. The Source tab shows you the actual file. There’s no translation layer between what you reviewed and what was imported, because there’s nothing to translate.

The format was designed for portability and version control. That it turned out to be an excellent AI interchange format is a benefit of having chosen readability over cleverness.

What this all adds up to

Every FarkiBot decision resolves the same way: prefer the checkable answer over the impressive one.

Decision	The impressive option	What FarkiBot does
Where answers come from	Anything the model knows	Your model, or an admission that it doesn’t say
Where your data goes	Our servers, for convenience	Your browser to your provider, verifiably
Which AI	Ours, bundled	Yours, any of 300+, swappable
Generated content	Written straight in	Staged, validated, reviewed
Modifications	Applied	Diffed, confirmed, snapshotted
Metamodels	Modifiable too	Excluded, because the guard couldn’t see the damage

It’s a slower tool than one that just does what you asked. It’s a tool you can hand results from to someone who will act on them.