Key Concepts

Superpositional has a few core concepts that show up everywhere in the product. Understanding them upfront saves you confusion later.

Repository indexing

When you connect a repository, Superpositional clones it, parses the code using AST (abstract syntax tree) analysis, generates embeddings for semantic search, and stores everything in a hybrid vector + graph store.

The result is three things:

• Entities. Functions, classes, files, modules — the building blocks of your codebase, extracted and stored as structured data.
• Relationships. Which functions call which, what imports what, how modules depend on each other. The graph of connections between entities.
• Embeddings. Vector representations of your code that power semantic search. When you ask a question in plain English, embeddings are how Superpositional finds the relevant code — even if your query doesn't match any exact keywords.

Indexing runs automatically when you first connect a repo and re-runs when code changes. You don't need to trigger it manually (though you can).

Document freshness

Generated docs go stale. A function signature changes, a parameter gets renamed, a module gets restructured — and the docs still describe the old version. Normally you wouldn't notice until someone reads the doc and gets confused.

Superpositional detects this automatically. When docs are generated, structured claims are extracted from them — specific, verifiable statements about the code ("function X takes parameters A and B", "module Y exports class Z"). When code changes, those claims are evaluated against the updated code graph.

If a claim no longer holds, the doc is flagged as stale.

The key detail: this is a structural comparison, not an LLM call. Freshness checks don't burn tokens or cost money per check. They compare the claims against the code graph directly. You get continuous staleness detection without continuous LLM spend.

Flows

A flow is a pipeline run triggered by an event — a push to a branch, a pull request opened, an issue created. Flows are how Superpositional reacts to things happening in your repositories.

Each flow has stages (the individual steps in the pipeline) and a status. You can see flow progress in the dashboard: what triggered it, what stage it's at, whether it succeeded or failed.

Common flow triggers:

• Push. Code was pushed to a branch. Superpositional re-indexes the affected files and checks for drift.
• Pull request. A PR was opened or updated. Superpositional reviews it against the system model — architectural violations, dependency breakage, coding standard violations.
• Issue. An issue was created. Superpositional can investigate it, trace potential root causes, and suggest fixes.

If a flow fails, the dashboard tells you which stage failed and why. You don't need to dig through logs.

Guards

Guards are rules that enforce coding standards across pull requests. You define what matters — naming conventions, architectural boundaries, dependency restrictions, documentation requirements — and guards check every PR against those rules.

When a PR is opened, guards evaluate it. If something violates a rule, it gets flagged with a clear explanation of what's wrong and why it matters. Guards don't just say "this is bad" — they tell you which rule was violated and what the expected behaviour is.

Guards compound over time. As your team defines more rules, the baseline quality of every PR improves. AI-assisted code gets the same scrutiny as hand-written code. Standards don't drift just because the team is moving fast.