Waymark

Waymark turns any GitLab repo into a plain-language map of how the code fits together and shows reviewers what a merge request might break

Comment

Waymark turns any GitLab repo into a simple map. Each part gets a plain label like Front door, Logic, Data or Tests, plus one sentence on what it does. You can click a part to see what it uses and what uses it. You can also follow a step-by-step tour, like “what happens when someone sends a package.” On a merge request, a GitLab Duo agent uses the same map to show what the change touches and what might break. It runs the tests and posts a short summary for the reviewer. Waymark can also save a tour as a Replay, an image that plays by itself in a README.

Try it live (Google Cloud Run)

Both run on Google Cloud Run. The app is the Waymark viewer: paste a public GitLab link and get a plain map of the code. The API is a small Node service that asks Gemini to explain the repo in plain words and write guided tours. Its Gemini key lives in Google Secret Manager. It only answers the Waymark app and limits how many explanations each visitor gets.

See it running in GitLab

Inspiration

Reviewing a merge request in a repo you don't know is slow. The diff shows the lines that changed, but not what those lines feed into. Most of a reviewer's time goes into clicking through imports to answer one question: what else could this break?

We wanted a map of the code you can read in a minute, and an agent that brings that map to every merge request.

What it does

Paste a GitLab link. See how the code fits together. Waymark reads a public GitLab repo and draws its main parts as boxes. Each box gets a plain label (Front door, Logic, Data, Helper, Screen, Tests) and one sentence on what it does.

  • Click a box to see what it uses and what uses it. Double-click to look inside.
  • Take a tour: press play and Waymark walks you through how a module works, step by step.
  • Check a change: paste a merge request link and see the changed files plus everything that depends on them.
  • Replay: save any tour as one animated SVG (no scripts) that plays by itself in a GitLab README or MR comment.
  • Download the whole map as one HTML file that works offline.

In GitLab, a Duo agent does the review legwork. Mention the Waymark change review flow on a merge request and it:

  1. reads the MR and checks it is looking at the right commit,
  2. runs Waymark's mapper to trace the changed files and what depends on them,
  3. runs the tests and the build, and records the real exit codes,
  4. writes plain-English explanations that are checked against the map,
  5. posts one review note: what changed, what might break (with file and line evidence), what the tests actually showed, and regression tests worth adding.

It never merges, pushes, or deploys. The reviewer approves the outcome.

Every merge request pipeline also runs the tests, GitLab SAST and secret detection (findings show up on the map and in the change report), writes a change report and a Replay, estimates their carbon with CO2.js, builds the app, and publishes it to GitLab Pages. The app and its Gemini API are also live on Google Cloud Run (links above).

How we built it

  • Plain JavaScript on Node 22, no framework and no runtime dependencies. src/engine.js reads import lines in JavaScript, TypeScript, and Python and builds folders → files → functions.
  • Structure from code, words from AI. Arrows come only from real import lines, never from a model. Gemini (in the app) and Duo (in the flow) only write the words: a summary, one sentence per part, and 2–4 tours. A tour is kept only if every step follows a real import, and every file and line the AI points to is checked against the code. Anything that doesn't match is dropped.
  • Replay (src/replay.js) turns a tour into a single self-playing SVG that uses CSS animation only, so it survives GitLab's sanitized Markdown.
  • CI/CD (.gitlab-ci.yml): verify → SAST → secret detection → map, change report, and Replay → footprint → package → Pages.
  • Duo Agent Platform (.gitlab/duo/flows/waymark.yml + agent-config.yml): a custom flow with a Mention trigger and a small toolset (read files, run commands, read MR diffs, post an MR note).
  • Google Cloud Run (scripts/deploy-cloud-run.sh, deploy/cloud-run/, deploy/cloud-run-api/): one script deploys two services. Cloud Build packages an Nginx container for the app and a Node container for the Gemini API, which reads its key from Secret Manager. Both scale to zero.

Challenges we ran into

  • Making AI output trustworthy. Early on, the model would happily invent connections between files. We flipped it around: the code decides the structure, the AI only labels it, and every claim gets validated.
  • Running Duo in a real account. Custom flows weren't available on a personal namespace, so we moved the project into a group with Duo enabled. GitLab's flow schema rejected a field (max_cycles), and the Duo sandbox pointed TMPDIR at a folder that didn't exist, which made 31 tests fail for the wrong reason. We fixed it by having npm test create the temp folder before the tests run.
  • Getting animation into a merge request. GitLab strips scripts, so Replay had to be pure SVG and CSS.
  • Keeping the words simple. Every label went through rounds of cutting jargon so someone new to the repo can follow it.

What we learned

  • An agent is far more useful when it works from a fixed, checkable artifact (the map) and has to report real command results instead of guesses.
  • "Show me what this touches" is the question reviewers actually need answered, and a picture answers it faster than a list.
  • A small, dependency-free app is easier to run everywhere: locally, in CI, on GitLab Pages, and on Cloud Run.

What's next

  • Run the review automatically on every new merge request (it is mention-only today to save Duo credits).
  • More languages (Go, Java, Ruby).
  • Private repos through a GitLab token.

Built With

Share this project:

Updates

Submission history