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.

▲

tikhonj a day ago | parent | next [-]

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.

	▲	stephen a day ago \| parent \| next [-]
		> 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.
	▲	prabhanjana_c a day ago \| parent \| prev [-]
		I currently use the separate md file to capture the mermaid diagrams about the code, it helps to get overview of the file and various scenarios. It is good to keep all documentation ideally part of the same code. But if documentation is more as part of the code, passion to read source file is reducing, for me. *_learnings.md: I am also using one more _learning.md, that captures what agents learn while building this file. it depends the complexity of the source file. mainly if the source files is about low level, protocols and so on. even separate _learnings.md also helps. so have now. _learnings.md may be needed how much investigation we have done to produce a working protocol.c. protocol.c, protocol.md, protocol_learnings.md

▲

AlarQ 17 hours ago | parent | prev [-]

I get your point @stephen. In such areas, finding balance to not overcomplicate, can be a challenge. The approach I described works for me, though, as I'm focused on closing LLM statistical behavior within deterministic barriers. That's why I highly rely on schema-based ideas.