Guide for contributors (and editor tooling) on where files belong in the JuliaFEM.jl tree. Read this together with [`AGENTS.md`](https://github.com/JuliaFEM/JuliaFEM.jl/blob/master/AGENTS.md) (architecture and invariants) and [`src/README.md`](https://github.com/JuliaFEM/JuliaFEM.jl/blob/master/src/README.md) (per-module overview).
Last updated: 2026-05-09.
---
## Organisational philosophy
Prefer subdirectories over flat structures.
When several files deal with the same topic, group them into a topic subdirectory:
- The subdirectory has its own `README.md` describing purpose and status.
- Related files stay together.
- An optional `Project.toml` keeps extra dependencies local instead of growing the main package manifest.
Examples:
-`src/materials/` for material models.
-`test/materials/` for matching tests.
-`benchmarks/regression/` for CI regression benchmarks and reports.
-`benchmarks/analysis/` for exploratory or architecture benchmarks.
Avoid flat directories with dozens of unrelated files.
└── solvers/ # Reserved; see README there if present
```
Rules:
- Mirror `src/` where practical: tests for `src/foo/bar.jl` belong under `test/foo/`.
- Topic folders may include a `README.md` for scope and conventions.
- Test files: prefer `test_<feature>.jl`.
- Long-form comparison or verification methodology can live in topic `README.md` files; timestamp machine-generated reports as `reports/YYYY-MM-DD_HHMMSS_name.txt` under the relevant folder when you add them.
- Avoid dropping loose session write-ups under `test/`; use a gitignored notes area or a dated report path as above.
---
## Examples, demos, benchmarks
Some clones use optional top-level folders:
```text
examples/ # Full programs for users (often one subdirectory per example)
├── repository_layout.md # This guide (built into the manual)
├── developer/
│ └── architecture_layers.md
└── snippets/ # Executable snippets for Documenter pages
```
The high-level architecture narrative lives in the repository root [`AGENTS.md`](https://github.com/JuliaFEM/JuliaFEM.jl/blob/master/AGENTS.md). `docs/src/api.md` is generated from docstrings and exports.
What belongs in `docs/`:
- Documenter sources for the published manual (pages listed in `docs/make.jl`).
- Logo assets and docs-specific `Project.toml`.
- Contributor-facing notes such as `CONTRIBUTING.md`.
- This layout guide (`docs/src/repository_layout.md`) plus the short pointer `docs/repository_layout.md`.
What does not:
- Per-module developer notes that belong next to code: use `src/<topic>/README.md` instead.
- Large generated logs or scratch files: keep them out of `docs/src/` or timestamp under a dedicated reports location.
---
## Experimental and disposable paths
```text
prototypes/ # Gitignored in normal setups: experiments by topic
.trash/ # Gitignored: pending deletion or scratch outputs
```
Rules:
- Use `prototypes/` for spike code you might promote into `src/` or delete.
- Use `.trash/` for short-lived files; delete once obsolete.
---
## Gitignored local notes (`llm/`)
Many developer setups keep a **local-only**, gitignored `llm/` tree for dated session logs and drafts. Nothing under `llm/` should be committed. If your checkout does not use it, you can ignore this section.
Naming convention when present: `llm/sessions/YYYY-MM-DD-topic.md` (lowercase, datestamped).
---
## Scripts
```text
scripts/
├── README.md
└── *.jl / *.sh # Dev tooling, CI helpers, mesh utilities (not package code)
```
Rules:
- Scripts are not loaded by `using JuliaFEM`; they are run explicitly.
