Comment by stephen
7 hours ago
I've also been a little-d DDD fan, and we've had luck with per-entity `md` files to language-independent document domain behavior/quirks/usages.
I.e. an `Author.ts` has an `Author.md`, `Book.ts` has an `Book.md`.
For agents, we've given them a skill to read & write the `md` files:
https://github.com/joist-orm/joist-orm/blob/main/packages/co...
And so agent-written `md` updates are showing up in PRs. So far it seems useful (our main repo is a 350k LOC TypeScript monolith).
Admittedly, this is way less sophisticated (& less complicated) than the "graph of edges in/out of every bounded context" in the OP, but that is probably again my "little-d" DDD perference, where I find some of "DDD at scale" patterns lead to, imo, over-engineering.
Why not put the content from the md file in the code as documentation?
Ideally, the code can actually help you structure that information. I've written a bunch of Haskell and OCaml like this, where the types in each module let me structure my documentation in a way that is actually easier for people—and maybe also LLMs—to track. As a bonus, it makes it more natural to keep the two in sync.
> why not put the content from the md file in the code
We do that :-)
https://joist-orm.io/modeling/documentation/#two-way-syncing
Technically the md file can have more free-form docs, but for the overview/fields headers that, by convention, map to the entity/field jsdocs, we do sync them over.