Reading diagrams / Topic 1 of 42

What a diagram is

The rule

Yichus reads a program and draws pictures of how it is built. It reads programs written in Bosatsu, a small typed language. The programs in these lessons are Bosatsu copies of well-known programs such as Koa, Redux and SQLite. If you write TypeScript or Python, read a Bosatsu package as a module: one file, with its name on the first line and its imports below it.

Why read the pictures? When an agent writes most of a change, you need to know what it did to the program's shape without reading every line. Did the router start touching the database? Does anything new depend on this package? A diagram answers questions like these in seconds, and it can rule things out, which reading a diff cannot.

Yichus reads only Bosatsu today. It cannot draw these pictures of a TypeScript or Python repository. What carries over is the reading: the same questions apply to any program's structure.

Each picture comes from a lens: one question the tool answers about the code, drawn one way. These lessons start with the layers lens, which answers “what is built from what”.

Everything inside a frame labelled Yichus output is computed from the code. Words outside a frame, like these, are written by people or agents, and nothing checks them. The frame also prints words these lessons have not taught yet, such as direct IO. Each one gets its own lesson.

Each lesson teaches one small rule, shows it worked through twice, then asks you to judge statements until you get them right. Later lessons reuse earlier rules, so each one is short. A statement gets one of three answers: the diagram confirms it, rules it out, or can't tell. The first lessons need only the first two; the third, can't tell, gets its own lesson once you know what the picture does say.

The first rule is about boxes. Here is the start of one Koa source file:

demos/structures/koa/router.bosatsu
package Yichus/Examples/Koa/Router

from Yichus/Examples/Koa/Context import Context, Middleware, tick

In the diagram below, that file is the box labelled Router.

A small copy of the Koa web framework, in five files.

Loading the layer diagram.

A small copy of a Redux todo app, in three files.

Loading the layer diagram.

Loading the worked examples and practice.