Software Architecture Skill

This skill provides architectural guidance for enhancing and cleaning up the lib-electronic-components library.

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                    ComponentType (Enum)                         │
│                    ~200 component types                         │
│         Base types (RESISTOR) + Specific (RESISTOR_CHIP_VISHAY) │
└────────────────────────┬────────────────────────────────────────┘
                         │ matched by
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│              ComponentManufacturer (Enum)                       │
│                    50+ manufacturers                            │
│         Each holds: regex pattern + ManufacturerHandler         │
└────────────────────────┬────────────────────────────────────────┘
                         │ delegates to
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│              ManufacturerHandler (Interface)                    │
│                    50+ implementations                          │
│     initializePatterns(), extractPackageCode(), extractSeries() │
└────────────────────────┬────────────────────────────────────────┘
                         │ populates
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│                PatternRegistry (Class)                          │
│     Map<ComponentType, Map<Class<?>, Set<Pattern>>>            │
│              Multi-handler pattern storage                      │
└────────────────────────┬────────────────────────────────────────┘
                         │ used by
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│          ComponentSimilarityCalculator (Interface)              │
│                    20+ implementations                          │
│     Per-component-type similarity strategies                    │
└─────────────────────────────────────────────────────────────────┘

Design Patterns In Use

PatternRegistry

ManufacturerHandlerFactory

ComponentSimilarityCalculator

ComponentManufacturer

ManufacturerHandler.matches()

Critical Issues to Fix

RESOLVED ISSUES (PR #74, #75)

The following issues have been fixed:

1. TIHandler Pattern Duplication - FIXED

   • Removed ~170 lines of duplicate COMPONENT_SERIES entries
   • Fixed LM35/LM358 pattern conflict (LM35 sensors use letter suffix A-D)

2. No Base Handler Class - FIXED

   • Created

     AbstractManufacturerHandler

     with shared helper methods
   • Methods:

     extractSuffixAfterHyphen()

     ,

     extractTrailingSuffix()

     ,

     findFirstDigitIndex()

     ,

     findLastDigitIndex()

3. Package Code Duplication - FIXED

   • Created

     PackageCodeRegistry

     with centralized mappings
   • Includes standard codes (N→DIP, D→SOIC) and Atmel-specific (PU→PDIP, AU→TQFP)

4. Flaky Tests - FIXED

   • Changed

     ManufacturerHandlerFactory

     from

     HashSet

     to

     TreeSet

     with deterministic ordering
   • Handler iteration order is now consistent across all test runs

5. ComponentType.getManufacturer() Fragile - FIXED

   • Was using string matching on manufacturer names (fragile)
   • Fixed with explicit

     MANUFACTURER_SUFFIX_MAP

     for special cases (ON→ON_SEMI, AD→ANALOG_DEVICES)
   • Direct enum

     valueOf()

     lookup for standard cases

6. TIHandlerPatterns.java Unused - FIXED (deleted)

   • File existed but was never used after TIHandler consolidation
   • Safely deleted

Package Code Registry (IMPLEMENTED)

The

PackageCodeRegistry

// Usage in handlers:
String resolvedCode = PackageCodeRegistry.resolve("PU");  // Returns "PDIP"
boolean isKnown = PackageCodeRegistry.isKnownCode("N");   // Returns true
boolean isPower = PackageCodeRegistry.isPowerPackage("TO-220"); // Returns true

Supported codes include:

• Standard: N→DIP, D→SOIC, PW→TSSOP, DGK→MSOP, DBV→SOT-23
• Power: T→TO-220, KC→TO-252, MP→SOT-223
• Atmel-specific: PU→PDIP, AU→TQFP, MU→QFN, SU→SOIC, XU→TSSOP

Next step: Migrate existing handlers to use the registry instead of inline maps.

Test Coverage Status (January 2026)

Handlers WITHOUT Tests (16): Abracon, AKM, Cree, DiodesInc, Epson, Fairchild, IQD, LG, LogicIC, Lumileds, NDK, Nexteria, OSRAM, Qualcomm, Spansion, Unknown

Similarity Calculators (ALL untested): CapacitorSimilarityCalculator, ConnectorSimilarityCalculator, DiodeSimilarityCalculator, LEDSimilarityCalculator, MCUSimilarityCalculator, MemorySimilarityCalculator, MosfetSimilarityCalculator, OpAmpSimilarityCalculator, ResistorSimilarityCalculator, SensorSimilarityCalculator, TransistorSimilarityCalculator, VoltageRegulatorSimilarityCalculator, MicrocontrollerSimilarityCalculator, DefaultSimilarityCalculator, PassiveComponentCalculator, LevenshteinCalculator

Priority tests to add:

1. Handler tests - For each handler:

   @Test void shouldDetectComponentType()
   @Test void shouldExtractPackageCode()
   @Test void shouldExtractSeries()
   @Test void shouldIdentifyReplacements()
   

2. Pattern conflict tests:

   @Test void noTwoHandlersShouldClaimSameMPN()
   

3. Similarity calculator tests:

   @Test void resistorsSameValueShouldBeHighSimilarity()
   @Test void differentComponentTypesShouldBeLowSimilarity()
   

Refactoring Priorities

COMPLETED (PR #74, #75)

• Deduplicate TIHandler COMPONENT_SERIES - Done, removed ~170 lines
• Create AbstractManufacturerHandler - Done
• Create PackageCodeRegistry - Done
• Fix flaky tests (handler ordering) - Done, uses TreeSet now

Priority 1: High (Structural Improvements)

1. Migrate handlers to use AbstractManufacturerHandler

   • Many handlers still use duplicate helper methods
   • Files:

     *Handler.java

     in

     manufacturers/

2. Migrate handlers to use PackageCodeRegistry

   • Replace inline PACKAGE_CODES maps with registry calls
   • Files:

     *Handler.java

     in

     manufacturers/

3. Delete TIHandlerPatterns.java - DONE

   • Deleted unused file

Priority 2: Medium (Quality Improvements)

4. Add Handler Unit Tests

   • Test each handler's pattern matching
   • New files:

     *HandlerTest.java

5. Fix ComponentType.getManufacturer() - DONE

   • Fixed with explicit MANUFACTURER_SUFFIX_MAP

6. Add Similarity Calculator Tests

   • Test each calculator
   • New files:

     *SimilarityCalculatorTest.java

Priority 3: Low (Enhancements)

7. Standardize Pattern Approaches
   • Consistent regex style across handlers
   • All handlers in

     manufacturers/

Technical Debt Inventory (January 2026)

Production Debug Statements (181 total - HIGH priority)

Action: Replace with SLF4J logging framework.

printStackTrace() Calls (9 total - HIGH priority)

Action: Replace with

logger.error("message", exception)

Inconsistent getSupportedTypes() Pattern

Action: Standardize all to Set.of() for immutability and conciseness. Note: 5 handlers fixed in PR #89: EspressifHandler, LogicICHandler, MaximHandler, PanasonicHandler, VishayHandler

Type/Pattern Registration Mismatches (Critical bugs)

Impact:

matches()

Fix pattern: When adding a type to

getSupportedTypes()

initializePatterns()

Code Quality Issues

Magic Numbers in Scoring (108+ instances)

All similarity calculators use hardcoded weights:

// Varies by calculator - no consistent values!
HIGH_SIMILARITY = 0.9
MEDIUM_SIMILARITY = 0.5-0.7  // Inconsistent!
LOW_SIMILARITY = 0.3

// Scoring increments vary wildly
valueMatch = 0.3-0.5
packageMatch = 0.2-0.4

Action: Extract to configurable SimilarityWeights constants class.

Code Smell Indicators

When reviewing code, watch for:

return "TO-220"

File Reference Quick Guide

ComponentManufacturer.java

*Handler.java

ComponentType.java

initializePatterns()

matches()

*SimilarityCalculator.java

MPNUtils

ComponentManufacturer.fromMPN()

Learnings & Quirks

Architecture Decisions

• ComponentManufacturer

  enum tightly couples manufacturer identity with handler - this is intentional for performance (single lookup)

• PatternRegistry

  supports multi-handler per type but this feature is largely unused
• Similarity calculators are registered in

  MPNUtils

  static initializer (lines 34-48)

Critical Implementation Details

Handler Ordering (PR #75):

• ManufacturerHandlerFactory

  MUST use

  TreeSet

  with deterministic comparator

• HashSet

  caused flaky tests because iteration order varied between runs
• First matching handler wins in

  getManufacturerHandler()

  - order is critical!

Type Detection Specificity (PR #74):

• MPNUtils.getComponentType()

  uses specificity scoring via

  getTypeSpecificityScore()

• Manufacturer-specific types (OPAMP_TI) score +150, generic types (IC) score -50
• Without scoring, iteration order could return IC instead of OPAMP_TI

ComponentType.getBaseType() Completeness:

• All manufacturer-specific types MUST be in the switch statement
• Missing types fall through to

  default -> this

  (returns self, not base type)
• Fixed in PR #74: Added TRANSISTOR_VISHAY, TRANSISTOR_NXP, OPAMP_ON, OPAMP_NXP, OPAMP_ROHM

ComponentType.getManufacturer() Mapping (PR #76):

• Uses explicit

  MANUFACTURER_SUFFIX_MAP

  for special cases (ON→ON_SEMI, AD→ANALOG_DEVICES, SILABS→SILICON_LABS, DIODES→DIODES_INC)
• Falls back to direct

  ComponentManufacturer.valueOf(suffix)

  for standard cases
• Much more reliable than previous string-contains matching

Cross-Handler Pattern Matching (PR #90 - CRITICAL FIX):

• Default

  ManufacturerHandler.matches()

  was using

  PatternRegistry.getPattern(type)

  which returned the first pattern from ANY handler
• This caused false matches when handlers were tested in alphabetical order (e.g., CypressHandler before STHandler)
• Fix: Added

  matchesForCurrentHandler()

  to PatternRegistry that only checks patterns for the current handler
• IMPORTANT: 7 handlers had custom

  matches()

  overrides with the same bug (using

  patterns.getPattern(type)

  as fallback):
  • NXPHandler, FairchildHandler, OnSemiHandler, MaximHandler, KemetHandler, WinbondHandler, TIHandler
  • All fixed by replacing fallback with

    patterns.matchesForCurrentHandler()

• Key insight: If tests pass locally but fail in CI, check for HashMap iteration order differences

Known Gotchas

• Handler order in

  ComponentManufacturer

  affects detection priority for ambiguous MPNs
• Some MPNs legitimately match multiple manufacturers (second-source parts)
• Handlers with custom matches() overrides: Must use

  patterns.matchesForCurrentHandler()

  NOT

  patterns.getPattern(type)

  for fallback matching
• CI vs Local differences: Usually caused by HashMap/HashSet iteration order - always use deterministic collections

Historical Context

• CI test failures (pre-PR #75) were caused by non-deterministic HashSet iteration
• Test stability now achieved via TreeSet with class name comparator
• PR #90: Fixed cross-handler pattern matching that caused STM32 MPNs to match CypressHandler
• Some handlers have commented-out patterns (e.g.,

  ComponentManufacturer.java

  lines 45-53) - unclear if deprecated or WIP

See Also

Advanced Skills

• /handler-pattern-design

  - Handler patterns, anti-patterns, and cleanup checklists

• /similarity-calculator-architecture

  - Calculator ordering and architectural patterns

• /component-type-detection-hierarchy

  - Type system architecture and specificity

• /manufacturer-detection-from-mpn

  - Manufacturer detection patterns and ordering

Documentation

• HISTORY.md - Technical debt history and completed work
• .docs/history/ - Detailed analyses of architectural decisions