docs: architecture.md is outdated and missing coverage for most crates #13880
Description
Problem
The docs/dev/architecture.md file currently only documents three crates:
evm/config/cli/
However, the repository has grown significantly and now contains 20+ crates,
the majority of which have no architectural documentation at all.
The following crates present in crates/ are completely undocumented
in architecture.md:
anvilcastchiselcli-markdowncommondebuggerdocfmtforgelinkinglintmacrosprimitivesscriptscript-sequencesol-macro-gentest-utilsverifywallets
The docs/dev/README.md itself acknowledges this with the note:
Note: This is incomplete and possibly outdated
Here is the current state of architecture.md:
This makes it significantly harder for new contributors to understand
the codebase structure and know where to look when working on a feature
or bug fix.
Proposed Solution
I propose that we expand the architecture.md to include a short description of
every crate in the workspace which will cover its purpose, what it depends on, and which
other crates depend on it.
This can be done by either including every explanation in the architecture.md itself or creating individual
<crate-name>.md files under docs/dev/
for crates that need more detailed explanation (similar to how cheatcodes.md
exists as its own file), and keep architecture.md as a high-level index
that links to them.
I am happy to work on this. Before doing so, I wanted to confirm:
- Which approach do the maintainers prefer (Option A or B)?
- Are there any crates that are intentionally undocumented or internal-only?
- Should the descriptions be brief (2–3 sentences) or more detailed
(covering internal architecture likecheatcodes.mddoes)?
Happy to take this on once there's clarity on the preferred direction.