Domain Terminology Refactoring: Align Codebase with Medical/Biological Terminology

Overview

This issue tracks the comprehensive refactoring of the entire codebase to align with medical/biological domain terminology (Ubiquitous Language). The goal is to ensure 100% adherence to medical/biological terminology throughout the codebase, reflecting the body and all that belongs to it.

Current Status

Health Score: 17% (Critical - Significant terminology drift)

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%)

Critical Areas

UI System (Critical): 12 legacy terms need migration to Skin system
Type System (Critical): ComponentProps/ComponentState used in 100+ files
Visualization System (High): 11+ generic chart terms need medical equivalents
Infrastructure (High): Server/Client/Bridge terms need medical equivalents
Communication (Medium): EventBus/Event need Circulatory System terms
Respiratory System (Medium): Router/Resource/Route need medical equivalents

Reference Documents

All analysis and planning documents have been created:

DOMAIN_TERMINOLOGY_GLOSSARY.md - Official Domain Terminology Glossary
AUDIT_FINDINGS.md - Complete audit findings with categorized terms
PRIORITIZED_REFACTORING_PLAN.md - Prioritized refactoring plan with 100+ changes
BLAST_RADIUS_ASSESSMENT.md - Blast radius assessment for each High Priority change
PHASING_AND_TDD_PLAN.md - 7-phase implementation strategy with TDD plan
COMPREHENSIVE_REFACTORING_PLAYBOOK.md - Complete refactoring playbook

Implementation Phases

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

Critical Changes:

VisualNeuron → SkinCell (42 files affected)
SensoryNeuron → Receptor (25 files affected)
MotorNeuron → Effector (3 files affected)
InterneuronUI → DermalLayer (8 files affected)
VisualAstrocyte → Adipocyte (3 files affected)
VisualOligodendrocyte → Melanocyte (3 files affected)
ComponentProps → System-specific props (SkinCellProps, ReceptorProps, EffectorProps, DermalLayerProps) (100+ files affected)
ComponentState → System-specific state (SkinCellState, ReceptorState, EffectorState, DermalLayerState) (100+ files affected)

Files to Update:

src/ui/VisualNeuron.ts → src/ui/SkinCell.ts
src/ui/SensoryNeuron.ts → src/ui/Receptor.ts
src/ui/MotorNeuron.ts → src/ui/Effector.ts
src/ui/InterneuronUI.ts → src/ui/DermalLayer.ts
src/ui/glial/VisualAstrocyte.ts → src/ui/glial/Adipocyte.ts
src/ui/glial/VisualOligodendrocyte.ts → src/ui/glial/Melanocyte.ts
src/ui/types.ts (add system-specific types)
All files in src/ui/components/ (18 files)
All files in src/visualization/ (10 files)
All test files in src/ui/__tests__/ (4 files)
All story files *.stories.ts (9 files)
src/ui/index.ts (update exports)

Migration Steps:

Create new classes with medical names (SkinCell, Receptor, etc.)
Update all imports (use find/replace carefully)
Update all type references
Update all class extensions
Update exports in index files
Update tests
Update stories
Run full test suite
Verify type checking passes
Verify build succeeds

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

Changes:

Files to Update:

All component files in src/ui/components/
All component test files
All component story files
src/ui/components/index.ts

Phase 3: Visualization System (Week 5-6)

Changes:

Files to Update:

All files in src/visualization/
src/visualization/index.ts

Phase 4: Communication System (Week 7)

Changes:

EventBus → Heart / Artery (decide on single term)
Event → BloodCell / Signal (decide on single term)

Files to Update:

src/communication/EventBus.ts
src/communication/index.ts
src/index.ts
All files using EventBus

Phase 5: Respiratory System (Week 8-9)

Changes:

Files to Update:

All files in src/respiratory/
src/respiratory/index.ts

Phase 6: Infrastructure Terms (Week 10)

Changes:

Files to Update:

All files in src/theater/server/
src/theater/index.ts

Phase 7: Tools & Testing Terms (Week 11)

Changes:

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

Files to Update:

src/tools/dependency-auditor.ts
Test files (optional - can keep Test/Mock for compatibility)

Planned Features & Components (Future Implementation)

This section lists all planned features and components from the roadmap and GitHub issues that need to use medical/biological terminology from the start.

Phase 3: Muscular System (Planned)

Core Components:

Muscle (base class for operations) - Already correct
MuscleGroup (operation composition) - Already correct
MuscleMemory (operation caching) - Already correct
MuscleCoordination (orchestration) - Already correct
Tendon (integration points) - Already correct

Built-in Muscles:

ComputeMuscle → ComputeMuscle (already correct)
TransformMuscle → TransformMuscle (already correct)
AggregateMuscle → AggregateMuscle (already correct)
FilterMuscle → FilterMuscle (already correct)
SortMuscle → SortMuscle (already correct)
MapMuscle → MapMuscle (already correct)
ReduceMuscle → ReduceMuscle (already correct)

Phase 4: Circulatory System (Planned)

Core Components:

Heart (central message broker) - Already correct
Artery (outbound data streams) - Already correct
Vein (inbound data streams) - Already correct
Capillary (micro-channels) - Already correct
BloodCell (message envelope) - Already correct
Hemoglobin (data carrier) - Already correct

Phase 5: Respiratory System (Planned)

Core Components:

Lung (HTTP client/server) - Already correct
Alveoli (API endpoints) - Already correct
Diaphragm (breathing control) - Already correct
Bronchi (protocol adapters) - Already correct
Oxygen (external resources) - Already correct
CarbonDioxide (error exhaust) - Already correct

Protocol Adapters:

RestAdapter → RestBronchus
GraphQLAdapter → GraphQLBronchus
WebSocketAdapter → WebSocketBronchus
SSEAdapter → SSEBronchus
gRPCAdapter → gRPCBronchus

Phase 6: Immune System (Planned)

Core Components:

WhiteBloodCell (threat detection) - Already correct
Antibody (authentication) - Already correct
TCell (authorization) - Already correct
BCell (error memory) - Already correct
Macrophage (cleanup & sanitization) - Already correct
Lymph (security context) - Already correct
Vaccine (security configuration) - Already correct

Phase 7: Endocrine System (Planned)

Core Components:

Gland (configuration provider) - Already correct
Hormone (configuration value) - Already correct
Receptor (config consumer) - Already correct (but conflicts with Skin Receptor - decide on naming)
Hypothalamus (feature flags) - Already correct
Pituitary (central control) - Already correct
Thyroid (performance tuning) - Already correct

Phase 8: Digestive System (Planned)

Core Components:

Mouth (data ingestion) - Already correct
Esophagus (data pipeline) - Already correct
Stomach (data processing) - Already correct
Intestine (data transformation) - Already correct
Liver (data cleansing) - Already correct
Enzyme (transformation functions) - Already correct

Phase 9: Skin Layer - Advanced Components (Planned)

Form Controls:

Select / Dropdown → SelectReceptor / ChoiceReceptor
Checkbox → CheckReceptor / ToggleReceptor
Radio → RadioReceptor / ChoiceReceptor
Toggle / Switch → ToggleReceptor / SwitchReceptor
Slider / Range → RangeReceptor / SliderReceptor
DatePicker → DateReceptor / TemporalReceptor
TimePicker → TimeReceptor / TemporalReceptor
ColorPicker → ColorReceptor / VisualReceptor
FileUpload → FileReceptor / UploadReceptor

Data Display:

Table → DataTable / GridCell / TabularCell
TreeView → TreeCell / HierarchicalCell
List → ListCell / CollectionCell
Grid → GridCell / MatrixCell
Timeline → TimelineCell / ChronologicalCell
Accordion → AccordionCell / ExpandableCell
Tabs → TabCell / TabularCell
Breadcrumbs → BreadcrumbCell / NavigationCell

Navigation:

Menu / DropdownMenu → MenuCell / NavigationCell
Sidebar → SidebarCell / LateralCell
Navbar → NavbarCell / NavigationCell
Pagination → PaginationCell / PageNavigationCell
Stepper / Wizard → StepperCell / ProgressiveCell
CommandPalette → CommandCell / PaletteCell

Feedback:

Modal / Dialog → Membrane / Vesicle
Toast / Notification → NotificationCell / AlertCell
Alert → AlertReceptor / Nociceptor
ProgressBar → ProgressCell / ProgressIndicator
SkeletonLoader → SkeletonCell / LoadingCell
Spinner → SpinnerCell / LoadingCell
Badge → BadgeCell / IndicatorCell
Tooltip → TooltipCell / HintCell
Popover → PopoverCell / OverlayCell

Layout:

Grid → GridCell / MatrixCell
Flex / FlexContainer → FlexCell / FlexibleCell
Stack → StackCell / LayeredCell
Divider → DividerCell / SeparatorCell
Spacer → SpacerCell / EmptyCell
Container → ContainerCell / WrapperCell
Card → CardCell / Epidermis / DermalLayer

Advanced:

Chart → Visualization (see Phase 3)
CodeEditor → CodeCell / EditorCell
RichTextEditor → RichTextCell / EditorCell
MarkdownViewer → MarkdownCell / DocumentCell
PDFViewer → PDFCell / DocumentCell
ImageCropper → ImageCell / ImageProcessor
Autocomplete → AutocompleteReceptor / SuggestReceptor
Combobox → ComboboxReceptor / SelectReceptor

Phase 10: Observability & Monitoring (Planned)

Core Components:

SensoryNerve (telemetry collection) - Already correct
HealthMonitor - Already correct
MetricsRegistry - Already correct
Dashboard → DashboardCell / MonitorCell

Phase 11: Developer Experience & Tooling (Planned)

CLI Components:

CLI → CLI (keep as-is, or use CommandLineInterface)
REPL → REPL (keep as-is, or use InteractiveShell)
CodeGenerator → CodeGenerator / CodeSynthesizer
MigrationTool → MigrationTool / MigrationAssistant

Build Tools:

BuildTool → BuildTool / CompilationTool
BundleAnalyzer → BundleAnalyzer / BundleInspector
CodeSplitter → CodeSplitter / CodeDivider

Debug Tools:

Debugger → Debugger / DiagnosticTool
StateInspector → StateInspector / StateExplorer
PerformanceProfiler → PerformanceProfiler / PerformanceAnalyzer
MemoryLeakDetector → MemoryLeakDetector / MemoryAnalyzer

Phase 12: Performance Optimization (Planned)

Optimization Components:

JITCompiler → JITCompiler / RuntimeCompiler
ObjectPool → ObjectPool / ObjectCache
MemoryArena → MemoryArena / MemoryPool
WorkerThreadPool → WorkerThreadPool / ThreadPool
CacheStrategy → CacheStrategy / CachingStrategy
LazyLoader → LazyLoader / DeferredLoader
Compressor → Compressor / CompressionTool

Phase 13: Advanced Data Patterns (Planned)

Core Patterns:

CQRS → CQRS (keep as-is, or use CommandQuerySeparation)
EventStore → EventStore / EventRepository
EventStream → EventStream / EventFlow
Saga → Saga / TransactionOrchestrator
Outbox → Outbox / MessageOutbox
MaterializedView → MaterializedView / CachedView

Phase 14: Real-time Collaboration (Planned)

Core Components:

CRDT → CRDT (keep as-is, or use ConflictFreeReplicatedDataType)
OperationalTransform → OperationalTransform / OperationTransformer
PresenceTracker → PresenceTracker / PresenceMonitor
SyncEngine → SyncEngine / SynchronizationEngine
CollaborativeEditor → CollaborativeEditor / SharedEditor

Phase 15: AI & Machine Learning Integration (Planned)

Core Components:

MLPipeline → MLPipeline / MachineLearningPipeline
ModelServing → ModelServing / ModelServer
ModelVersioning → ModelVersioning / ModelRegistry
AutoML → AutoML / AutomatedML
Explainability → Explainability / ModelExplanation

WebNN Integration:

WebNN → WebNN (keep as-is)
NeuralNetwork → NeuralNetwork / NeuralCircuit (already exists)
ModelOptimizer → ModelOptimizer / ModelCompressor
HardwareAccelerator → HardwareAccelerator / AccelerationEngine

Pre-trained Models:

TextClassifier → TextClassifier / TextAnalysisModel
SentimentAnalyzer → SentimentAnalyzer / SentimentModel
NamedEntityRecognizer → NamedEntityRecognizer / EntityExtractor
ImageClassifier → ImageClassifier / ImageAnalysisModel
ObjectDetector → ObjectDetector / ObjectRecognitionModel

Intelligent Features:

SmartAutocomplete → SmartAutocomplete / IntelligentAutocomplete
ContentRecommender → ContentRecommender / RecommendationEngine
AnomalyDetector → AnomalyDetector / AnomalyRecognition
PredictiveAnalytics → PredictiveAnalytics / PredictionEngine
PersonalizationEngine → PersonalizationEngine / PersonalizationSystem

Phase 16: Edge Computing & Distributed Systems (Planned)

Core Components:

EdgeRuntime → EdgeRuntime / EdgeExecutionEnvironment
DistributedCache → DistributedCache / DistributedMemory
ServiceMesh → ServiceMesh / ServiceNetwork
GlobalStateSync → GlobalStateSync / GlobalSynchronization
EdgeOptimizer → EdgeOptimizer / EdgeOptimizationEngine
DistributedTracing → DistributedTracing / DistributedTraceSystem

Deployment Targets:

CloudflareWorkers → CloudflareWorkers / CloudflareEdge
AWSLambda → AWSLambda / LambdaFunction
VercelEdgeFunctions → VercelEdgeFunctions / VercelEdge
DenoDeploy → DenoDeploy / DenoEdge

Phase 17: Testing & Quality Assurance Framework (Planned)

Testing Tools:

TestUtilities → TestUtilities / TestingUtilities
MockFactory → MockFactory / SpecimenFactory
FixtureGenerator → FixtureGenerator / TestDataGenerator
SnapshotTester → SnapshotTester / SnapshotValidator
VisualRegressionTester → VisualRegressionTester / VisualTester

E2E Testing:

E2ETester → E2ETester / EndToEndTester
PlaywrightIntegration → PlaywrightIntegration / PlaywrightAdapter
PuppeteerIntegration → PuppeteerIntegration / PuppeteerAdapter
VisualTester → VisualTester / VisualRegressionTester
AccessibilityTester → AccessibilityTester / A11yTester

Load Testing:

LoadTester → LoadTester / LoadTestingTool
StressTester → StressTester / StressTestingTool
SoakTester → SoakTester / SoakTestingTool
SpikeTester → SpikeTester / SpikeTestingTool
ScalabilityTester → ScalabilityTester / ScalabilityTestingTool

Contract Testing:

ContractTester → ContractTester / ContractValidator
APIContractTester → APIContractTester / APIContractValidator
ConsumerDrivenContract → ConsumerDrivenContract / ConsumerContract

Chaos Engineering:

ChaosEngineer → ChaosEngineer / ChaosTestingTool
FailureInjector → FailureInjector / FailureSimulator
LatencyInjector → LatencyInjector / LatencySimulator
NetworkPartitionSimulator → NetworkPartitionSimulator / PartitionSimulator
ResourceExhaustionSimulator → ResourceExhaustionSimulator / ResourceSimulator

Test Coverage:

CoverageAnalyzer → CoverageAnalyzer / CoverageTool
MutationTester → MutationTester / MutationTestingTool
PropertyBasedTester → PropertyBasedTester / PropertyTester

Phase 18: Enterprise Features (Planned)

Enterprise Components:

MultiTenancy → MultiTenancy / TenantIsolation
TenantIsolation → TenantIsolation / TenantSeparation
AuditTrail → AuditTrail / AuditLog
ComplianceTool → ComplianceTool / ComplianceManager
GDPRCompliance → GDPRCompliance / GDPRManager
HIPAACompliance → HIPAACompliance / HIPAAManager
SOC2Compliance → SOC2Compliance / SOC2Manager

Advanced Authorization:

HierarchicalRoles → HierarchicalRoles / RoleHierarchy
DelegatedAdministration → DelegatedAdministration / DelegationSystem
TimeBasedAccess → TimeBasedAccess / TemporalAccess
LocationBasedAccess → LocationBasedAccess / SpatialAccess
RiskBasedAuthentication → RiskBasedAuthentication / RiskAssessment

Reporting:

UsageReporter → UsageReporter / UsageAnalytics
PerformanceReporter → PerformanceReporter / PerformanceAnalytics
SecurityReporter → SecurityReporter / SecurityAnalytics
ComplianceReporter → ComplianceReporter / ComplianceAnalytics
CustomReportBuilder → CustomReportBuilder / ReportGenerator
ScheduledReporter → ScheduledReporter / ScheduledReportGenerator

Billing & Metering:

UsageTracker → UsageTracker / UsageMonitor
QuotaManager → QuotaManager / QuotaSystem
RateLimiter → RateLimiter / RateController
BillingIntegrator → BillingIntegrator / BillingAdapter
InvoiceGenerator → InvoiceGenerator / InvoiceCreator
PaymentProcessor → PaymentProcessor / PaymentHandler

SLA Management:

SLOManager → SLOManager / ServiceLevelManager
SLITracker → SLITracker / ServiceLevelTracker
ErrorBudget → ErrorBudget / ErrorAllowance
UptimeMonitor → UptimeMonitor / AvailabilityMonitor
IncidentManager → IncidentManager / IncidentSystem
PostMortemTemplate → PostMortemTemplate / PostMortemGenerator

Phase 19: Plugin Ecosystem (Planned)

Plugin System:

Plugin → Plugin / Extension
PluginInterface → PluginInterface / ExtensionInterface
PluginLifecycle → PluginLifecycle / ExtensionLifecycle
PluginIsolation → PluginIsolation / ExtensionIsolation
PluginSandbox → PluginSandbox / ExtensionSandbox
PluginDependencies → PluginDependencies / ExtensionDependencies
PluginVersioning → PluginVersioning / ExtensionVersioning
PluginHotReload → PluginHotReload / ExtensionHotReload

Plugin APIs:

CoreExtensionPoint → CoreExtensionPoint / CoreHook
UIExtensionPoint → UIExtensionPoint / UIHook
DataExtensionPoint → DataExtensionPoint / DataHook
CLIExtensionPoint → CLIExtensionPoint / CLIHook
BuildExtensionPoint → BuildExtensionPoint / BuildHook

Plugin Development:

PluginCLIGenerator → PluginCLIGenerator / ExtensionGenerator
PluginTestingFramework → PluginTestingFramework / ExtensionTestingFramework
PluginDebugger → PluginDebugger / ExtensionDebugger
PluginDocumentationGenerator → PluginDocumentationGenerator / ExtensionDocumentationGenerator

Plugin Distribution:

PluginMarketplace → PluginMarketplace / ExtensionMarketplace
PluginDiscovery → PluginDiscovery / ExtensionDiscovery
PluginRatings → PluginRatings / ExtensionRatings
PluginReviews → PluginReviews / ExtensionReviews
PluginAnalytics → PluginAnalytics / ExtensionAnalytics

Official Plugins:

DatabasePlugin → DatabasePlugin / DatabaseAdapter
StoragePlugin → StoragePlugin / StorageAdapter
AuthPlugin → AuthPlugin / AuthAdapter
PaymentPlugin → PaymentPlugin / PaymentAdapter
EmailPlugin → EmailPlugin / EmailAdapter
AnalyticsPlugin → AnalyticsPlugin / AnalyticsAdapter

Plugin Security:

PermissionSystem → PermissionSystem / CapabilitySystem
CapabilityBasedSecurity → CapabilityBasedSecurity / CapabilitySecurity
CodeSigning → CodeSigning / CodeVerification
SecurityAudit → SecurityAudit / SecurityReview
VulnerabilityScanner → VulnerabilityScanner / VulnerabilityDetector

Phase 20: Advanced UI & Visualization (Planned)

Visualization Components:

Canvas-based Rendering:

CanvasRenderer → CanvasRenderer / CanvasEngine
WebGLRenderer → WebGLRenderer / WebGLEngine
GPUAccelerator → GPUAccelerator / GPUEngine
CustomShader → CustomShader / ShaderProgram
ParticleSystem → ParticleSystem / ParticleEngine

Data Visualization:

GeographicMap → GeographicMap / MapVisualization
NetworkTopology → NetworkTopology / TopologyVisualization
FlowDiagram → FlowDiagram / FlowVisualization
SankeyDiagram → SankeyDiagram / SankeyVisualization
ChordDiagram → ChordDiagram / ChordVisualization
ForceDirectedGraph → ForceDirectedGraph / ForceGraph

Interactive Features:

ZoomAndPan → ZoomAndPan / ZoomController
BrushSelection → BrushSelection / SelectionBrush
Tooltip → Tooltip / HintCell (see Phase 9)
Crosshairs → Crosshairs / CrosshairIndicator
Annotations → Annotations / AnnotationLayer
ExportToImage → ExportToImage / ImageExporter
ExportToPDF → ExportToPDF / PDFExporter

Animation System:

AnimationSystem → AnimationSystem / AnimationEngine
SpringPhysics → SpringPhysics / SpringAnimation
EasingFunctions → EasingFunctions / EasingCurves
StaggeredAnimations → StaggeredAnimations / SequentialAnimations
GestureAnimations → GestureAnimations / GestureBasedAnimations
ScrollTriggeredAnimations → ScrollTriggeredAnimations / ScrollAnimations
PageTransitions → PageTransitions / TransitionAnimations

3D Rendering:

WebGLRenderer → WebGLRenderer / WebGLEngine (duplicate)
ThreeJSIntegration → ThreeJSIntegration / ThreeJSAdapter
3DModelLoader → 3DModelLoader / ModelLoader
SceneManager → SceneManager / SceneController
CameraControls → CameraControls / CameraController
Lighting → Lighting / LightSystem
Materials → Materials / MaterialSystem
Textures → Textures / TextureSystem

Advanced UI Patterns:

VirtualScrolling → VirtualScrolling / VirtualList
InfiniteScrolling → InfiniteScrolling / InfiniteList
Windowing → Windowing / WindowManager
MasonryLayout → MasonryLayout / MasonryGrid
DragAndDrop → DragAndDrop / DragDropSystem
GestureRecognition → GestureRecognition / GestureSystem
TouchInteractions → TouchInteractions / TouchSystem
VoiceInteractions → VoiceInteractions / VoiceSystem

Theater System (Planned - Phase 6)

Core Components:

Microscope Tools:

SignalTracer → SignalTracer / SignalTracker
StateExplorer → StateExplorer / StateInspector
PerformanceProfiler → PerformanceProfiler / PerformanceAnalyzer
HealthMonitor → HealthMonitor / HealthChecker

Laboratory Components:

PetriDish → PetriDish / TestContainer
Culture → Culture / TestEnvironment
Experiment - Already correct

Atlas Components:

ComponentCatalogue → ComponentCatalogue / ComponentRegistry
Diagram → Diagram / Visualization
Protocol - Already correct

Server & Hot Reload:

TheaterServer → TheaterOrgan / TheaterSystem (see Phase 6)
HotReload → Regeneration / Renewal (see Phase 6)
WebSocketCommunication → WebSocketSynapse / WebSocketConnection (see Phase 6)

CLI & Configuration:

TheaterCLI → TheaterCLI / TheaterCommandLine
TheaterConfiguration → TheaterConfiguration / TheaterConfig
SpecimenFileLoader → SpecimenFileLoader / SpecimenLoader

Planned UI Components (From GitHub Issues)

Manufacturing Components:

QuantumAssembly → QuantumAssembly / MultiPathAssembly (keep as-is or rename)
NeuralProductionLine → NeuralProductionLine / IntelligentProductionLine (keep as-is or rename)
SynapticQuality → SynapticQuality / NeuralQualityControl (keep as-is or rename)

Energy Components:

NeuralEnergyMonitor → NeuralEnergyMonitor / IntelligentEnergyMonitor (keep as-is or rename)
SynapticGridControl → SynapticGridControl / NeuralGridControl (keep as-is or rename)
QuantumEnergyOptimizer → QuantumEnergyOptimizer / MultiSourceEnergyOptimizer (keep as-is or rename)

Agriculture Components:

QuantumHarvest → QuantumHarvest / MultiScenarioHarvest (keep as-is or rename)

Note on "Quantum" and "Neural" Prefixes:

These components use "Quantum" and "Neural" prefixes which may not align with medical terminology
Consider renaming to more medical terms or keeping as domain-specific terminology
Decision needed: Should "Quantum" → "Multi" / "Parallel" / "Concurrent"?
Decision needed: Should "Neural" → "Intelligent" / "Adaptive" / keep as-is (since it's part of Nervous System)?

Implementation Guidelines

Naming Conventions

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

Migration Strategy

Create New Classes: Create new classes with medical names
Update Imports: Update all imports to use new names
Update Types: Update all type references
Update Tests: Update all test files
Update Documentation: Update all documentation
Backward Compatibility (if needed): Add deprecated aliases with warnings
Remove Old Names: After migration period, remove deprecated aliases

Backward Compatibility

For critical breaking changes, consider adding deprecated aliases:

/** @deprecated Use SkinCell instead. Will be removed in v2.0.0 */
export const VisualNeuron = SkinCell;

/** @deprecated Use SkinCell instead. Will be removed in v2.0.0 */
export class VisualNeuron extends SkinCell {
  constructor(...args: ConstructorParameters<typeof SkinCell>) {
    console.warn('VisualNeuron is deprecated. Use SkinCell instead.');
    super(...args);
  }
}

Testing Requirements

Before Each Phase

Write tests asserting new terminology (if applicable)
Document expected behavior
Review test coverage

During Each Phase

Update test imports to use new names
Update test class names (TestVisualNeuron → TestSkinCell)
Update test type references
Update test assertions
Run tests frequently to catch issues early

After Each Phase

Run full test suite: npm test
Verify all tests pass: npm test -- --passWithNoTests
Check test coverage: npm run test:coverage
Verify type checking: npm run type-check
Verify build succeeds: npm run build
Verify linting passes: npm run lint
Verify no old terminology remains (grep for old names)
Verify exports work correctly
Update documentation

Acceptance Criteria

Phase 1 (Critical)

Overall Success Criteria

Verification Checklist (Per Phase)

After completing each phase, verify:

Risk Mitigation

High Risk Changes

VisualNeuron → SkinCell (42 files, Critical)
- Create comprehensive migration guide
- Consider backward compatibility aliases
- Test thoroughly before merging
ComponentProps/State → System-specific (100+ files, Critical)
- Create type aliases for gradual migration
- Use TypeScript's type system to catch errors
- Test type checking thoroughly
SensoryNeuron → Receptor (25 files, Critical)
- Create migration guide
- Consider backward compatibility

Testing Strategy

Before Refactoring: Write tests asserting new terminology
During Refactoring: Update tests as you go
After Refactoring: Run full test suite, verify coverage

Decision Points

Before starting, decide on these ambiguous terms:

EventBus → Heart or Artery?
- Recommendation: Use Heart (already exists, is message broker)
Event → BloodCell or Signal?
- Recommendation: Use BloodCell for messages, Signal for neural communication
Router → Bronchus or Trachea?
- Recommendation: Use Bronchus (branches airways, more flexible)
Resource → Oxygen or Nutrient?
- Recommendation: Use Oxygen (more specific, fits respiratory metaphor)
ResourcePool → Alveolus or Capillary?
- Recommendation: Use Alveolus (exchanges oxygen, fits pooling metaphor)
Server → Organ or System?
- Recommendation: Use Organ (more specific, fits medical metaphor)
Client → Receptor or Effector?
- Recommendation: Use Receptor (receives, fits client role)
Bridge → Synapse or Connection?
- Recommendation: Use Synapse (connects neurons, fits bridge role)
HotReload → Regeneration or Renewal?
- Recommendation: Use Regeneration (cells regenerate, fits hot reload)

Notes

Do NOT break existing functionality - All tests must pass
Do NOT introduce linting errors - All linting must pass
Do NOT break type checking - All type checking must pass
Do NOT break builds - All builds must succeed
Consider backward compatibility - Add deprecated aliases if needed
Update documentation - Keep documentation in sync
Test thoroughly - Run full test suite after each phase
Commit frequently - Small, focused commits per change
Review carefully - Code review before merging

Project Rename Analysis: Synapse → Full Body Metaphor

Current State

Current Name: "Synapse Framework"

Package: @synapse-framework/core
CLI: synapse
Repository: synapse
Description: "Neural-inspired TypeScript framework"

The Problem

"Synapse" is too narrow - it only refers to the Nervous System (a synapse is a connection between neurons). However, the framework has expanded to include the entire body metaphor:

Current Systems (Implemented + Planned):

✅ Nervous System (Synapse is part of this)
✅ Skeletal System (Bone, Schema, validation)
✅ Skin Layer (SkinCell, Receptor, Effector)
⚪ Muscular System (Muscle, MuscleGroup, operations)
⚪ Circulatory System (Heart, Artery, Vein, BloodCell)
⚪ Respiratory System (Lung, Alveoli, Diaphragm, Bronchi)
⚪ Immune System (TCell, BCell, Macrophage, WhiteBloodCell)
⚪ Endocrine System (Gland, Hormone, Receptor)
⚪ Digestive System (Mouth, Esophagus, Stomach, Intestine)
⚪ Theater System (Stage, Specimen, Laboratory, Experiment)

Conclusion: The framework is about the entire body/organism, not just the nervous system.

Rename Options

Option 1: Anatomy Framework ⭐ (Recommended)

Pros:

✅ Reflects the entire body structure
✅ Medical/biological terminology
✅ Clear and professional
✅ "Anatomy" = study of body structure (perfect fit)
✅ Package: @anatomy-framework/core
✅ CLI: anatomy

Cons:

⚠️ Breaking change for existing users
⚠️ Repository rename needed
⚠️ Package name change needed

Tagline: "A TypeScript framework inspired by human anatomy"

Option 2: Organism Framework

Pros:

✅ Reflects the entire living system
✅ Biological terminology
✅ Emphasizes systems working together
✅ Package: @organism-framework/core
✅ CLI: organism

Cons:

⚠️ Less specific than "Anatomy"
⚠️ Might sound too generic
⚠️ Breaking change

Tagline: "A TypeScript framework inspired by biological organisms"

Option 3: Physiology Framework

Pros:

✅ Reflects body functions (physiology = how body works)
✅ Medical terminology
✅ Emphasizes systems and their functions
✅ Package: @physiology-framework/core
✅ CLI: physiology

Cons:

⚠️ Less well-known term than "Anatomy"
⚠️ Breaking change
⚠️ Might be confused with medical education

Tagline: "A TypeScript framework inspired by human physiology"

Option 4: Body Framework

Pros:

✅ Simple and clear
✅ Immediately understandable
✅ Package: @body-framework/core
✅ CLI: body

Cons:

⚠️ Too generic (could be confused with CSS frameworks)
⚠️ Less professional sounding
⚠️ Breaking change

Tagline: "A TypeScript framework inspired by the human body"

Option 5: Keep "Synapse" but Rebrand

Pros:

✅ No breaking changes
✅ Existing brand recognition
✅ Can expand meaning: "Synapse = connection between all body systems"

Cons:

⚠️ Still narrow - synapse is specifically nervous system
⚠️ Doesn't reflect full body metaphor
⚠️ Might confuse users when they see "Muscle", "Heart", "Lung" but framework is called "Synapse"

Tagline: "A TypeScript framework inspired by biological systems" (vague)

Impact Assessment

Breaking Changes Required:

Package Name: @synapse-framework/core → @anatomy-framework/core
- All imports need updating
- NPM package republish
- Documentation updates
CLI Command: synapse → anatomy
- All scripts need updating
- Documentation updates
- User migration guide needed
Repository Name: synapse → anatomy (or anatomy-framework)
- GitHub repository rename
- All URLs change
- CI/CD updates
- Badge URLs update
Documentation:
- All README files
- All code examples
- All API documentation
- All guides and tutorials
Code References:
- Framework metadata in src/index.ts
- All documentation files
- All markdown files

Migration Strategy

If renaming, recommend:

Phase 1: Create new package name, keep old one as alias

{
  "name": "@anatomy-framework/core",
  "synapse": "@anatomy-framework/core"  // Alias
}

Phase 2: Update all documentation to use new name
Phase 3: Deprecate old package name (6 months)
Phase 4: Remove old package name

Recommendation

Recommendation: Rename to "Anatomy Framework" ⭐

Rationale:

Accurate: Reflects the entire body metaphor, not just nervous system
Professional: Medical terminology that's well-understood
Clear: "Anatomy" = study of body structure (perfect fit)
Consistent: Aligns with all the body system terminology already in use
Future-proof: Works for all planned systems

Timing:

Best time: Before v1.0.0 (currently v0.1.0)
Reason: Less breaking change impact before major release
Strategy: Do it now while still in early development

Alternative if keeping current name:

Keep "Synapse" but update tagline to: "A TypeScript framework inspired by biological systems"
Add note in README: "Synapse connects all body systems, just as synapses connect neurons"
Accept that name is narrower than scope

Decision Matrix

Option	Accuracy	Professional	Breaking Change	Brand Recognition	Score
Anatomy	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⚠️⚠️⚠️	⭐⭐	18/20
Organism	⭐⭐⭐⭐	⭐⭐⭐⭐	⚠️⚠️⚠️	⭐	15/20
Physiology	⭐⭐⭐⭐	⭐⭐⭐⭐	⚠️⚠️⚠️	⭐	14/20
Body	⭐⭐⭐	⭐⭐	⚠️⚠️⚠️	⭐	10/20
Keep Synapse	⭐⭐	⭐⭐⭐⭐	✅	⭐⭐⭐⭐	13/20

Next Steps

If proceeding with rename:

Update package.json with new name
Update all documentation files
Update repository name (GitHub settings)
Create migration guide for users
Update CI/CD configurations
Publish new package to NPM
Deprecate old package (6 months notice)

Questions to Consider

Is the project mature enough for a rename? (Currently v0.1.0 - YES, perfect time)
How many users would be affected? (Check GitHub stars, NPM downloads)
Is brand recognition important? (If yes, consider keeping "Synapse")
Do we want to emphasize "body" or "systems"? (Anatomy = body, Organism = systems)

Reference

See COMPREHENSIVE_REFACTORING_PLAYBOOK.md for complete details. See PROJECT_RENAME_ANALYSIS.md for detailed project rename analysis.

Status: Ready for Implementation
Priority: High
Estimated Effort: 11 weeks (7 phases) + Project rename (if decided)
Assignee: TBD
Labels: refactoring, domain-terminology, breaking-change, high-priority

FilesExpand file tree

GITHUB_ISSUE_DOMAIN_TERMINOLOGY_REFACTORING.md

Latest commit

History

GITHUB_ISSUE_DOMAIN_TERMINOLOGY_REFACTORING.md

File metadata and controls

Domain Terminology Refactoring: Align Codebase with Medical/Biological Terminology

Overview

Current Status

Critical Areas

Reference Documents

Implementation Phases

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

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

Phase 3: Visualization System (Week 5-6)

Phase 4: Communication System (Week 7)

Phase 5: Respiratory System (Week 8-9)

Phase 6: Infrastructure Terms (Week 10)

Phase 7: Tools & Testing Terms (Week 11)

Planned Features & Components (Future Implementation)

Phase 3: Muscular System (Planned)

Phase 4: Circulatory System (Planned)

Phase 5: Respiratory System (Planned)

Phase 6: Immune System (Planned)

Phase 7: Endocrine System (Planned)

Phase 8: Digestive System (Planned)

Phase 9: Skin Layer - Advanced Components (Planned)

Phase 10: Observability & Monitoring (Planned)

Phase 11: Developer Experience & Tooling (Planned)

Phase 12: Performance Optimization (Planned)

Phase 13: Advanced Data Patterns (Planned)

Phase 14: Real-time Collaboration (Planned)

Phase 15: AI & Machine Learning Integration (Planned)

Phase 16: Edge Computing & Distributed Systems (Planned)

Phase 17: Testing & Quality Assurance Framework (Planned)

Phase 18: Enterprise Features (Planned)

Phase 19: Plugin Ecosystem (Planned)

Phase 20: Advanced UI & Visualization (Planned)

Theater System (Planned - Phase 6)

Planned UI Components (From GitHub Issues)

Implementation Guidelines

Naming Conventions

Migration Strategy

Backward Compatibility

Testing Requirements

Before Each Phase

During Each Phase

After Each Phase

Acceptance Criteria

Phase 1 (Critical)

Overall Success Criteria

Verification Checklist (Per Phase)

Risk Mitigation

High Risk Changes

Testing Strategy

Decision Points

Notes

Project Rename Analysis: Synapse → Full Body Metaphor

Current State

The Problem

Rename Options

Option 1: Anatomy Framework ⭐ (Recommended)

Option 2: Organism Framework

Option 3: Physiology Framework

Option 4: Body Framework

Option 5: Keep "Synapse" but Rebrand

Impact Assessment

Migration Strategy

Recommendation

Decision Matrix

Next Steps

Questions to Consider

Reference