How it works

Orbit

AI testing platform. Point it at a GitHub repo and it tests the app for you: riskiest journeys first, in a real browser, with what broke explained in plain English.

Live · in developmentVisit the site ↗

Fig.An AI tester for small teams that ship fast: connect a repo and it tests the app the way a person would.

Architecture

  1. AClients· 3Dashboard · GitHub · Claude
    • DashboardNext.js · live mapUI

      UI · Next.js · live map

      Projects, the system map, plans, runs with replays and failure analysis, and a chat panel.

      Talks to

      • → API routes (HTTPS)
      • ← Live stream (live)
    • GitHubOAuth · App · webhooksEXTERNAL

      EXTERNAL · OAuth · App · webhooks

      Sign-in, repo access through an installed App, webhooks on changes, and checks and comments back on pull requests.

      Talks to

      • → API routes (webhooks)
      • ← Reporter (PR check)
    • ClaudeMCP clientEXTERNAL

      EXTERNAL · MCP client

      Trigger runs, read the system map, plans and results, and search failures from Claude.

      Talks to

      • → MCP server (MCP)
  2. BAPI· 4API routes · Live stream · Orchestrator · MCP server
    • API routesNextAuth · RESTSERVICE

      SERVICE · NextAuth · REST

      Workspaces, projects, plans and runs, plus the webhook receivers for GitHub, Linear, Slack and billing.

      Talks to

      • ← Dashboard (HTTPS)
      • ← GitHub (webhooks)
      • → indexing (enqueue)
    • Live streamSSE · pub/subREALTIME

      REALTIME · SSE · pub/sub

      Streams indexing progress, run events and browser screenshots to the dashboard as they happen.

      Talks to

      • ← Executor (screenshots)
      • → Dashboard (live)
    • Orchestratorbudgets · contextSERVICE

      SERVICE · budgets · context

      Coordinates the agents through a run: token budgets per agent, and context picked by similarity rather than sent whole.

      Talks to

      • → execution (run)
      • ← scheduler (schedule)
      • ← MCP server (trigger)
    • MCP server7 toolsAI

      AI · 7 tools

      Run, map, plan, results, health, failure search and a code audit, over MCP.

      Talks to

      • ← Claude (MCP)
      • → Orchestrator (trigger)
  3. CQueues· 4indexing · execution · reporting · scheduler
    • indexingBullMQQUEUE

      QUEUE · BullMQ

      Jobs to clone and index a repo.

      Talks to

      • ← API routes (enqueue)
      • → Analyst (worker)
    • executionBullMQQUEUE

      QUEUE · BullMQ

      Jobs to run test cases in a browser.

      Talks to

      • ← Orchestrator (run)
      • → Executor (worker)
    • reportingBullMQQUEUE

      QUEUE · BullMQ

      Jobs to analyse results and send reports.

      Talks to

      • ← Executor (results)
      • → Reporter (worker)
    • schedulerBullMQQUEUE

      QUEUE · BullMQ

      Recurring runs on a schedule.

      Talks to

      • → Orchestrator (schedule)
  4. DAgents· 7Analyst · Planner · Executor · Reporter · Indexer · Prioritiser · Self-healer
    • Analystsystem mapAI

      AI · system map

      Turns a repo into a system map: framework, routes, components and their links.

      Talks to

      • ← indexing (worker)
      • → Indexer
      • → Planner (system map)
    • Plannerjourneys · casesAI

      AI · journeys · cases

      Rebuilds user journeys from the map, finds coverage gaps and writes test cases. Plans are cached.

      Talks to

      • ← Analyst (system map)
      • → Prioritiser
      • → Claude · GPT (plan)
    • Executorruns · evidenceAI

      AI · runs · evidence

      Drives a real browser step by step, classifies each failure, and captures screenshots, video and DOM snapshots.

      Talks to

      • ← execution (worker)
      • → Playwright · Stagehand (CDP)
      • → Self-healer
      • → Object storage (evidence)
      • → Live stream (screenshots)
      • → reporting (results)
    • Reporterplain EnglishAI

      AI · plain English

      Explains failures, spots patterns across runs, and files them where the team works.

      Talks to

      • ← reporting (worker)
      • → GitHub (PR check)
      • → Linear · Slack
    • Indexertree-sitter · regex fallbackSERVICE

      SERVICE · tree-sitter · regex fallback

      Parses source with tree-sitter, falls back to patterns when it can’t, detects the framework, and indexes incrementally.

      Talks to

      • ← Analyst
      • → PostgreSQL (map · embeddings)
    • Prioritiser40 · 35 · 25SERVICE

      SERVICE · 40 · 35 · 25

      Scores each case on criticality (40%), risk (35%) and coverage gap (25%), and boosts journeys like sign-in and checkout.

      Talks to

      • ← Planner
    • Self-healerselector memorySERVICE

      SERVICE · selector memory

      Finds a moved element by stored fix, text, label or role before asking a model, and saves what worked.

      Talks to

      • ← Executor
      • → PostgreSQL (saved fixes)
  5. EData· 3PostgreSQL · Redis · Object storage
    • PostgreSQLpgvectorSTORE

      STORE · pgvector

      Projects, maps, plans, runs and healed selectors, with embeddings for retrieval.

      Talks to

      • ← Indexer (map · embeddings)
      • ← Self-healer (saved fixes)
    • Redisqueues · pub/subSTORE

      STORE · queues · pub/sub

      Backs the job queues, rate limits and live events.

    • Object storageS3 / R2STORE

      STORE · S3 / R2

      Screenshots, videos and DOM snapshots from every run.

      Talks to

      • ← Executor (evidence)
  6. FOutside· 3Claude · GPT · Playwright · Stagehand · Linear · Slack
    • Claude · GPTrouted by taskEXTERNAL

      EXTERNAL · routed by task

      Different models for mapping, planning, running and reporting, chosen per task.

      Talks to

      • ← Planner (plan)
    • Playwright · Stagehandremote CDPEXTERNAL

      EXTERNAL · remote CDP

      A real headless browser over CDP, or a cloud browser when configured.

      Talks to

      • ← Executor (CDP)
    • Linear · Slackissues · alertsEXTERNAL

      EXTERNAL · issues · alerts

      Where failures become issues and alerts.

      Talks to

      • ← Reporter
Connections · 24

→ request · ⇢ webhook, queue or schedule

  1. Dashboard → API routes · HTTPS
  2. GitHub ⇢ API routes · webhooks
  3. API routes ⇢ indexing · enqueue
  4. indexing ⇢ Analyst · worker
  5. Analyst → Indexer
  6. Indexer → PostgreSQL · map · embeddings
  7. Analyst → Planner · system map
  8. Planner → Prioritiser
  9. Planner → Claude · GPT · plan
  10. Orchestrator ⇢ execution · run
  11. scheduler ⇢ Orchestrator · schedule
  12. execution ⇢ Executor · worker
  13. Executor → Playwright · Stagehand · CDP
  14. Executor → Self-healer
  15. Self-healer → PostgreSQL · saved fixes
  16. Executor → Object storage · evidence
  17. Executor ⇢ Live stream · screenshots
  18. Live stream ⇢ Dashboard · live
  19. Executor ⇢ reporting · results
  20. reporting ⇢ Reporter · worker
  21. Reporter → GitHub · PR check
  22. Reporter → Linear · Slack
  23. Claude → MCP server · MCP
  24. MCP server → Orchestrator · trigger

Inside: the executor and self-healing

Real apps change under their tests. The executor checks it’s allowed to run, orders tests by what they depend on, and when a button has moved it climbs a ladder of cheap fixes before it ever asks a model, then remembers the answer.

  1. ABefore· 4Environment check · Dependency order · Auth reuse · API tests
    • Environment checknever productionSERVICE

      SERVICE · never production

      Refuses production environments outright, checks the target is reachable, and decrypts the test credentials.

      Talks to

      • → Dependency order
    • Dependency orderparallel groupsSERVICE

      SERVICE · parallel groups

      Sorts tests by their prerequisites into groups that run in parallel, one group after another, breaking any cycles first.

      Talks to

      • ← Environment check
      • → Auth reuse
      • → API tests (contracts)
    • Auth reuseskip repeat loginsSERVICE

      SERVICE · skip repeat logins

      Once signed in, later tests skip their opening login steps. Tests of the login itself always start fresh.

      Talks to

      • ← Dependency order
      • → Step executor
    • API testsplain HTTPSERVICE

      SERVICE · plain HTTP

      Contract tests run without a browser or a model loop, falling back to the browser when they need the UI.

      Talks to

      • ← Dependency order (contracts)
  2. BRun· 3Step executor · Browser · Provider guard
    • Step executorone step at a timeAI

      AI · one step at a time

      Acts on the page step by step and classifies any failure: missing element, not clickable, timeout, wrong assertion, wrong page.

      Talks to

      • ← Auth reuse
      • ← Provider guard (abort)
      • → Browser (act)
      • → Stored fix (broken selector)
      • → Flaky registry (retries)
      • → Baselines (on pass)
      • → Evidence
    • BrowserPlaywright · StagehandEXTERNAL

      EXTERNAL · Playwright · Stagehand

      A real browser over CDP, with Stagehand’s element and prompt caching when it is used.

      Talks to

      • ← Step executor (act)
    • Provider guardstop, don’t pile upSERVICE

      SERVICE · stop, don’t pile up

      If the AI provider fails on billing, auth or quota, the run stops rather than recording a false failure for every remaining test.

      Talks to

      • → Step executor (abort)
  3. CHeal· 5Stored fix · Visible text · Label · Role · Model
    • Stored fixapproved firstSERVICE

      SERVICE · approved first

      A fix that worked before for this selector, approved ones first, then others above 0.85 confidence.

      Talks to

      • ← Step executor (broken selector)
      • → Visible text (miss)
    • Visible textheuristicSERVICE

      SERVICE · heuristic

      Finds the element by the words on it.

      Talks to

      • ← Stored fix (miss)
      • → Label (miss)
    • Labelaria-labelSERVICE

      SERVICE · aria-label

      Finds it by its accessible label.

      Talks to

      • ← Visible text (miss)
      • → Role (miss)
    • Rolerole-basedSERVICE

      SERVICE · role-based

      Finds it by what it is: a button, a link, a field.

      Talks to

      • ← Label (miss)
      • → Model (miss)
    • Modelselector sub-agentAI

      AI · selector sub-agent

      Last resort: a model reads the page’s interactive elements and the selectors that failed, and proposes a new one.

      Talks to

      • ← Role (miss)
      • → Selector memory (saved)
  4. DAfter· 4Selector memory · Flaky registry · Baselines · Evidence
    • Selector memorysaved fixesSTORE

      STORE · saved fixes

      Every heal is stored with its strategy and confidence, so the next run starts from it.

      Talks to

      • ← Model (saved)
    • Flaky registryquarantineSERVICE

      SERVICE · quarantine

      A test that fails then passes with no code change is flaky, not broken; after five such flips with under half its recent runs passing, it is quarantined.

      Talks to

      • ← Step executor (retries)
    • Baselinesscreens · API shapesSTORE

      STORE · screens · API shapes

      After a passing run, screenshots and API response shapes are kept to compare the next run against.

      Talks to

      • ← Step executor (on pass)
    • Evidencescreens · video · DOMSTORE

      STORE · screens · video · DOM

      Everything a person needs to see what happened, kept per step.

      Talks to

      • ← Step executor
Connections · 15

→ request · ⇢ webhook, queue or schedule

  1. Environment check → Dependency order
  2. Dependency order → Auth reuse
  3. Dependency order → API tests · contracts
  4. Auth reuse → Step executor
  5. Provider guard → Step executor · abort
  6. Step executor → Browser · act
  7. Step executor → Stored fix · broken selector
  8. Stored fix → Visible text · miss
  9. Visible text → Label · miss
  10. Label → Role · miss
  11. Role → Model · miss
  12. Model → Selector memory · saved
  13. Step executor → Flaky registry · retries
  14. Step executor → Baselines · on pass
  15. Step executor → Evidence

Two flows

Testing your app

Walk through it and each step lights the parts it runs through in the drawings above.

By count

agents: analyst, planner, executor, reporter
4
actions Claude can take in it
7

Notes

  1. N.1When a button moves, Orbit tries the cheap ways to find it first: its text, its label, its role. It only asks a model as a last resort, and it remembers the answer.
  2. N.2It can break things on purpose, like a dropped request or a slow server, to see how the app copes.

Built by

I design, architect and build software products like this one.

naram@hey.com·See the rest of my work

More systems