Use case

Architecture diagrams for open source projects.

Most first-time contributors give up before opening a pull request, and a surprising share of that is not knowing where anything is.

Download for macOS
v0.1.33 · .dmg · Apple Silicon & Intel
Signed & notarized by Apple · opens without a Gatekeeper warning
sha256 698955a0187bc039f4c74f5d05a9f10fbb27376a45788a0a241d1326b73873c7
Download for Windows instead
$curl -fsSL https://lucidtrain.com/install.sh | sh

The situation

A maintainer knows the codebase completely and cannot see it as a newcomer does. Contributing guides explain how to run the tests and the code of conduct; they rarely explain the shape of the system, because to the person writing them the shape is obvious. The result is issues tagged good-first-issue that nobody picks up.

One diagram in the README

An architecture diagram near the top of the README does more for contribution rates than another paragraph of setup instructions. It lets someone decide whether their change is a two-file change or a redesign before they invest an evening finding out.

Regenerate on release

Contributors will not update the diagram and should not have to. Regenerating at release time is a small maintainer task that keeps it honest, which matters because a wrong architecture diagram is worse than none for someone with no way to check it.

Free for this

The CLI is free and open source, so a maintainer can generate diagrams without a subscription. The desktop app costs $3 a month and is the nicer experience; it is not required to produce the picture for your README.

For the README

shell
$ lucid
# Diagram this project's architecture for a first-time contributor.
# Export to docs/architecture.svg
FAQ

Questions

Is the CLI really free?

Free and open source. The paid product is the desktop app, which adds the Diagram tab UI, the audit and dashboards surfaces, and the command palette.

Where should the diagram go?

In the README, above the setup instructions. Someone deciding whether to contribute reads the top of the README and rarely reaches CONTRIBUTING.md.

How detailed should it be?

Enough to orient, not enough to be a specification. Ten to fifteen boxes, at the level of what talks to what, which is what a contributor needs to place their change.

Related