r/emacs • u/kLeZhAcK • 10h ago
I wrote blueprint.el, a way of documenting software architecture in Org
Disclaimer: an LLM touched the code.
Part of my job is walking into systems nobody remembers anymore and writing down what they are: which components, how they talk, what they do for the business, where they run, what could go wrong. The documents run to a few hundred pages, several people write them at once, and the hard part was never the writing. It was knowing what to write, keeping the whole thing in shape, and being honest about what we hadn't verified yet.
Over the years that became a method, and the method became blueprint.el. It started as a Python script that generated Org files. One day I noticed I was leaving Emacs to run a program that opened, edited and rewrote Org files, which is the one thing Org has done well for twenty years, so I rewrote it in Elisp, on org-element and Org's own exporter, with Transient for the menu. Now the whole document lives where the rest of my work already lives: a master file, one directory per component, plain text in git, open points written in the text and counted, a dashboard in the spirit of Magit.
I'm proud of it, and since it lives inside Emacs I thought some of you might find it interesting. The templates are still in Italian (English is planned) and it isn't on MELPA yet. There's a half-documented demo project in the repository if you want to look around without starting from scratch.
If you try it, I'd like to know what you think.
https://github.com/kLeZ/blueprint.el
The longer story: https://klez.me/en/2026/11/15/blueprint-el/
----
Edit: added the disclaimer at the top.

