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