Organizing Diagram Files

ASCII Diagram does not require one fixed project layout, but some patterns make long-term maintenance much easier.

Recommended default

For many repos, this is a good starting point:

my-project/
  README.md
  docs/
    diagrams/
      system-context.asciid
      request-flow.asciid
      deployment.asciid

Why this works:

• diagrams live beside docs
• filenames reflect the concept, not the tool
• source files are easy to find in Git

Keep one file per diagram

ASCII Diagram is designed around standalone documents.

As a rule of thumb:

• keep one conceptual diagram per .asciid file
• prefer meaningful filenames over dates
• split a diagram when the concept changes, not just when it grows

Name files after the thing they explain

Good examples:

• system-context.asciid
• ingest-pipeline.asciid
• worker-lifecycle.asciid
• auth-request-flow.asciid

Less useful examples:

• diagram-1.asciid
• new-flow-final-final.asciid

Keep rendered ASCII as output, not the only source

If you paste rendered ASCII into a README or issue, keep the .asciid file somewhere stable too.

That way:

• the pasted text is easy to read
• the source remains editable
• future revisions do not require redrawing from scratch

Organization patterns

By docs section

docs/
  diagrams/
    architecture/
    api/
    operations/

This works well when documentation already drives the project structure.

By code area

services/
  billing/
    diagrams/
  auth/
    diagrams/

This works well when diagrams are tightly coupled to specific parts of the codebase.

By decision record

docs/
  adr/
    0012-cache-design.md
    diagrams/
      0012-cache-design.asciid

This works well when diagrams support architecture decisions and should travel with them.

Suggested rules

• keep filenames stable
• commit diagram source with the docs or code it explains
• avoid storing only screenshots
• treat rendered ASCII as a projection of the source file
• prefer layouts that future contributors can discover quickly