Yichus

Idea

Project / Lenses and diagrams

See how a program is organized.

To understand a large codebase, you need to see its building blocks, which abstractions are reused, and where definitions depart from the conventions used elsewhere. Those relationships can be hard to follow across many files.

Usually you learn this from a tour by someone who knows the code well, then build your own picture over months of working in it.

For programs written in the typed functional language Bosatsu, Yichus draws these structures from the compiled source. Use the maps to get to know a codebase, to keep as a reference while you work, and to check that an agent is building in a pattern you like, so you can tell it to change course when it isn’t.

Separation of concerns

The author groups and places real definitions; the compiler supplies their relationships. Select a region to highlight its connections, or a definition to inspect the source.

Compare Forum’s original program with a shared-fields refactor, and switch the arrangement independently. Layout changes the picture; extraction changes what the code shares.

Loading the compiled example and its authored layout…

Edit this diagram’s composition

Change region names, descriptions, member order, emphasis, initial expansion and grid positions. Rows and columns start at zero; span covers adjacent columns. Every definition belongs to exactly one region. A context region is listed below the picture, with all crossing relationships preserved. These are author choices, not claims proved by the compiler.

Apply checks the layout against this source snapshot. Download saves the JSON for version control. To change the program itself, open the workbench below. Layout format and examples →

Compiled source and evidence
Edit and check this program in the workbench →

Here is Icetakes, a community reading site built with Yichus, as a layer diagram. Its packages judge submitted articles with the help of a “lawyer” model, which is why so many names start with Lawyer. Each box is a package, and each arrow points to a package it is built from. The diagram places each dependency below the packages that use it. What differs between programs is how far the arrows reach and where direct IO operations sit.

Try itTap a package to see what it uses, what uses it, and which tables it reads and writes.

Loading the Icetakes layer diagram. Read about the lenses.

Inside one package

The forum app on this site is a single package. Building blocks arranges definitions by their dependencies. Most reused highlights definitions that many others use. Recurring shapes groups definitions with similar types so you can compare how they are written.

Try itTap a definition, then switch tabs to see it from another side.

Loading the forum’s lenses. Read about the lenses.

Checking an agent’s work

Lenses also show when an agent copies logic instead of reusing it. In this shop, cart, checkout, and support each work out how much stock can be sold.

Try itPress After the fix to see the program once the copies share one definition.

Loading the recorded dependency map. Read the stock-rule example.

Code & run Edit the stock logic and redraw the map
Map a larger program More maps and what they show →

Inspect larger programs and compare refactors

The program-structure workbench lets you expand groups and follow references in a larger example. The worked examples explain which facts each view can show and how those facts stay tied to the source.

A dependency arrow says that one definition refers to another. It does not establish execution order or prove that a permission check runs. Use a view matched to the question you are asking.

Follow a complete refactor →Read the lens guide →How the diagrams stay tied to the source →

All Yichus projects · Work with your agent

Where this fits

See it

Do it