docs: architecture.md is outdated and missing coverage for most crates

[ParthSinghPS]

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:

• anvil
• cast
• chisel
• cli-markdown
• common
• debugger
• doc
• fmt
• forge
• linking
• lint
• macros
• primitives
• script
• script-sequence
• sol-macro-gen
• test-utils
• verify
• wallets

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:

1. Which approach do the maintainers prefer (Option A or B)?
2. Are there any crates that are intentionally undocumented or internal-only?
3. Should the descriptions be brief (2–3 sentences) or more detailed
   (covering internal architecture like cheatcodes.md does)?

Happy to take this on once there's clarity on the preferred direction.

[mablr]

Good point 🫡

A significant refactor is currently underway, some effort should be put on this in the coming days/weeks.

We may provide scope and some guidance soon if you want to contribute.

Cc @figtracer @stevencartavia

[figtracer]

Good point 🫡

A significant refactor is currently underway, some effort should be put on this in the coming days/weeks.

We may provide scope and some guidance soon if you want to contribute.

Cc @figtracer @stevencartavia

yeah most docs have to be updated, better to start internally then this should be last step

[ParthSinghPS]

thanks for the context!
could you share which areas are in scope for the refactor? I am currently exploring the codebase so I would love to contribute along the way.

[zerosnacks]

Hi @ParthSinghPS in my opinion it will be higher leverage to improve the quality of https://foundry-rs.github.io/foundry/ and our book https://www.getfoundry.sh/. In my opinion we should just get rid of this outdated documentation. Feel free to propose PRs to incrementally improve this.