docs: Add project structure map for contributors

README.md

@@ -22,7 +22,8 @@ It can be run:
 * For the entire repository or just for change-related files (e.g., local git stash, last commit, or all changes in a Pull Request)
 
 Want to contribute?
-Check [open issues](https://github.com/antonbabenko/pre-commit-terraform/issues?q=label%3A%22good+first+issue%22+is%3Aopen+sort%3Aupdated-desc)
+Check [open issues](https://github.com/antonbabenko/pre-commit-terraform/issues?q=label%3A%22good+first+issue%22+is%3Aopen+sort%3Aupdated-desc),
+[project structure](docs/project_structure.md),
 and [contributing notes](/.github/CONTRIBUTING.md).
 
 [Latest Github tag]: https://img.shields.io/github/tag/antonbabenko/pre-commit-terraform.svg
@@ -42,6 +43,7 @@ If you want to support the development of `pre-commit-terraform` and [many other
 
 * [Sponsors](#sponsors)
 * [Table of content](#table-of-content)
+* [Project structure](#project-structure)
 * [How to install](#how-to-install)
   * [1. Install dependencies](#1-install-dependencies)
     * [1.1 Custom Terraform binaries and OpenTofu support](#11-custom-terraform-binaries-and-opentofu-support)
@@ -85,6 +87,10 @@ If you want to support the development of `pre-commit-terraform` and [many other
 * [License](#license)
   * [Additional information for users from Russia and Belarus](#additional-information-for-users-from-russia-and-belarus)
 
+## Project structure
+
+See [docs/project_structure.md](docs/project_structure.md) for the directory layout, the two hook types (shell vs Python), and where tests live.
+
 ## How to install
 
 ### 1. Install dependencies

docs/project_structure.md

@@ -0,0 +1,36 @@
+# Project structure
+
+This is a map of the repository for contributors. Hook *usage* stays in the [README](../README.md). How to add a hook, run tests, and open a PR is in [`.github/CONTRIBUTING.md`](../.github/CONTRIBUTING.md).
+
+## Layout
+
+| Path | Role |
+| --- | --- |
+| `hooks/` | Bash entry points (`<hook_name>.sh`) and shared `_common.sh` |
+| `src/pre_commit_terraform/` | Python package: CLI parsing, env expansion, `__GIT_WORKING_DIR__`, `terraform_docs_replace` |
+| `tests/pytest/` | Python unit tests (`pytest`) |
+| `tools/entrypoint.sh` | Docker image entrypoint |
+| `tools/install/` | Per-tool install scripts used when building the Docker image |
+| `dependencies/lock-files/` | Pinned Python constraints for reproducible image builds |
+| `.pre-commit-hooks.yaml` | Hook definitions consumed by the [pre-commit framework](https://pre-commit.com/) |
+| `pyproject.toml` / `hatch.toml` | Python project and build config |
+| `tox.ini` | Test environment matrix |
+| `.github/workflows/ci-cd.yml` | PR checks, tox, image build; release on merge to `master` |
+
+## Hook types
+
+**Shell hooks** (most of them) live in `hooks/<hook_name>.sh`:
+
+- Source `_common.sh` for `--args`, `--hook-config`, `--env-vars`, env expansion, `__GIT_WORKING_DIR__`, parallelism, and `terraform init`
+- Define `per_dir_hook_unique_part()` for per-directory work
+- Call `common::per_dir_hook` instead of splitting arguments by hand
+
+**Python hooks** run as `python -m pre_commit_terraform <subcommand>`:
+
+- Modules live under `src/pre_commit_terraform/`
+- Each subcommand implements `invoke_cli_app()`, `populate_argument_parser()`, and `CLI_SUBCOMMAND_NAME`
+- Register new subcommands in `_cli_subcommands.py` and add a hook entry in `.pre-commit-hooks.yaml`
+
+## Local checks
+
+Install pre-commit and run the repo's own hooks before you push. Python tests run with `tox`. Do not hand-edit `CHANGELOG.md`; releases own that file.