Skip to main content
Unfoldnbaglivo/unfold-test
decided4/7/2026

ADR-0002: Unfold Engine and Unfold Lens communication

Context

Unfold is composed of two internal services: Unfold Engine, which derives the architecture graph from ADRs, and Unfold Lens, which visualizes it. We need to define how these two services relate to each other and how data flows between them.

Decision

Unfold Engine and Unfold Lens do not communicate directly. The JSON graph file (architecture.json) committed to the user's repository is the contract between them. Engine writes it, Lens reads it.

Unfold Engine

  • Internal service
  • Hono (Node.js) on Railway
  • Triggered by GitHub webhook on push to the ADR repository
  • Produces architecture.json and opens a PR on the user's repository

Unfold Lens

  • Internal service
  • Next.js on Vercel
  • Reads architecture.json from the user's repository via raw GitHub URL
  • Renders the visual graph — no direct dependency on Engine at runtime

The connection between them is a one-way data flow over GitHub: Engine writes, Lens reads.

Consequences

  • There is no API between Engine and Lens — architecture.json is the interface
  • Lens can be pointed at any valid architecture.json, regardless of how it was produced
  • Engine and Lens can be deployed, updated, and scaled independently