Hardware Project Folder Structure: A Practical Example — and Where Folders Break Down

A folder structure that works

Here is a tree that has served real hardware projects. It is organised by hardware and revision rather than by document type, for the reasons in how to organise hardware engineering documentation.

ORION-CONTROL-UNIT/
├── 00-product/
│   ├── product-overview.md
│   ├── requirements.md
│   └── known-limitations.md
│
├── 10-main-control-board/
│   ├── design/                      ← live, edited daily
│   │   ├── orion-mcb.kicad_pro
│   │   ├── orion-mcb.kicad_sch
│   │   ├── orion-mcb.kicad_pcb
│   │   └── lib/                     ← project-specific symbols, footprints
│   │
│   ├── releases/                    ← frozen, never edited
│   │   ├── MCB-A-001_2024-11-03/
│   │   ├── MCB-B-001_2025-04-18/
│   │   └── MCB-C-002_2026-03-14/
│   │        ├── fabrication/
│   │        ├── assembly/
│   │        ├── schematic.pdf
│   │        └── RELEASE-NOTE.txt
│   │
│   ├── verification/
│   │   ├── test-plan.md
│   │   ├── 2026-03-20_thermal-report.pdf
│   │   └── setups/
│   │
│   └── decisions/
│       ├── 2025-09-12_J1-replacement.md
│       └── 2026-01-30_C12-dielectric.md
│
├── 20-power-supply-board/
│   └── … same shape
│
└── 90-suppliers/
    ├── pcn-pdn/
    └── quotes/

Sample structure. The numeric prefixes keep the ordering stable and leave gaps for things that arrive later.

The four decisions that make it work

1. design/ and releases/ are different things. design/ is where work happens and changes constantly. releases/ is a sequence of frozen snapshots that nobody edits. Mixing them is the single most damaging shortcut, because it means the state that was manufactured can be modified afterwards.

2. Releases are named with both revision and date. MCB-C-002_2026-03-14. The revision says which design; the date disambiguates two releases of the same revision, which happens more than people expect.

3. Decisions get their own directory and one file each. Dated, named for the thing decided. These are the files that make a project transferable, and they take ten minutes to write at the time.

4. Suppliers live at product level, not inside a board. A PCN affects every board that uses the part. Filing it under one board hides it from the others.

What goes in a release note

The file that makes everything else findable:

Board:        Main Control Board
Revision:     C
Release:      MCB-C-002
Date:         2026-03-14
Approved by:  C. Benito
Source:       KiCad project, commit a1b2c3d

CHANGES SINCE MCB-C-001
  - BOM rev 5: R7 now DNP for export variant
  - Assembly drawing reissued to show R7 unfitted
  - No PCB change

CONTENTS
  fabrication/  gerbers (16 files), drill (2), fab drawing
  assembly/     BOM rev 5, centroid, assembly drawing
  schematic.pdf

Sample data.

Where folders start to break down

This is the honest part, and it is not "folders are bad". Folders are excellent at what they do. They break on three specific things.

They cannot enforce immutability

releases/ is read-only by convention. A convention holds until somebody needs to fix a typo at 7pm before a deadline. Then the record of what was manufactured quietly changes, and nothing anywhere notices.

File-system permissions help. They also get in the way often enough that people remove them.

They cannot express relationships across the tree

The structure encodes containment — this file is inside this revision. It cannot encode:

this BOM line uses the same component as that BOM line in another product; this release was built with that firmware version; * this capacitor appears in nine products, four of which are in production.

That last one is the question that matters the day a part goes EOL, and a folder tree cannot answer it. You answer it by opening nine BOMs and hoping everyone spelled the part the same way.

They have no idea what is current

A folder with MCB-B-001 and MCB-C-002 does not know that B is superseded, that C-002 is what shipped, or that a C-003 was started and abandoned. The ordering of names implies it. Nothing enforces it.

When folders are the right answer

Genuinely often:

one or two products; one or two engineers; a handful of revisions per board; no requirement to prove what was built to anyone external.

Under those conditions a disciplined tree plus a naming convention will serve for years, and the overhead of a system would exceed the benefit. Anyone telling you otherwise is selling something.

When they stop

Roughly when products × revisions exceeds what one person can hold in their head, or when any of these becomes true:

the same component appears in several products and you cannot list them; somebody outside the team needs to be told exactly what was built; a released package has been edited after release, even once; answering "which BOM shipped with this serial number" takes more than ten minutes; * the person who knows the structure is the bottleneck for everyone else.

That list is not a sales pitch. Three of those five can be fixed with discipline and no new tools.

A middle path

Before replacing anything, two cheap changes capture most of the benefit:

1. Make releases/ genuinely read-only at the file-system level, and accept

the friction. The friction is the feature.

1. Keep a single component index — one spreadsheet, one row per part, listing

which products use it. It duplicates information, which is a real cost, but it answers the EOL question in seconds instead of hours.

If both of those are in place and things still break, the problem is structural rather than procedural.

The tree above is a good structure and it will take a small team a long way. What it cannot do is know that one of the two BOMs inside it belongs to a revision nobody built, or tell you which products use a part that just went end-of-life.

XKEMA holds those relationships: documents hang from the element they describe, components are shared records rather than repeated text, and an approved version is frozen.

One thing it does not do, since it appears in the list above: XKEMA has no serial-number or as-built tracking. It can tell you what revision C contained; it cannot tell you which revision a particular unit was built from. That link lives in your production records.

Hardware documentation Component library * When does a project outgrow a spreadsheet?