🚀 PCB Placement Rules Auto-Sync System¶

Single source of truth for component placement rules with automatic code synchronization

📋 Overview¶

This system ensures your placement rules in COMPONENT_PLACEMENT_LAYOUT_RULES.md automatically sync to your code files, maintaining consistency across your PCB design workflow.

🔧 System Components¶

File	Purpose
`COMPONENT_PLACEMENT_LAYOUT_RULES.md`	Source of truth for all placement rules
`scripts/development/sync-placement-rules.py`	Parser & synchronizer - updates code to match rules
`scripts/utilities/watch-placement-rules.py`	File watcher - triggers sync when rules change
`scripts/validation/validate-placement-rules.py`	Validator - ensures compliance
`scripts/development/setup-placement-auto-sync.ps1`	Setup script - easy management interface

🚀 Quick Start¶

Option 1: Interactive Setup (Recommended)¶

.\scripts\development\setup-placement-auto-sync.ps1

Then choose: - Option 1: Manual sync (run once) - Option 2: Auto-watcher (continuous monitoring) - Option 3: Validate compliance

Option 2: Manual Commands¶

# Manual synchronization
python scripts/development/sync-placement-rules.py    # npm run sync-placement-rules

# Start automatic file watcher
python scripts/utilities/watch-placement-rules.py     # npm run watch-placement-rules

# Validate compliance
python scripts/validation/validate-placement-rules.py .  # npm run validate-placement-rules

📋 How It Works¶

1. Rules Definition (COMPONENT_PLACEMENT_LAYOUT_RULES.md)¶

### 1.1 Zoning Layout
- RF Signal Chain Zone (y=100mm)  ← This gets parsed
- DC/Power Components Zone (y=50mm)  ← This gets parsed

### 2.1 Minimum Spacing Requirements
| **Base (Any)** | 2.0mm | DFM manufacturability |  ← This gets parsed
| **RF-to-RF** | 3.0mm | Interference prevention |  ← This gets parsed

2. Automatic Parsing¶

The sync script extracts: - ✅ Zone constants: rf_zone_y = 100.0, dc_zone_y = 50.0 - ✅ Spacing constants: min_component_spacing = 2.0, etc. - ✅ Package size database from the markdown tables - ✅ Component classification rules

3. Code Synchronization¶

Updates kicad_export.py with:

# AUTOMATICALLY UPDATED from markdown rules
rf_zone_y = 100.0       # ← From "RF Signal Chain Zone (y=100mm)"
dc_zone_y = 50.0        # ← From "DC/Power Components Zone (y=50mm)"
min_component_spacing = 2.0     # ← From spacing table
rf_component_spacing = 3.0      # ← From spacing table

4. Validation & Compliance¶

Ensures all code follows the documented rules.

🎬 Usage Scenarios¶

Scenario 1: Update Spacing Rules¶

Edit COMPONENT_PLACEMENT_LAYOUT_RULES.md:

| **RF-to-RF** | 4.0mm | Interference prevention |  # Changed from 3.0mm

Sync automatically (if watcher running) or run:

python scripts/development/sync-placement-rules.py

Code updates automatically:

rf_component_spacing = 4.0  # Was 3.0, now 4.0

Scenario 2: Add New Component Zone¶

Add to rules:
```
- Analog Components Zone (y=25mm)
```
Sync and the code gets:
```
analog_zone_y = 25.0
```

Scenario 3: Continuous Development¶

Start watcher:

python scripts/utilities/watch-placement-rules.py

Edit rules as needed - code updates automatically
Validation runs after each change
Commit when ready

📊 Validation Features¶

Automatic Checks¶

✅ Rules Synchronization: Code matches current rules
✅ Spacing Constants: All required constants present and correct
✅ Zone Constants: RF/DC zones properly defined
✅ Required Functions: All mandatory functions exist
✅ Package Database: All required packages included
✅ Classification Rules: Component classification follows standards

Sample Validation Output¶

🔍 Validating Component Placement Rules...
------------------------------------------------------------
Checking rules synchronization...
Validating backend/utils/kicad_export.py...
Validating backend/utils/test_placement.py...

✅ All placement rules validated successfully!
✅ VALIDATION PASSED - Ready to commit!

🔧 Advanced Configuration¶

Custom Rules File¶

# Use different rules file
parser = PlacementRulesParser("MY_CUSTOM_RULES.md")

Custom Target Files¶

# Sync different target file
synchronizer = CodeSynchronizer("my_custom_file.py")

Adding New Rule Types¶

Extend the PlacementRulesParser class:

def _extract_my_custom_rules(self, content: str) -> Dict:
    # Parse your custom rule format
    pass

🛡️ Safety Features¶

Automatic Backups¶

✅ Backup created before every sync: kicad_export.py.backup
✅ Automatic restore if sync fails
✅ Manual restore available

Validation Before Changes¶

✅ Rules validated before sync
✅ Code validated after sync
✅ Compliance check before commit

Error Handling¶

✅ Graceful failure with detailed error messages
✅ Rollback on sync failure
✅ Detailed logging for debugging

🔄 ENSURING AUTO-SYNC ALWAYS RUNS¶

Method 1: Integrated with Main Servers (RECOMMENDED)¶

The placement rules watcher is automatically included in the main server startup:

# Starts the two app servers (FastAPI backend + React frontend)
.\start-all-servers-windowed.ps1

Note: start-all-servers-windowed.ps1 does NOT start the placement rules watcher — it launches only the FastAPI backend (port 8000) and the React frontend (port 5180). To run the watcher, use the npm script in Method 2 below (in its own terminal).

Method 2: Standalone NPM Scripts¶

# Start only the placement rules watcher
npm run watch-placement-rules

# Manual sync (one-time)
npm run sync-placement-rules

# Validate current rules
npm run validate-placement-rules

Method 3: Direct Python Execution¶

# Activate virtual environment first
.\venv\Scripts\Activate.ps1

# Start watcher
python scripts/utilities/watch-placement-rules.py

Method 4: Background Service Setup¶

For production environments or if you want it to run as a Windows service:

# Interactive setup wizard
.\scripts\development\setup-placement-auto-sync.ps1

🛡️ WATCHER VERIFICATION¶

Start the watcher in its own terminal with npm run watch-placement-rules. When it is running you'll see it print the files it is monitoring and a message on each detected change. The two app servers, started separately by .\start-all-servers-windowed.ps1, run at:

  Frontend:  http://localhost:5180
  Backend:   http://localhost:8000
  API Docs:  http://localhost:8000/docs

🔍 TROUBLESHOOTING AUTO-STARTUP¶

Missing Watcher Window?¶

Check if the watcher script exists:

# Should exist
ls scripts/utilities/watch-placement-rules.py

Python Environment Issues?¶

Ensure watchdog is installed:

.\venv\Scripts\Activate.ps1
pip install watchdog

Manual Recovery¶

If the integrated startup fails, manually start:

npm run watch-placement-rules

💡 DEVELOPMENT WORKFLOW¶

Normal Development (Recommended)¶

Start everything: .\start-all-servers-windowed.ps1
Edit rules in COMPONENT_PLACEMENT_LAYOUT_RULES.md
Code automatically updates in background
Continue development - no manual intervention needed

Rule Changes Only¶

npm run watch-placement-rules (if not already running)
Edit COMPONENT_PLACEMENT_LAYOUT_RULES.md
See instant code updates

Quick Manual Sync¶

# One-time sync without watching
npm run sync-placement-rules

📝 File Structure¶

pcb_stackup_generator/
├── docs/guides/COMPONENT_PLACEMENT_LAYOUT_RULES.md  ← SOURCE OF TRUTH
├── backend/utils/kicad_export.py                    ← TARGET FILE
└── scripts/
    ├── development/sync-placement-rules.py          ← SYNCHRONIZER
    ├── development/setup-placement-auto-sync.ps1    ← SETUP SCRIPT
    ├── utilities/watch-placement-rules.py           ← FILE WATCHER
    └── validation/validate-placement-rules.py       ← VALIDATOR

🎯 Integration with Development Workflow¶

Pre-commit Hook Integration (opt-in — not shipped)¶

There is no repo-provided placement pre-commit hook. If you want commit-time validation, wire the validator into your own local hook, e.g.:

# In .git/hooks/pre-commit
python scripts/validation/validate-placement-rules.py .

CI/CD Integration (not currently configured)¶

No placement-rules workflow ships in .github/workflows/. To add one:

- name: Validate Placement Rules
  run: |
    python scripts/validation/validate-placement-rules.py .

Development Best Practices¶

Always validate before committing
Review changes after synchronization
Test placement after rule updates
Document rule changes in commits

🏆 Benefits¶

✅ Consistency: Code always matches documented rules
✅ Automation: No manual code updates needed
✅ Validation: Automatic compliance checking
✅ Safety: Backup and restore capabilities
✅ Transparency: Clear audit trail of changes
✅ Maintainability: Single source of truth for rules

COMPONENT_PLACEMENT_LAYOUT_RULES.md - Complete placement rules
SETUP_PLACEMENT_RULES_ENFORCEMENT.md - Setup instructions
backend/utils/kicad_export.py - Target implementation file

🔄 Keep your placement rules and code in perfect sync!