Git Repository Architecture: Team Collaboration Git Setup

With team roles defined, the next step is to establish an efficient Git collaboration infrastructure. This section focuses on Git configurations directly related to team organization — how to design submodule architecture, branch strategies, permission models, and conventions that allow marketing, engineering, and finance to collaborate within a single version control system.

Team Repository Architecture Overview

IoT projects involve multiple asset types, each with distinct access permissions and update cadences:

Asset Type	Contents	Maintained by	Access
Firmware source	C/C++ code, CMakeLists	Firmware engineers	Engineering R/W
Hardware design	KiCAD projects, Gerber	Hardware engineers	Engineering R/W
Test scripts	Python scripts, test firmware	Test/Firmware engineers	Engineering R/W
Requirements	Customer needs, functional specs	Pre-sales engineers	Sales+Mgmt R/W
Business docs	Contracts, quotes, communication	Pre-sales engineers	Sales/Mgmt only
Project decisions	Approval reviews, financial assessment	Committee	All read, Mgmt write

Using Git submodules, you can organize different assets under one main repository while maintaining independent access control.

Submodule-Based Directory Structure

iot-project/                    # Main repo (index & docs only)
├── .gitmodules                 # Submodule declarations
├── README.md                   # Project overview, status, contacts
├── docs/                       # Project-level documentation
│   └── project-overview.md
├── firmware/                   # Submodule: firmware
│   └── (independent git repo)
├── hardware/                   # Submodule: hardware
│   └── (independent git repo)
├── test/                       # Submodule: automated testing
│   └── (independent git repo)
└── business/                   # Submodule: business docs (private)
    └── (independent git repo)

Submodule Initialization & Configuration

Creating the Main Repository

mkdir iot-project && cd iot-project
git init

mkdir docs
echo "# IoT Project" > README.md
git add README.md docs/
git commit -m "chore: initialize project main repo"

Adding Submodules

# Technical submodules (team-visible)
git submodule add https://github.com/your-org/iot-firmware.git firmware
git submodule add https://github.com/your-org/iot-hardware.git hardware
git submodule add https://github.com/your-org/iot-test.git test

# Business submodule (private, sales+management only)
git submodule add https://github.com/your-org/iot-business.git business

git add .gitmodules
git commit -m "chore: add all submodules"

Branch Protection Rules (Team-Wide)

All repositories (main + submodules) should enforce:

main branch: direct push prohibited, PR required
PR requirement: at least 1 Code Review approval
Status check: CI automated tests must pass

Role-Based Collaboration Workflow

Git Work Boundaries by Role

Role	Primary Submodule	Collaboration Method
Firmware engineer	`firmware/`	feature branch → PR → Code Review
Hardware engineer	`hardware/`	feature branch → PR → Code Review
Pre-sales engineer	`business/`	Direct commit or simple PR
Test engineer	`test/`	feature branch → PR → Code Review
Committee member	Main repo `README`	View status, no code writes

Post-Approval Git Collaboration Sequence

1. Committee approves project → update README in main repo
2. Tech lead creates feature branch from main in firmware/hardware
3. Development complete → PR within submodule → Code Review
4. Merge into submodule main → CI triggers integration tests
5. Update submodule reference pointer in main repo

# Step 2: Tech lead creates a feature branch
cd firmware
git checkout -b feature/mqtt-reconnect

# Step 3: Create PR on GitHub/GitLab after development

# Step 4: After merge, update main repo reference
cd ..
git add firmware
git commit -m "chore: update firmware submodule to mqtt-reconnect feature"

Git Workflow for Pre-Sales Colleagues

Pre-sales work primarily in the business/ submodule:

# Clone (first time)
git clone --recursive https://github.com/your-org/iot-project.git

# Daily: just work in business submodule
cd iot-project/business

git status
git add requirements/v2-customer-needs.md
git commit -m "docs: add customer phase 2 requirements"
git push origin main

Pre-sales colleagues don’t need to enter firmware/ or hardware/. The main repo’s README.md provides project status visibility for marketing and management.

Committee Decision ↔ Git Operations Mapping

Phase	Git Operation	Submodule
Pre-sales collects requirements	Write requirement docs in `business/`	`business/`
Technical assessment	BOM & cycle estimate in `firmware/`, `hardware/`	`firmware/`, `hardware/`
Financial assessment	Finance opinion document → `business/`	`business/`
Committee review	Update project approval status in main README	Main repo
Project approved	Create `feature/` branch from submodule `main`	Tech submodules

Team Git Standards

Item	Recommended Practice
Branch naming	`feature/name`, `fix/description`, `docs/name`
Commit messages	Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`)
Merging	Tech submodules: PR + Code Review; Business: simplified
Main branch protection	Tech submodules: no direct push
Submodule pointers	Update main repo commit after submodule merge
.gitignore	Each submodule manages its own
Cross-role visibility	Main repo README updated regularly for marketing & finance

Next: With the Git repository architecture established, the next section covers how pre-sales engineers use the business/ submodule to collect customer requirements and write formal requirement documents.

Building a commercial IoT product?

We provide ESP32 ODM design-to-manufacturing services. From prototype to production — the team behind this tutorial can build it with you.

Talk to us →