Skip to content

COMPREHENSIVE_REFACTORING_PLAYBOOK.md

Latest commit

 

History

History
575 lines (423 loc) · 25 KB

COMPREHENSIVE_REFACTORING_PLAYBOOK.md

File metadata and controls

575 lines (423 loc) · 25 KB

Comprehensive Domain Terminology Refactoring Playbook

Executive Summary

Overall Health Score

Domain Language Adherence: 17% (Critical)

The codebase shows significant terminology drift from the medical/biological domain terminology. While core systems (Nervous, Circulatory, Immune, Skeletal, Muscular, Respiratory, Glial) use medical terminology, the UI system, visualization system, and infrastructure terms use generic technical terminology.

Critical Areas for Refactoring

  1. UI System (Critical): 12 legacy terms need migration to Skin system

    • VisualNeuron → SkinCell (42 files affected)
    • SensoryNeuron → Receptor (25 files affected)
    • ComponentProps/State → System-specific types (100+ files affected)

  2. Visualization System (High): 11+ generic chart terms need medical equivalents

    • Chart → Visualization (10 files affected)
    • All chart types need medical equivalents

  3. Infrastructure (High): Server/Client/Bridge terms need medical equivalents

    • Server → Organ/System (15 files affected)
    • Client → Receptor/Effector (10 files affected)

  4. Communication (Medium): EventBus/Event need Circulatory System terms

    • EventBus → Heart/Artery (3 files affected)

  5. Respiratory System (Medium): Router/Resource/Route need medical equivalents

    • Router → Bronchus/Trachea (15 files affected)
    • Resource → Oxygen/Nutrient (20 files affected)

Statistics

  • Total Terms Audited: 500+
  • Direct Match: 85 terms (17%)
  • Legacy/Deprecated: 12 terms (2.4%)
  • Ambiguous/Confusing: 8 terms (1.6%)
  • No Match: 395+ terms (79%)
  • Misspelled: 0 terms (0%)

Summary of Most Critical Areas

  1. UI System: The entire UI system uses legacy terminology (VisualNeuron, SensoryNeuron, etc.) that should be migrated to Skin system terminology (SkinCell, Receptor, etc.) per SKIN_WEBNN_ARCHITECTURE.md.

  2. Type System: Generic ComponentProps/ComponentState types are used throughout the codebase (100+ files). These should be system-specific (SkinCellProps, ReceptorProps, etc.).

  3. Visualization System: All visualization components use generic "Chart" terminology. These should use "Visualization" or medical equivalents.

  4. Infrastructure: Server/Client/Bridge terms are generic technical terms. These should use medical equivalents (Organ/System, Receptor/Effector, Synapse/Connection).

1. Glossary & Audit Findings

Official Domain Terminology Glossary

See DOMAIN_TERMINOLOGY_GLOSSARY.md for the complete Official Domain Terminology Glossary.

Complete Audit Findings

See AUDIT_FINDINGS.md for the complete audit findings with all categorized terms.

Key Findings

Direct Match (85 terms)

  • Core medical/biological terms are correctly used
  • Nervous System, Circulatory System, Immune System, Skeletal System, Muscular System, Respiratory System, Glial System terms are correct
  • Theater System terms are correct

Legacy/Deprecated (12 terms)

  • VisualNeuron → should be SkinCell
  • SensoryNeuron → should be Receptor
  • MotorNeuron → should be Effector
  • InterneuronUI → should be DermalLayer
  • VisualAstrocyte → should be Adipocyte
  • VisualOligodendrocyte → should be Melanocyte
  • ComponentProps → should be system-specific
  • ComponentState → should be system-specific

Ambiguous/Confusing (8 terms)

  • Router → could mean network router or HTTP router (should be Bronchus/Trachea)
  • Resource → generic technical term (should be Oxygen/Nutrient)
  • ResourcePool → generic technical term (should be Alveolus/Capillary)
  • Protocol → conflicts with Theater Protocol (should be Bronchus/Trachea)
  • Route → generic technical term (should be Bronchiole)
  • Adapter → generic technical term (should be Bronchus)
  • EventBus → generic technical term (should be Heart/Artery)
  • Event → generic technical term (should be BloodCell/Signal)

No Match (395+ terms)

  • Generic UI components: Button, Input, Select, Form, Modal, Card, Alert, Text, Radio, Checkbox
  • Visualization terms: Chart, BarChart, LineChart, PieChart, ScatterPlot, ChartDataPoint, DataBounds, CanvasPoint
  • Infrastructure terms: Server, Client, Bridge, WebSocketBridge, TheaterServer, HotReload
  • Configuration terms: Config, Options, Settings, ServerConfig, ServerState
  • Type system terms: ComponentProps, ComponentState, Props, State
  • Testing terms: Test, Mock
  • Communication terms: EventBus, Event
  • Tools terms: DependencyAuditor, AuditReport, AuditOptions

2. Prioritized Refactoring Plan

High Priority Changes (45 changes)

See PRIORITIZED_REFACTORING_PLAN.md for the complete prioritized refactoring plan.

Top 10 Critical Changes

  1. VisualNeuron → SkinCell (42 files, Critical)
  2. ComponentProps → System-specific props (100+ files, Critical)
  3. ComponentState → System-specific state (100+ files, Critical)
  4. SensoryNeuron → Receptor (25 files, Critical)
  5. Button → TouchReceptor (5 files, High)
  6. Input → TextReceptor (5 files, High)
  7. Chart → Visualization (10 files, High)
  8. EventBus → Heart/Artery (3 files, High)
  9. Router → Bronchus/Trachea (15 files, High)
  10. Resource → Oxygen/Nutrient (20 files, High)

Medium Priority Changes (35 changes)

  • Configuration terms (Config, Options, Settings)
  • Respiratory system resource terms (DatabaseResource, CacheResource, StorageResource)
  • Protocol adapters (RestAdapter, GraphQLAdapter, WebSocketAdapter)
  • Component props/state (InputProps, SelectProps, FormProps, etc.)
  • Testing terms (Test → Experiment/Hypothesis, Mock → Specimen/Model)
  • Tools terms (DependencyAuditor → DependencyAnalyzer)

Low Priority Changes (20+ changes)

  • Technical infrastructure terms that don't conflict with medical metaphor
  • Storybook conventions (Story, StoryObj)
  • Internal implementation details

3. Risk & Implementation Strategy

Blast Radius Assessment

See BLAST_RADIUS_ASSESSMENT.md for detailed blast radius assessment for each High Priority change.

Critical Risk Areas

  1. VisualNeuron → SkinCell: 42 files affected, Critical risk

    • Breaking: API, Type, Inheritance, Export
    • Migration: Rename class, file, update 42 imports, 100+ type references

  2. ComponentProps/State: 100+ files affected, Critical risk

    • Breaking: Type system, Generic constraints
    • Migration: Create system-specific types, update 100+ files

  3. SensoryNeuron → Receptor: 25 files affected, Critical risk

    • Breaking: API, Type, Inheritance, Export
    • Migration: Rename class, file, update 25 imports, 50+ type references

Recommended Phasing

See PHASING_AND_TDD_PLAN.md for the complete phasing strategy.

Phase 1: Core UI System Terminology (Week 1-2)

  • VisualNeuron → SkinCell
  • SensoryNeuron → Receptor
  • MotorNeuron → Effector
  • InterneuronUI → DermalLayer
  • VisualAstrocyte → Adipocyte
  • VisualOligodendrocyte → Melanocyte
  • ComponentProps → System-specific props
  • ComponentState → System-specific state

Rationale: Foundation for all UI components. Must be done first.

Risk: Critical - Breaking changes to core UI system

Estimated Effort: 2 weeks

Phase 2: UI Component Names (Week 3-4)

  • Button → TouchReceptor
  • Input → TextReceptor
  • Select → SelectReceptor / ChoiceReceptor
  • Form → DermalLayer
  • Modal → Membrane / Vesicle
  • Card → DermalLayer / Epidermis
  • Alert → AlertReceptor / Nociceptor
  • Text → Keratinocyte / TextCell
  • Radio → RadioReceptor / ChoiceReceptor
  • Checkbox → CheckReceptor / ToggleReceptor

Rationale: Depends on Phase 1. Components extend base classes.

Risk: High - Breaking changes to component library

Estimated Effort: 2 weeks

Phase 3: Visualization System (Week 5-6)

  • Chart → Visualization
  • BarChart → BarVisualization
  • LineChart → LineVisualization
  • PieChart → PieVisualization
  • ScatterPlot → ScatterVisualization
  • ChartDataPoint → DataPoint / Measurement
  • DataBounds → Bounds / Range
  • CanvasPoint → Coordinate / Point
  • BaseChartProps → BaseVisualizationProps
  • BaseChartState → BaseVisualizationState
  • ChartTheme → VisualizationTheme

Rationale: Independent of UI system changes. Can be done in parallel with Phase 2.

Risk: Medium - Breaking changes to visualization system

Estimated Effort: 2 weeks

Phase 4: Communication System (Week 7)

  • EventBus → Heart / Artery
  • Event → BloodCell / Signal

Rationale: Independent system. Can be done in parallel.

Risk: Medium - Breaking changes to communication system

Estimated Effort: 1 week

Phase 5: Respiratory System (Week 8-9)

  • Router → Bronchus / Trachea
  • Resource → Oxygen / Nutrient
  • ResourcePool → Alveolus / Capillary
  • Route → Bronchiole
  • DatabaseResource → DatabaseOxygen / DatabaseNutrient
  • CacheResource → CacheOxygen / CacheNutrient
  • StorageResource → StorageOxygen / StorageNutrient
  • RestAdapter → RestBronchus
  • GraphQLAdapter → GraphQLBronchus
  • WebSocketAdapter → WebSocketBronchus
  • ProtocolAdapter → ProtocolBronchus

Rationale: Independent system. Can be done in parallel.

Risk: Medium - Breaking changes to respiratory system

Estimated Effort: 2 weeks

Phase 6: Infrastructure Terms (Week 10)

  • Server → Organ / System
  • Client → Receptor / Effector
  • Bridge → Synapse / Connection
  • WebSocketBridge → WebSocketSynapse / WebSocketConnection
  • TheaterServer → TheaterOrgan / TheaterSystem
  • ClientConnection → ReceptorConnection / EffectorConnection
  • HotReload → Regeneration / Renewal
  • ServerConfig → OrganConfig / SystemConfig
  • ServerState → OrganState / SystemState
  • WebSocketConfig → WebSocketConnectionConfig
  • HotReloadConfig → RegenerationConfig

Rationale: Independent system. Can be done in parallel.

Risk: Medium - Breaking changes to infrastructure

Estimated Effort: 1 week

Phase 7: Tools & Testing Terms (Week 11)

  • DependencyAuditor → DependencyAnalyzer / DependencyInspector
  • AuditReport → AnalysisReport / InspectionReport
  • AuditOptions → AnalysisOptions / InspectionOptions
  • Test → Experiment / Hypothesis (in test files)
  • Mock → Specimen / Model (in test files)

Rationale: Less critical. Can be done last.

Risk: Low - Internal tools, less breaking

Estimated Effort: 1 week

Total Estimated Timeline

11 weeks (approximately 3 months) for complete refactoring

4. TDD/Verification Plan

See PHASING_AND_TDD_PLAN.md for the complete TDD/Verification plan.

General TDD Principles

  1. Write Tests First: Before refactoring, write tests that assert the new terminology
  2. Update Tests During Refactoring: Update test imports, class names, type references, assertions
  3. Verify After Refactoring: Run full test suite, verify all tests pass, check test coverage
  4. Backward Compatibility (if needed): Create deprecated aliases, add deprecation warnings, document migration path

Verification Checklist (Per Phase)

  • All tests pass
  • Type checking passes
  • Build succeeds
  • Exports work correctly
  • Documentation updated
  • No old terminology remains
  • Integration tests pass
  • Performance not degraded
  • No breaking changes (or documented)

Test Adaptation Steps

  1. Update Test Imports:

    // Before
import { VisualNeuron } from '../VisualNeuron';

// After
import { SkinCell } from '../SkinCell';

  2. Update Test Class Names:

    // Before
class TestVisualNeuron extends VisualNeuron<...> {}

// After
class TestSkinCell extends SkinCell<...> {}

  3. Update Type References:

    // Before
class TestComponent extends VisualNeuron<ComponentProps, ComponentState> {}

// After
class TestComponent extends SkinCell<SkinCellProps, SkinCellState> {}

  4. Update Test Assertions:

    // Before
expect(component).toBeInstanceOf(VisualNeuron);

// After
expect(component).toBeInstanceOf(SkinCell);

5. Detailed Refactoring Tables

High Priority Changes Table

Current Term Location(s) Proposed Term Justification Priority Affected Files Risk Level
VisualNeuron src/ui/VisualNeuron.ts, src/ui/components/*.ts, src/visualization/*.ts (42 files) SkinCell Per SKIN_WEBNN_ARCHITECTURE.md, VisualNeuron should be SkinCell. This is the base class for all UI components. High 42 Critical
SensoryNeuron src/ui/SensoryNeuron.ts, src/ui/components/Button.ts, src/ui/components/Input.ts, src/ui/components/Select.ts, src/ui/components/Radio.ts, src/ui/components/Checkbox.ts Receptor Per SKIN_WEBNN_ARCHITECTURE.md, SensoryNeuron should be Receptor. Input components detect external stimuli. High 25 Critical
MotorNeuron src/ui/MotorNeuron.ts Effector Per SKIN_WEBNN_ARCHITECTURE.md, MotorNeuron should be Effector. Action components produce responses. High 3 High
InterneuronUI src/ui/InterneuronUI.ts, src/ui/components/Form.ts, src/ui/components/Modal.ts, src/ui/components/Card.ts DermalLayer Per SKIN_WEBNN_ARCHITECTURE.md, InterneuronUI should be DermalLayer. Container components provide structural support. High 8 High
VisualAstrocyte src/ui/glial/VisualAstrocyte.ts Adipocyte Per SKIN_WEBNN_ARCHITECTURE.md, VisualAstrocyte should be Adipocyte. State storage in skin layer. High 3 Medium
VisualOligodendrocyte src/ui/glial/VisualOligodendrocyte.ts Melanocyte Per SKIN_WEBNN_ARCHITECTURE.md, VisualOligodendrocyte should be Melanocyte. Rendering optimization in skin layer. High 3 Medium
ComponentProps src/ui/types.ts, src/ui/*.ts, src/visualization/*.ts (100+ files) SkinCellProps / ReceptorProps / EffectorProps / DermalLayerProps Generic "ComponentProps" should be system-specific. Use SkinCellProps for base, ReceptorProps for inputs, EffectorProps for actions, DermalLayerProps for containers. High 100+ Critical
ComponentState src/ui/types.ts, src/ui/*.ts, src/visualization/*.ts (100+ files) SkinCellState / ReceptorState / EffectorState / DermalLayerState Generic "ComponentState" should be system-specific. Use SkinCellState for base, ReceptorState for inputs, EffectorState for actions, DermalLayerState for containers. High 100+ Critical
VisualNeuronConfig src/ui/VisualNeuron.ts SkinCellConfig Should match SkinCell naming. Configuration for skin cell components. High 1 Medium
Button src/ui/components/Button.ts TouchReceptor Already exists in Skin system. Button is a touch/click receptor. High 5 High
Input src/ui/components/Input.ts TextReceptor Already exists in Skin system. Input is a text receptor. High 5 High
TestVisualNeuron src/ui/__tests__/VisualNeuron.test.ts TestSkinCell Test class should match production naming. High 1 Low
Select src/ui/components/Select.ts SelectReceptor / ChoiceReceptor Needs medical equivalent. Select is a choice receptor. High 5 High
Form src/ui/components/Form.ts DermalLayer Container component. Form coordinates multiple receptors. High 5 High
Modal src/ui/components/Modal.ts Membrane / Vesicle Medical term for overlay. Membrane separates spaces, Vesicle contains content. High 5 High
Card src/ui/components/Card.ts DermalLayer / Epidermis Container component. Card provides structural container. High 5 High
Alert src/ui/components/Alert.ts AlertReceptor / Nociceptor Medical term for alerts. Nociceptor detects harmful stimuli. High 5 High
Text src/ui/components/Text.ts Keratinocyte / TextCell Medical term for text display. Keratinocyte is a skin cell that displays content. High 5 High
Radio src/ui/components/Radio.ts RadioReceptor / ChoiceReceptor Needs medical equivalent. Radio is a choice receptor. High 5 High
Checkbox src/ui/components/Checkbox.ts CheckReceptor / ToggleReceptor Needs medical equivalent. Checkbox is a toggle receptor. High 5 High
Chart src/visualization/*.ts (4 files) Visualization / Graph Generic "Chart" needs medical equivalent. Visualization is more precise. High 10 High
BarChart src/visualization/BarChart.ts BarVisualization / BarGraph Needs medical equivalent. Bar visualization. High 3 High
LineChart src/visualization/LineChart.ts LineVisualization / LineGraph Needs medical equivalent. Line visualization. High 3 High
PieChart src/visualization/PieChart.ts PieVisualization / PieGraph Needs medical equivalent. Pie visualization. High 3 High
ScatterPlot src/visualization/ScatterPlot.ts ScatterVisualization / ScatterGraph Needs medical equivalent. Scatter visualization. High 3 High
ChartDataPoint src/visualization/types.ts DataPoint / Measurement Needs medical equivalent. Data point in visualization. High 5 Medium
DataBounds src/visualization/types.ts Bounds / Range Needs medical equivalent. Data bounds for scaling. High 5 Medium
CanvasPoint src/visualization/types.ts Coordinate / Point Needs medical equivalent. Canvas coordinate. High 5 Medium
BaseChartProps src/visualization/types.ts BaseVisualizationProps Should match Visualization naming. High 5 Medium
BaseChartState src/visualization/types.ts BaseVisualizationState Should match Visualization naming. High 5 Medium
ChartTheme src/visualization/types.ts VisualizationTheme Should match Visualization naming. High 5 Medium
Server src/theater/server/TheaterServer.ts Organ / System Medical term for server. Organ performs specific function. High 15 Medium
Client src/theater/server/WebSocketBridge.ts Receptor / Effector Medical term for client. Receptor receives, Effector acts. High 10 Medium
Bridge src/theater/server/WebSocketBridge.ts Synapse / Connection Medical term for bridge. Synapse connects neurons. High 5 Medium
WebSocketBridge src/theater/server/WebSocketBridge.ts WebSocketSynapse / WebSocketConnection Medical term for WebSocket bridge. High 5 Medium
TheaterServer src/theater/server/TheaterServer.ts TheaterOrgan / TheaterSystem Medical term for theater server. High 5 Medium
ClientConnection src/theater/server/WebSocketBridge.ts ReceptorConnection / EffectorConnection Medical term for client connection. High 5 Medium
EventBus src/communication/EventBus.ts Heart / Artery Should use Circulatory System terms. Heart is message broker, Artery is outgoing channel. High 3 Medium
Event src/types/index.ts, src/communication/*.ts BloodCell / Signal Should use medical terminology. BloodCell carries messages, Signal is neural communication. High 10 Medium
Router src/respiratory/resources/Router.ts Bronchus / Trachea Medical term for routing. Bronchus branches airways, Trachea is main airway. High 15 Medium
Resource src/respiratory/resources/Resource.ts Oxygen / Nutrient Medical term for external resources. Oxygen/nutrients are external resources. High 20 Medium
ResourcePool src/respiratory/resources/ResourcePool.ts Alveolus / Capillary Medical term for resource pooling. Alveolus exchanges oxygen, Capillary exchanges nutrients. High 10 Medium
Route src/respiratory/resources/Route.ts Bronchiole Medical term for routing path. Bronchiole is small airway branch. High 10 Medium

6. Implementation Guidelines

Naming Conventions

  1. Classes: PascalCase (e.g., SkinCell, TouchReceptor)
  2. Interfaces: PascalCase (e.g., SkinCellConfig, TouchReceptorProps)
  3. Types: PascalCase (e.g., ReceptorType, SkinCellState)
  4. Methods: camelCase (e.g., activate(), receive())
  5. Variables: camelCase (e.g., signalQueue, activationTime)
  6. Constants: UPPER_SNAKE_CASE (e.g., MAX_RETRIES, DEFAULT_TTL)

Migration Strategy

  1. Create New Classes: Create new classes with medical names
  2. Update Imports: Update all imports to use new names
  3. Update Types: Update all type references
  4. Update Tests: Update all test files
  5. Update Documentation: Update all documentation
  6. Deprecate Old Names (if backward compatibility needed): Add deprecated aliases with warnings
  7. Remove Old Names: After migration period, remove deprecated aliases

Backward Compatibility

If backward compatibility is required:

  1. Create Deprecated Aliases:

    /** @deprecated Use SkinCell instead */
export const VisualNeuron = SkinCell;

  2. Add Deprecation Warnings:

    /** @deprecated Use SkinCell instead */
export class VisualNeuron extends SkinCell {
  constructor(...args) {
    console.warn('VisualNeuron is deprecated. Use SkinCell instead.');
    super(...args);
  }
}

  3. Document Migration Path: Create migration guide

  4. Plan Removal Timeline: Set timeline for removing deprecated aliases (e.g., 2 major versions)

7. Risk Mitigation

High Risk Changes

  1. VisualNeuron → SkinCell:

    • Mitigation: Create comprehensive migration guide
    • Mitigation: Provide automated migration script
    • Mitigation: Maintain backward compatibility for 2 major versions

  2. ComponentProps/State → System-specific:

    • Mitigation: Create type aliases for gradual migration
    • Mitigation: Provide migration guide with examples
    • Mitigation: Use TypeScript's type system to catch errors

  3. SensoryNeuron → Receptor:

    • Mitigation: Create migration guide
    • Mitigation: Maintain backward compatibility

Medium Risk Changes

  1. Chart → Visualization:

    • Mitigation: Create migration guide
    • Mitigation: Maintain backward compatibility

  2. EventBus → Heart/Artery:

    • Mitigation: Decide on single term (Heart or Artery)
    • Mitigation: Create migration guide

  3. Router → Bronchus/Trachea:

    • Mitigation: Decide on single term (Bronchus or Trachea)
    • Mitigation: Create migration guide

8. Success Criteria

Phase 1 Success Criteria

  • All VisualNeuron references migrated to SkinCell
  • All SensoryNeuron references migrated to Receptor
  • All MotorNeuron references migrated to Effector
  • All InterneuronUI references migrated to DermalLayer
  • All VisualAstrocyte references migrated to Adipocyte
  • All VisualOligodendrocyte references migrated to Melanocyte
  • All ComponentProps references migrated to system-specific props
  • All ComponentState references migrated to system-specific state
  • All tests pass
  • All type checking passes
  • All exports work correctly
  • Documentation updated

Overall Success Criteria

  • 100% of High Priority changes completed
  • 80% of Medium Priority changes completed
  • All tests pass
  • All type checking passes
  • All builds succeed
  • All exports work correctly
  • Documentation updated
  • No old terminology remains in production code
  • Domain language adherence > 80%

9. Final Critical Review Notice

This plan is now ready for critical review by the architecture and product teams before any implementation begins.

Review Checklist

  • Architecture team reviews terminology choices
  • Product team reviews breaking changes
  • Development team reviews implementation plan
  • Testing team reviews TDD plan
  • Documentation team reviews documentation updates
  • Security team reviews security implications
  • Performance team reviews performance implications

Approval Required

  • Architecture team approval
  • Product team approval
  • Development team approval
  • Testing team approval

Next Steps After Approval

  1. Create detailed migration guides for each phase
  2. Create automated migration scripts (if possible)
  3. Set up backward compatibility (if needed)
  4. Begin Phase 1 implementation
  5. Track progress and update plan as needed

10. Appendices

Appendix A: Official Domain Terminology Glossary

See DOMAIN_TERMINOLOGY_GLOSSARY.md for the complete Official Domain Terminology Glossary.

Appendix B: Complete Audit Findings

See AUDIT_FINDINGS.md for the complete audit findings with all categorized terms.

Appendix C: Prioritized Refactoring Plan

See PRIORITIZED_REFACTORING_PLAN.md for the complete prioritized refactoring plan.

Appendix D: Blast Radius Assessment

See BLAST_RADIUS_ASSESSMENT.md for detailed blast radius assessment for each High Priority change.

Appendix E: Phasing & TDD Plan

See PHASING_AND_TDD_PLAN.md for the complete phasing strategy and TDD/Verification plan.

Document Information

Version: 1.0 Date: 2024 Status: Complete - Ready for Review Author: Domain Terminology & Codebase Refactoring Architect

This Comprehensive Refactoring Playbook is now complete and ready for critical review by the architecture and product teams before any implementation begins.