Example
Documented architectures
Some maintainers draw their own software and write down the rules its modules follow. Each program below copies one of those projects into a small Bosatsu program: the same module names, the same imports, bodies cut down until they still run. The diagram under each one is what the layers lens draws from the compiled program alone. Some of the programs also declare the maintainers' groups in a package that holds nothing else. The layers lens does not draw a package that only declares, uses nothing in the program and is imported by nothing; the structure picture further down checks those groups against the program. Compare each diagram with the maintainers' own picture.
Each diagram opens as tiles in rows, where a package sits above what it is built from; switch to boxes and arrows to see the imports. An arrow means a package imports another. It is solid when the package refers to the other's definitions and dashed when it names only its types, which is how a port or a shared data model shows up; select a package for the counts.
An import says a package depends on another, not what it does with it. Under some of the diagrams is a second picture, from the structure lens, drawn from where each value in the program comes from and goes, and from its types, within the edges the compiled program shows: a call whose result is dropped reads as dropped, and a record of functions handed in reads differently from one a function reaches for by name. A value that comes in as the parameter of a function written inline is not followed to whoever applies that function.
SQLite: a tall stack
SQLite's architecture page draws a stack from the C interface through the tokenizer, parser and code generator to the virtual machine, then the B-tree, the pager and the OS interface. The pager reaches files only through the VFS, a record of operations, so the arrow from the pager to the OS layer names types and calls nothing. The page draws the compiler as a column beside the core; the diagram stacks it on top, because the code generator builds virtual machine programs.
Loading the SQLite layer diagram.
The VFS is a record of functions. The Unix VFS fills it and only
sqlite3_open picks it; the pager gets it handed in. Pages
and cells are found by a plain integer key. The
program also declares the page's groups, with the compiler beside the
core: the compiler hands the core the programs it writes, as types
alone, and never touches the backend.
Loading the SQLite structure picture.
Code & run Parse a statement
rust-analyzer: one door into the compiler
rust-analyzer's architecture guide
says the IDE crates reach the compiler's internals, hir_def
and hir_ty, only through hir, a facade with an
object-oriented API. In the diagram nothing above Hir has
an arrow into either of them.
Loading the rust-analyzer layer diagram.
The program declares the guide's crate groups and which group may
use which. Only hir may use the internals, and every use
of them comes from hir. An IDE crate that imported a
hir_def type would show up here as divergent.
Loading the rust-analyzer structure picture.
Code & run Parse two lines
TypeScript: phases over shared types
The TypeScript architectural overview
describes a pipeline: the scanner and parser make a syntax tree, the
binder makes symbols, the checker makes types and diagnostics, the
emitter writes output. Every phase is written in the data types of
types.ts. The diagram shows that hub at the bottom with an
arrow from every phase; it does not show the order of the pipeline.
Loading the TypeScript layer diagram.
The order is in the signatures. Each phase makes a type of
types.ts that a later one takes, and listing them that way
gives the overview's pipeline.
Loading the TypeScript structure picture.
Code & run Scan a statement
An allocation service: ports and a composition root
Architecture Patterns with Python
by Harry Percival and Bob Gregory builds a service whose handlers talk
to a repository and a notifier through abstract ports, and only the
bootstrap module picks the real adapters. Select Handlers
and Bootstrap: the handlers name the ports' types, and only
the bootstrap calls the adapters.
Loading the allocation service layer diagram.
The handlers reach storage through the repository they are handed, so a test can hand them the in-memory one. Bootstrap is the only place an adapter is named.
Loading the allocation service structure picture.
The system map shows the same thing from the handlers' side. Each handler's calls run out to the port it is handed. The box on the right lists each port's adapters and who picks them.
Loading the allocation service system map.
Code & run Allocate an order line
The same service, storage reached for
The book's early chapters get a database session where it is used.
This version of the service works that way: each handler gets its
repository from repository() or names the adapter itself.
The imports look much the same as before; the picture of where each
record comes from does not.
Loading the structure picture.
On the system map, the mark under each handler's line shows where it builds its own repository.
Loading the system map.
Code & run Allocate an order line
Redux: slice reducers from one helper
The Redux guide to splitting reducer logic
builds each slice reducer with a createReducer helper from
a table of case functions, then combines the slices into one root. The
program declares that both slice reducers share create_reducer,
and the abstractions lens checks it.
Loading the Redux layer diagram.
Put together as a tree, the store is the root reducer, the root
reducer puts what the two slice reducers return into the state, and
each slice reducer is create_reducer handed its case
functions. Both slice reducers return what create_reducer builds,
unchanged. A slice that called it and then dropped the result would
read "drops it" here, and the declared check would fail. The line under
create_reducer comes from its type: it is generic over the
state and the action, so it can only route them to the case functions
it was handed, never look inside one.
Loading the Redux structure picture.
The system map draws the same tree inside the program, with the code that imports it calling in from the left.
Loading the Redux system map.
Code & run Dispatch actions to the store
Koa: an onion of middleware
Koa builds an app from middleware composed by koa-compose: each one does some work, calls the next, and does more work on the way back. The router is written against the context alone. The layer diagram shows that; the order of the middleware, which is what makes this Koa, is not an import.
Loading the Koa layer diagram.
Each middleware hands the context to next and works on
what comes back, and the app adds them one at a time in a fixed order.
Only response_time joins what comes back with the context
as it was handed in: it reads the clock before next and
uses it after, which is the onion. Nothing in the Middleware
type says a middleware has to call next: it is a bare
function type. The router finds a route by comparing the method and
URL it is handed, both plain strings, so no type ties a route to the
requests it answers.
Loading the Koa structure picture.
The system map draws the app as one line through its middleware, in the order the app adds them.
Loading the Koa system map.
Code & run Send a request through the middleware
VS Code: layers and contributions
The VS Code source organization
page names layers, base, platform,
editor and workbench, and features that
contribute to the workbench. A contribution never imports another
contribution; when two features meet, one uses the other's
common API. Only the main entry loads contributions.
Loading the VS Code layer diagram.
Each feature is declared as two groups, its common API
and its contribution, and only the main entry may use a contribution.
The source control contribution uses the search feature's
common API and nothing else of it. A command is found by
comparing its id, a plain string, so no type ties an id to its command.
Loading the VS Code structure picture.
Code & run Search an open file
What the diagrams leave out
Rules about groups of packages, such as "contributions meet only
through common", are what tools like
import-linter,
ArchUnit and
dependency-cruiser
check. The group pictures above use the outcomes of the reflexion model
of Murphy, Notkin and Sullivan: convergent, divergent and absent. A
group rule says which packages may use which. It does not say what a
use does with what it gets. Where a picture cannot tell a project's
story, the story is often not in the types. The structure pictures list
each choice made by comparing a plain string or integer handed in, such
as VS Code's command ids and SQLite's page numbers, because no type
says what those keys pick.
Where this fits
What this is about: Lenses and diagrams