The How and Why of Organizing Your Hardware Design Project's Digital Files

This blog post is based on by own experiences organizing and managing a hardware design project for small teams with the goal of reaching small batch manufacture. It serves as a sort of homegrown "ERP/MRP/PLM/BOM" system for staying on top of your design, manufacturing, and other files, with the goal of a smooth transition to production.

Along with this post, we've also set up a completely open source example project, the AWK-106 Flying Fun Plane. Besides the product page,  we've open sourced the

Bill of Materials / Full Product Definition
Manufacturing Files
Onshape Design Files
Github full project folder 

The Tools for Hardware Projects Haven't Caught Up With Software

The first step in organizing hardware projects with modern tools is understanding what tools are available for software, why they're so great, and then adapting them to hardware.

The "Gitflow" Software Flow

Git is a software tool that makes it really easy to change, track, branch, and merge different versions of text files (usually software source code) across multiple different computers.

In fact, it's so easy to make branches, that it's encouraged. (What's a few more bits and bytes here and there anyway?) Multiple people can work on individual new features of code, each on their own branches, then merge them back together!


Hardware Flow

Unfortunately, for hardware, merging binary files, like Solidworks CAD data, just doesn't work as well. That's ok though, because hardware tends to follow a much more linear development path. Adding a new webpage might be a few more lines of HTML, but adding new hardware means cutting stuff, machining stuff, buying stuff, making stuff. It tends to be a little more planned than software and the iteration time is certainly longer.

(As a sidebar, the difficulty in merging binary files does mean there are challenges for having multiple people work on a section of CAD model, or a section of circuit board schematic, but that's another topic entirely, and some in-browser, web based software, like, circumvents the issue entirely.)

The Catch With Hardware - Physical Builds Continue to Exist

Even though hardware development tends to follow a more linear path, there is an important catch:

Any time something physical is built, it lives on as a short, small "fork" off the main linear path.

Linear Flow

This includes test parts, samples, purchases from Digikey and McMaster, prototypes, engineering builds, production parts, benchtop hack jobs, and any other engineering experiments.

Whereas a software branch might get changed, recompiled, and iterated on multiple times before folding back into the main branch, in hardware, because of the inability to merge binary design data from CAD tools, an engineer is more likely to just work forward in a linear path from the previous design tool state.

The Foundation of Our Framework: The Build Log

That leads to our main organizational principle: Any action that results in the creation of a physical article should be entered into a build log.

Here's a bit more about how we use the build log in practice

  1. The build log gets its own folder in the directory structure of your project. That means the entire build log history get's carried forward with each "commit" to Git. A perk of this is that there's no need to change Git "branches" to see a build log entry for "what was built". This also works really well without Git using Dropbox or other shared folders.

  2. We treat each build log entry as a snap shot in time, with both design and manufacturing files. So a 3d print, for example, would include the original CAD design file, the .stl file sent to the printer, and any photos or notes we would want to include about the build.

  3. We number our build entries (including leading zeros) as sub folders in our build log. We find this is more orderly than relying on the "date created" field and allows the folder to be sorted alphabetically.

So our build log ends might end up looking something like this:

Build Log

The Main Design Branch

OK. So we've established the need for a build log, which tracks the physical things that were actually made in the course of a project and now we'll talk about the main design folder, which is where the bulk of the day to day work on the project will take place.

Again, we have a few guiding principles, based on driving products through small batch manufacture.

  1.  The organization of the design folder should reflect the "product breakdown structure." In other words, the subfolders should reflect the physical components of your product.

  2. The design folder should be kept clean and reflect the current state of the design process, which means moving old design files to an archive subfolder. In our experience, we have often wanted to peek in our build log to see "what we made," but hardly ever rolled back to old designs. Keeping out of date design files in an unarchived state is asking for clutter and asking for trouble.

Putting the Pieces Into a Bill of Materials

The last piece of getting to small batch manufacture is the Bill of Materials, or BoM. The BoM is the equivalent of the ingredients list and recipe for making a hardware product.

We've often seen the BoM shown as just a simple parts list, which might serve to describe the finished product, but doesn't quite capture all the work that it took to get there.

In our example project, a laser cut cardboard plane, we point out the number of items that fully define the plane's wing. There is

  1. The original CAD design file
  2. The manufacturing file, which is a .pdf that gets sent to a laser cutter
  3. The raw cardboard the part is cut from
  4. The finished part.

There is unfortunately no defined standard for organizing a Bill of Materials, but if you can capture at least items #2-4 in your BoM, you'll be all set. In regards to not needing item #1, remember, the design tools are just tools that generate manufacturing files. So if your design data was completely lost, but the manufacturing files still existed and were listed on the BoM, you could still make your product. Often, the design data, (like a Solidworks file) is used as the manufacturing file, which is why this concept is often confusing.

Putting the BoM and the Build Log Together

The final step in putting all these pieces together is to show how we use the Build Log, combined with a Bill of Materials,  to manage the transition from designing a product to actually building one.

It's very unusual on early builds to be able to order all the items on a BoM all at once. We typically finish portions of a design on a rolling basis, and we're able to kick off orders for things like say, mechanical housings, well in advance of things like circuit boards.

We'll typically keep our BoM at the top level in our Build Log folder and then for each line, we'll list the build log entry that was released to manufacture.

Every time we run a new batch of product, we copy our BoM to a new tab in our spreadsheet and start again from there.

To summarize, we use BoM spreadsheet tabs to manage product batch records and build log entries to manage line item records.

So a batch build history might look something like this:

=== Batch #1: Test build ===
Item # | Description | Ordered on
1      | Case        | Build log 05
2      | PCB         | Build log 02
3      | Packaging   | Build log 09

=== Batch #2: Production build ===
Item # | Description | Ordered on
1      | Case        | Build log 08
2      | PCB         | Build log 07
3      | Packaging   | Build log 10 

Summarizing and Wrapping Up

We hope this information is helpful to you on how to organize your hardware project. There's a lot of ground to cover and more detail to go into that we didn't go over here, including working collaboratively on CAD, more detail about what goes on a BoM, and more detail about the different phases that a product goes through as it goes from being a prototype to a full fledged product.


  1. Make a build log entry for every action that results in a physical article being built
  2. Keep the design folder clean; it should representing the current design state
  3. Know the difference between design files and manufacturing files
  4. Use spreadsheets BoMs to manage batches and build logs to manage line items.

E-mail List

Hey, we like to think our email list is pretty awesome! We share projects, discounts, and other cool stuff we're working on. Sign up below!


  • I think this article is so interesting, I’ve been using the which is a Git for hardware projects, it has file viewer to visualize & share my step and 3dm models… plus, it doesn’t require any coding

    Carolina Alves Portugal
  • Thank you for sharing. Given it’s been a few years, do you have any follow-ups or lessons learned since you wrote this article? As a software guy that started a medical device hardware company a year ago, I find this comparison easy to comprehend, and of course, the use of spreadsheets and conventions seems to highlight the opportunity for a SaaS solution to help physical product teams build better. Do you know of any SaaS solutions that help enforce or guide these principals? Thanks again.

    Michael Bender
  • “…this tells me you are committing binary files, or output products, to Git.”
    This tells me you have no experience using hardware design tools for electronics or mechanical design. Plenty of them use proprietary binary file formats for the actual designs. Even MS Office now saves things as binary (zip) files. Of course output/generated files shouldn’t be in the git rep, but you’re mistaken if you think it’s possible to avoid binary files entirely in this domain.

  • You say “because of the inability to merge binary design data”, and this tells me you are committing binary files, or output products, to Git. Instead you should release the output products to a binary repository like artifactory, or more simply have a Maven or Ivy repository directly on the file system (local or NFS).

    Martin d'Anjou

Leave a comment

Please note, comments must be approved before they are published