Skip to content

Component Update Guide

The Rule: Backend Is the Only Source of Truth

Component data lives only in the backend database:

backend/categorized_databases/{category}/{frequency_band}/{part_number}.json
  • There is no frontend component database and no sync step. The frontend reads components from the backend API only.
  • The old update_frontend_database.py script is deprecated — never run it.
  • The old scripts/update_component.js CLI no longer exists. Updates are done by editing the JSON file(s) directly, then validating.

See .claude/rules/database-sync-rule.md for the full rule.

Understanding Multi-Directory Components

Components can appear in multiple frequency band directories because they span multiple frequency ranges.

Example: - Component CGH40045 covers 0.5-6 GHz - Appears in: pa/sub_1ghz/CGH40045.json AND pa/1_6ghz/CGH40045.json

Why? Because: - 0.5-6 GHz overlaps with sub_1ghz (< 1 GHz) - AND overlaps with 1_6ghz (1-6 GHz)

Important: These are separate files (not symlinks). When you update one copy, you must update every copy to keep them consistent.

Update Workflow

Step 1: Find All Copies of the Component

cd backend/categorized_databases/pa
Get-ChildItem -Recurse -Filter "SST12CP21.json" | Select-Object FullName

Every path returned is a copy you must edit.

Step 2: Edit Each JSON File Directly

Open each file (e.g. backend/categorized_databases/pa/1_6ghz/SST12CP21.json) in your editor and change the field(s):

{
  "part_number": "SST12CP21",
  "efficiency": 30,
  "typical_current": 500
}
  • For array fields, use JSON array syntax, e.g. "power_range": [25, 35].
  • Apply the same change to every copy found in Step 1.

Bulk edit across all copies (PowerShell): 

cd backend/categorized_databases/pa
Get-ChildItem -Recurse -Filter "SST12CP21.json" | ForEach-Object {
    $content = Get-Content $_.FullName | ConvertFrom-Json
    $content.efficiency = 30
    $content | ConvertTo-Json -Depth 10 | Set-Content $_.FullName
}

Step 3: Validate

Run the offline schema/physics validator (see COMPONENT_VALIDATION_GUIDE.md):

cd backend
python validate_components.py --category pa

It checks Pydantic schema conformance, category-specific fields, cross-field physics rules, and frequency-band/folder consistency, and writes validation_report.json.

Optionally also run the unit-error checker (catches MHz-stored-as-GHz and Watts-stored-as-dBm mistakes):

cd backend
python scripts/validate_component_data.py --category pa

Step 4: Restart the Backend

The backend loads the component database at startup, so restart the servers to serve the updated data:

.\start-all-servers-windowed.ps1

Step 5: Verify Consistency Across Copies

cd backend/categorized_databases/pa
Get-Content 1_6ghz\SST12CP21.json | ConvertFrom-Json | Select-Object efficiency
Get-Content sub_1ghz\SST12CP21.json -ErrorAction SilentlyContinue | ConvertFrom-Json | Select-Object efficiency

All copies must show the same value.

Best Practices

  1. Find all copies first — a component spanning bands has one file per band; missing a copy creates silent inconsistency.
  2. Edit every copy identically — all copies must match.
  3. Always validate after editing — python validate_components.py catches schema breaks and physics violations before they reach the app.
  4. Restart the backend — edits are not picked up while the server is running.
  5. Never touch a frontend database or sync script — neither exists anymore.

Finding Components Across Directories

List all locations of a component: 

cd backend/categorized_databases/pa
Get-ChildItem -Recurse -Filter "SST12CP21.json" | Select-Object FullName

Count occurrences: 

cd backend/categorized_databases/pa
(Get-ChildItem -Recurse -Filter "SST12CP21.json").Count

List all components in a category: 

cd backend/categorized_databases/pa
Get-ChildItem -Recurse -Filter "*.json" | Select-Object Name

Future Improvement: Single Source of Truth

Current approach: Component files duplicated across frequency bands

Potential improvement: - Store component once in a components/ directory - Use symlinks or references in frequency band directories - Update once, reflects everywhere

Trade-off: - ✅ Single source of truth - ✅ Easier updates - ❌ More complex structure - ❌ Cross-platform symlink issues

Recommendation: Keep current structure for now (simpler, more portable). Use the find-all-copies step to keep duplicates consistent.

Troubleshooting

Issue: Component not found

Check: - Category name is correct (pa, filter, vco, etc.) - Part number matches exactly (case-sensitive) - Component exists in database

Solution: List the category contents (see "Finding Components" above).

Issue: Update not visible in the app

Check: - Did you restart the backend after editing? (.\start-all-servers-windowed.ps1) - Is the JSON syntactically valid? (python validate_components.py --category <cat> reports "Invalid JSON format" for broken files)

Issue: Inconsistent copies across frequency bands

Cause: A manual edit missed some copies.

Solution: Re-run the find-all-copies search and apply the same edit to every file returned, or use the PowerShell bulk-edit snippet above.

Summary

To update a component:

  1. Find every copy: Get-ChildItem -Recurse -Filter "<PART>.json" under backend/categorized_databases/<category>/
  2. Edit each JSON file directly with the same change.
  3. Validate: cd backend; python validate_components.py --category <category>
  4. Restart: .\start-all-servers-windowed.ps1

For a concrete worked example, see COMPONENT_UPDATE_STEP_BY_STEP.md.