From 86e9d29d56e11ea8360d09a4c126141129167ed4 Mon Sep 17 00:00:00 2001
From: ming <silverchris@foxmail.com>
Date: Wed, 1 Apr 2026 18:18:56 +0800
Subject: [PATCH] docs: add repository structure guide

---
 CONTRIBUTING.md              |  4 ++-
 docs/repository-structure.md | 65 ++++++++++++++++++++++++++++++++++++
 2 files changed, 68 insertions(+), 1 deletion(-)
 create mode 100644 docs/repository-structure.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0e9b66fe740..0b7b7f40748 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -30,6 +30,8 @@ See the [README.md](README.md#system-requirements) for platform specific setup s
 git clone https://github.com/FuelLabs/fuel-core
 ```
 
+If you are new to the codebase, see the [repository structure guide](docs/repository-structure.md) for a quick map of the top-level directories and workspace members.
+
 ### Configuring your Rust toolchain
 
 `rustup` is the official toolchain manager for Rust.
@@ -208,4 +210,4 @@ pub const CRATE_VERSIONS: &'static [(
     ("0-27-0", 1),
     ...
 ];
-```
\ No newline at end of file
+```
diff --git a/docs/repository-structure.md b/docs/repository-structure.md
new file mode 100644
index 00000000000..c55ef811667
--- /dev/null
+++ b/docs/repository-structure.md
@@ -0,0 +1,65 @@
+# Repository structure
+
+This guide provides a quick map of the `fuel-core` repository for contributors who need to find the right crate, binary, or support directory before making changes.
+
+## Top-level layout
+
+| Path | Purpose |
+|---|---|
+| `bin/` | Workspace binaries such as `fuel-core`, `fuel-core-client`, `keygen`, and test-oriented CLI tools. |
+| `crates/` | Library crates that implement the core node, shared types, storage, metrics, and service modules. |
+| `tests/` | Workspace-level integration tests and shared test helpers. |
+| `docs/` | Design notes and contributor-facing documentation. |
+| `deployment/` | Container build assets and deployment-oriented documentation. |
+| `benches/` | Benchmark crates and benchmark helpers. |
+| `version-compatibility/` | Release-compatibility tooling and chain configuration fixtures that are intentionally excluded from the main workspace. |
+| `xtask/` | Custom contributor workflows such as build-time automation. |
+| `.github/` | CI workflows, automation, and pull request templates. |
+| `.changes/` | Changelog fragments used by the release workflow. |
+| `ci_checks.sh` | Convenience entrypoint for the repository CI checks described in the README. |
+
+## Workspace members
+
+The root [`Cargo.toml`](../Cargo.toml) defines a Rust workspace with a few broad groups:
+
+- `bin/*`: executable entrypoints, including the main node binary in `bin/fuel-core`
+- `crates/fuel-core`: the core crate that wires GraphQL, services, state, and node-facing APIs together
+- `crates/services/*`: service implementations such as consensus, gas price, importer, producer, relayer, sync, and txpool
+- `crates/{database,storage,types,metrics,provider,client,...}`: shared libraries used across the node and its tooling
+- `tests`: the integration-test crate for end-to-end and cross-service behavior
+- `xtask`: custom build and maintenance commands used during development
+
+## Where to start for common tasks
+
+| If you want to... | Start here |
+|---|---|
+| Run or extend the main CLI | `bin/fuel-core/` |
+| Trace how the node assembles services | `crates/fuel-core/src/service.rs` and `crates/services/` |
+| Work on GraphQL behavior | `crates/fuel-core/src/graphql_api.rs` and related schema/query files in `crates/fuel-core/src/` |
+| Modify a specific runtime subsystem | The matching crate under `crates/services/` |
+| Update storage or shared domain types | `crates/storage/`, `crates/database/`, and `crates/types/` |
+| Add or repair integration coverage | `tests/tests/` and `tests/test-helpers/` |
+| Update contributor or operator docs | `docs/`, `deployment/`, `README.md`, or `CONTRIBUTING.md` |
+| Adjust custom build flows | `xtask/` |
+
+## Notes on a few commonly visited directories
+
+### `bin/`
+
+The `bin/` directory contains the workspace binaries. The most common entrypoint is `bin/fuel-core/`, which provides the main executable. Other binaries support client usage, key generation, end-to-end testing, or chaos-style testing.
+
+### `crates/`
+
+Most code changes land under `crates/`. A useful rule of thumb is:
+
+- use `crates/fuel-core/` when changing node-level composition or API wiring
+- use `crates/services/` when changing a specific subsystem
+- use the other top-level crates when the change is a reusable library concern rather than a node assembly concern
+
+### `tests/`
+
+The `tests/` workspace member is the integration surface for behavior that spans crates or services. Shared fixtures and utilities live in `tests/test-helpers/`.
+
+### `version-compatibility/`
+
+This directory is present in the repository but excluded from the main workspace. It is used for compatibility and upgrade-oriented workflows rather than normal day-to-day node development.