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 GlossaryAUDIT_FINDINGS.md - Complete audit findings with categorized termsPRIORITIZED_REFACTORING_PLAN.md - Prioritized refactoring plan with 100+ changesBLAST_RADIUS_ASSESSMENT.md - Blast radius assessment for each High Priority changePHASING_AND_TDD_PLAN.md - 7-phase implementation strategy with TDD planCOMPREHENSIVE_REFACTORING_PLAYBOOK.md - Complete refactoring playbook
Implementation Phases
Phase 1: Core UI System Terminology (Week 1-2) - START HERE
Critical Changes:
Files to Update:
src/ui/VisualNeuron.ts → src/ui/SkinCell.tssrc/ui/SensoryNeuron.ts → src/ui/Receptor.tssrc/ui/MotorNeuron.ts → src/ui/Effector.tssrc/ui/InterneuronUI.ts → src/ui/DermalLayer.tssrc/ui/glial/VisualAstrocyte.ts → src/ui/glial/Adipocyte.tssrc/ui/glial/VisualOligodendrocyte.ts → src/ui/glial/Melanocyte.tssrc/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:
Files to Update:
src/communication/EventBus.tssrc/communication/index.tssrc/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:
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:
Built-in Muscles:
Phase 4: Circulatory System (Planned)
Core Components:
Phase 5: Respiratory System (Planned)
Core Components:
Protocol Adapters:
Phase 6: Immune System (Planned)
Core Components:
Phase 7: Endocrine System (Planned)
Core Components:
Phase 8: Digestive System (Planned)
Core Components:
Phase 9: Skin Layer - Advanced Components (Planned)
Form Controls:
Data Display:
Navigation:
Feedback:
Layout:
Advanced:
Phase 10: Observability & Monitoring (Planned)
Core Components:
Phase 11: Developer Experience & Tooling (Planned)
CLI Components:
Build Tools:
Debug Tools:
Phase 12: Performance Optimization (Planned)
Optimization Components:
Phase 13: Advanced Data Patterns (Planned)
Core Patterns:
Phase 14: Real-time Collaboration (Planned)
Core Components:
Phase 15: AI & Machine Learning Integration (Planned)
Core Components:
WebNN Integration:
Pre-trained Models:
Intelligent Features:
Phase 16: Edge Computing & Distributed Systems (Planned)
Core Components:
Deployment Targets:
Phase 17: Testing & Quality Assurance Framework (Planned)
Testing Tools:
E2E Testing:
Load Testing:
Contract Testing:
Chaos Engineering:
Test Coverage:
Phase 18: Enterprise Features (Planned)
Enterprise Components:
Advanced Authorization:
Reporting:
Billing & Metering:
SLA Management:
Phase 19: Plugin Ecosystem (Planned)
Plugin System:
Plugin APIs:
Plugin Development:
Plugin Distribution:
Official Plugins:
Plugin Security:
Phase 20: Advanced UI & Visualization (Planned)
Visualization Components:
Canvas-based Rendering:
Data Visualization:
Interactive Features:
Animation System:
3D Rendering:
Advanced UI Patterns:
Theater System (Planned - Phase 6)
Core Components:
Microscope Tools:
Laboratory Components:
Atlas Components:
Server & Hot Reload:
CLI & Configuration:
Planned UI Components (From GitHub Issues)
Manufacturing Components:
Energy Components:
Agriculture Components:
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
During Each Phase
After Each Phase
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
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)
Critical Areas
Reference Documents
All analysis and planning documents have been created:
DOMAIN_TERMINOLOGY_GLOSSARY.md- Official Domain Terminology GlossaryAUDIT_FINDINGS.md- Complete audit findings with categorized termsPRIORITIZED_REFACTORING_PLAN.md- Prioritized refactoring plan with 100+ changesBLAST_RADIUS_ASSESSMENT.md- Blast radius assessment for each High Priority changePHASING_AND_TDD_PLAN.md- 7-phase implementation strategy with TDD planCOMPREHENSIVE_REFACTORING_PLAYBOOK.md- Complete refactoring playbookImplementation 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.tssrc/ui/SensoryNeuron.ts→src/ui/Receptor.tssrc/ui/MotorNeuron.ts→src/ui/Effector.tssrc/ui/InterneuronUI.ts→src/ui/DermalLayer.tssrc/ui/glial/VisualAstrocyte.ts→src/ui/glial/Adipocyte.tssrc/ui/glial/VisualOligodendrocyte.ts→src/ui/glial/Melanocyte.tssrc/ui/types.ts(add system-specific types)src/ui/components/(18 files)src/visualization/(10 files)src/ui/__tests__/(4 files)*.stories.ts(9 files)src/ui/index.ts(update exports)Migration Steps:
Phase 2: UI Component Names (Week 3-4)
Changes:
Button→TouchReceptor(5 files)Input→TextReceptor(5 files)Select→SelectReceptor/ChoiceReceptor(5 files)Form→DermalLayer(5 files)Modal→Membrane/Vesicle(5 files)Card→DermalLayer/Epidermis(5 files)Alert→AlertReceptor/Nociceptor(5 files)Text→Keratinocyte/TextCell(5 files)Radio→RadioReceptor/ChoiceReceptor(5 files)Checkbox→CheckReceptor/ToggleReceptor(5 files)Files to Update:
src/ui/components/src/ui/components/index.tsPhase 3: Visualization System (Week 5-6)
Changes:
Chart→VisualizationBarChart→BarVisualizationLineChart→LineVisualizationPieChart→PieVisualizationScatterPlot→ScatterVisualizationChartDataPoint→DataPoint/MeasurementDataBounds→Bounds/RangeCanvasPoint→Coordinate/PointBaseChartProps→BaseVisualizationPropsBaseChartState→BaseVisualizationStateChartTheme→VisualizationThemeFiles to Update:
src/visualization/src/visualization/index.tsPhase 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.tssrc/communication/index.tssrc/index.tsPhase 5: Respiratory System (Week 8-9)
Changes:
Router→Bronchus/Trachea(decide on single term)Resource→Oxygen/Nutrient(decide on single term)ResourcePool→Alveolus/Capillary(decide on single term)Route→BronchioleDatabaseResource→DatabaseOxygen/DatabaseNutrientCacheResource→CacheOxygen/CacheNutrientStorageResource→StorageOxygen/StorageNutrientRestAdapter→RestBronchusGraphQLAdapter→GraphQLBronchusWebSocketAdapter→WebSocketBronchusProtocolAdapter→ProtocolBronchusFiles to Update:
src/respiratory/src/respiratory/index.tsPhase 6: Infrastructure Terms (Week 10)
Changes:
Server→Organ/System(decide on single term)Client→Receptor/Effector(decide on single term)Bridge→Synapse/Connection(decide on single term)WebSocketBridge→WebSocketSynapse/WebSocketConnectionTheaterServer→TheaterOrgan/TheaterSystemClientConnection→ReceptorConnection/EffectorConnectionHotReload→Regeneration/RenewalServerConfig→OrganConfig/SystemConfigServerState→OrganState/SystemStateWebSocketConfig→WebSocketConnectionConfigHotReloadConfig→RegenerationConfigFiles to Update:
src/theater/server/src/theater/index.tsPhase 7: Tools & Testing Terms (Week 11)
Changes:
DependencyAuditor→DependencyAnalyzer/DependencyInspectorAuditReport→AnalysisReport/InspectionReportAuditOptions→AnalysisOptions/InspectionOptionsTest→Experiment/Hypothesis(in test files - optional)Mock→Specimen/Model(in test files - optional)Files to Update:
src/tools/dependency-auditor.tsPlanned 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 correctMuscleGroup(operation composition) - Already correctMuscleMemory(operation caching) - Already correctMuscleCoordination(orchestration) - Already correctTendon(integration points) - Already correctBuilt-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 correctArtery(outbound data streams) - Already correctVein(inbound data streams) - Already correctCapillary(micro-channels) - Already correctBloodCell(message envelope) - Already correctHemoglobin(data carrier) - Already correctPhase 5: Respiratory System (Planned)
Core Components:
Lung(HTTP client/server) - Already correctAlveoli(API endpoints) - Already correctDiaphragm(breathing control) - Already correctBronchi(protocol adapters) - Already correctOxygen(external resources) - Already correctCarbonDioxide(error exhaust) - Already correctProtocol Adapters:
RestAdapter→RestBronchusGraphQLAdapter→GraphQLBronchusWebSocketAdapter→WebSocketBronchusSSEAdapter→SSEBronchusgRPCAdapter→gRPCBronchusPhase 6: Immune System (Planned)
Core Components:
WhiteBloodCell(threat detection) - Already correctAntibody(authentication) - Already correctTCell(authorization) - Already correctBCell(error memory) - Already correctMacrophage(cleanup & sanitization) - Already correctLymph(security context) - Already correctVaccine(security configuration) - Already correctPhase 7: Endocrine System (Planned)
Core Components:
Gland(configuration provider) - Already correctHormone(configuration value) - Already correctReceptor(config consumer) - Already correct (but conflicts with Skin Receptor - decide on naming)Hypothalamus(feature flags) - Already correctPituitary(central control) - Already correctThyroid(performance tuning) - Already correctPhase 8: Digestive System (Planned)
Core Components:
Mouth(data ingestion) - Already correctEsophagus(data pipeline) - Already correctStomach(data processing) - Already correctIntestine(data transformation) - Already correctLiver(data cleansing) - Already correctEnzyme(transformation functions) - Already correctPhase 9: Skin Layer - Advanced Components (Planned)
Form Controls:
Select/Dropdown→SelectReceptor/ChoiceReceptorCheckbox→CheckReceptor/ToggleReceptorRadio→RadioReceptor/ChoiceReceptorToggle/Switch→ToggleReceptor/SwitchReceptorSlider/Range→RangeReceptor/SliderReceptorDatePicker→DateReceptor/TemporalReceptorTimePicker→TimeReceptor/TemporalReceptorColorPicker→ColorReceptor/VisualReceptorFileUpload→FileReceptor/UploadReceptorData Display:
Table→DataTable/GridCell/TabularCellTreeView→TreeCell/HierarchicalCellList→ListCell/CollectionCellGrid→GridCell/MatrixCellTimeline→TimelineCell/ChronologicalCellAccordion→AccordionCell/ExpandableCellTabs→TabCell/TabularCellBreadcrumbs→BreadcrumbCell/NavigationCellNavigation:
Menu/DropdownMenu→MenuCell/NavigationCellSidebar→SidebarCell/LateralCellNavbar→NavbarCell/NavigationCellPagination→PaginationCell/PageNavigationCellStepper/Wizard→StepperCell/ProgressiveCellCommandPalette→CommandCell/PaletteCellFeedback:
Modal/Dialog→Membrane/VesicleToast/Notification→NotificationCell/AlertCellAlert→AlertReceptor/NociceptorProgressBar→ProgressCell/ProgressIndicatorSkeletonLoader→SkeletonCell/LoadingCellSpinner→SpinnerCell/LoadingCellBadge→BadgeCell/IndicatorCellTooltip→TooltipCell/HintCellPopover→PopoverCell/OverlayCellLayout:
Grid→GridCell/MatrixCellFlex/FlexContainer→FlexCell/FlexibleCellStack→StackCell/LayeredCellDivider→DividerCell/SeparatorCellSpacer→SpacerCell/EmptyCellContainer→ContainerCell/WrapperCellCard→CardCell/Epidermis/DermalLayerAdvanced:
Chart→Visualization(see Phase 3)CodeEditor→CodeCell/EditorCellRichTextEditor→RichTextCell/EditorCellMarkdownViewer→MarkdownCell/DocumentCellPDFViewer→PDFCell/DocumentCellImageCropper→ImageCell/ImageProcessorAutocomplete→AutocompleteReceptor/SuggestReceptorCombobox→ComboboxReceptor/SelectReceptorPhase 10: Observability & Monitoring (Planned)
Core Components:
SensoryNerve(telemetry collection) - Already correctHealthMonitor- Already correctMetricsRegistry- Already correctDashboard→DashboardCell/MonitorCellPhase 11: Developer Experience & Tooling (Planned)
CLI Components:
CLI→CLI(keep as-is, or useCommandLineInterface)REPL→REPL(keep as-is, or useInteractiveShell)CodeGenerator→CodeGenerator/CodeSynthesizerMigrationTool→MigrationTool/MigrationAssistantBuild Tools:
BuildTool→BuildTool/CompilationToolBundleAnalyzer→BundleAnalyzer/BundleInspectorCodeSplitter→CodeSplitter/CodeDividerDebug Tools:
Debugger→Debugger/DiagnosticToolStateInspector→StateInspector/StateExplorerPerformanceProfiler→PerformanceProfiler/PerformanceAnalyzerMemoryLeakDetector→MemoryLeakDetector/MemoryAnalyzerPhase 12: Performance Optimization (Planned)
Optimization Components:
JITCompiler→JITCompiler/RuntimeCompilerObjectPool→ObjectPool/ObjectCacheMemoryArena→MemoryArena/MemoryPoolWorkerThreadPool→WorkerThreadPool/ThreadPoolCacheStrategy→CacheStrategy/CachingStrategyLazyLoader→LazyLoader/DeferredLoaderCompressor→Compressor/CompressionToolPhase 13: Advanced Data Patterns (Planned)
Core Patterns:
CQRS→CQRS(keep as-is, or useCommandQuerySeparation)EventStore→EventStore/EventRepositoryEventStream→EventStream/EventFlowSaga→Saga/TransactionOrchestratorOutbox→Outbox/MessageOutboxMaterializedView→MaterializedView/CachedViewPhase 14: Real-time Collaboration (Planned)
Core Components:
CRDT→CRDT(keep as-is, or useConflictFreeReplicatedDataType)OperationalTransform→OperationalTransform/OperationTransformerPresenceTracker→PresenceTracker/PresenceMonitorSyncEngine→SyncEngine/SynchronizationEngineCollaborativeEditor→CollaborativeEditor/SharedEditorPhase 15: AI & Machine Learning Integration (Planned)
Core Components:
MLPipeline→MLPipeline/MachineLearningPipelineModelServing→ModelServing/ModelServerModelVersioning→ModelVersioning/ModelRegistryAutoML→AutoML/AutomatedMLExplainability→Explainability/ModelExplanationWebNN Integration:
WebNN→WebNN(keep as-is)NeuralNetwork→NeuralNetwork/NeuralCircuit(already exists)ModelOptimizer→ModelOptimizer/ModelCompressorHardwareAccelerator→HardwareAccelerator/AccelerationEnginePre-trained Models:
TextClassifier→TextClassifier/TextAnalysisModelSentimentAnalyzer→SentimentAnalyzer/SentimentModelNamedEntityRecognizer→NamedEntityRecognizer/EntityExtractorImageClassifier→ImageClassifier/ImageAnalysisModelObjectDetector→ObjectDetector/ObjectRecognitionModelIntelligent Features:
SmartAutocomplete→SmartAutocomplete/IntelligentAutocompleteContentRecommender→ContentRecommender/RecommendationEngineAnomalyDetector→AnomalyDetector/AnomalyRecognitionPredictiveAnalytics→PredictiveAnalytics/PredictionEnginePersonalizationEngine→PersonalizationEngine/PersonalizationSystemPhase 16: Edge Computing & Distributed Systems (Planned)
Core Components:
EdgeRuntime→EdgeRuntime/EdgeExecutionEnvironmentDistributedCache→DistributedCache/DistributedMemoryServiceMesh→ServiceMesh/ServiceNetworkGlobalStateSync→GlobalStateSync/GlobalSynchronizationEdgeOptimizer→EdgeOptimizer/EdgeOptimizationEngineDistributedTracing→DistributedTracing/DistributedTraceSystemDeployment Targets:
CloudflareWorkers→CloudflareWorkers/CloudflareEdgeAWSLambda→AWSLambda/LambdaFunctionVercelEdgeFunctions→VercelEdgeFunctions/VercelEdgeDenoDeploy→DenoDeploy/DenoEdgePhase 17: Testing & Quality Assurance Framework (Planned)
Testing Tools:
TestUtilities→TestUtilities/TestingUtilitiesMockFactory→MockFactory/SpecimenFactoryFixtureGenerator→FixtureGenerator/TestDataGeneratorSnapshotTester→SnapshotTester/SnapshotValidatorVisualRegressionTester→VisualRegressionTester/VisualTesterE2E Testing:
E2ETester→E2ETester/EndToEndTesterPlaywrightIntegration→PlaywrightIntegration/PlaywrightAdapterPuppeteerIntegration→PuppeteerIntegration/PuppeteerAdapterVisualTester→VisualTester/VisualRegressionTesterAccessibilityTester→AccessibilityTester/A11yTesterLoad Testing:
LoadTester→LoadTester/LoadTestingToolStressTester→StressTester/StressTestingToolSoakTester→SoakTester/SoakTestingToolSpikeTester→SpikeTester/SpikeTestingToolScalabilityTester→ScalabilityTester/ScalabilityTestingToolContract Testing:
ContractTester→ContractTester/ContractValidatorAPIContractTester→APIContractTester/APIContractValidatorConsumerDrivenContract→ConsumerDrivenContract/ConsumerContractChaos Engineering:
ChaosEngineer→ChaosEngineer/ChaosTestingToolFailureInjector→FailureInjector/FailureSimulatorLatencyInjector→LatencyInjector/LatencySimulatorNetworkPartitionSimulator→NetworkPartitionSimulator/PartitionSimulatorResourceExhaustionSimulator→ResourceExhaustionSimulator/ResourceSimulatorTest Coverage:
CoverageAnalyzer→CoverageAnalyzer/CoverageToolMutationTester→MutationTester/MutationTestingToolPropertyBasedTester→PropertyBasedTester/PropertyTesterPhase 18: Enterprise Features (Planned)
Enterprise Components:
MultiTenancy→MultiTenancy/TenantIsolationTenantIsolation→TenantIsolation/TenantSeparationAuditTrail→AuditTrail/AuditLogComplianceTool→ComplianceTool/ComplianceManagerGDPRCompliance→GDPRCompliance/GDPRManagerHIPAACompliance→HIPAACompliance/HIPAAManagerSOC2Compliance→SOC2Compliance/SOC2ManagerAdvanced Authorization:
HierarchicalRoles→HierarchicalRoles/RoleHierarchyDelegatedAdministration→DelegatedAdministration/DelegationSystemTimeBasedAccess→TimeBasedAccess/TemporalAccessLocationBasedAccess→LocationBasedAccess/SpatialAccessRiskBasedAuthentication→RiskBasedAuthentication/RiskAssessmentReporting:
UsageReporter→UsageReporter/UsageAnalyticsPerformanceReporter→PerformanceReporter/PerformanceAnalyticsSecurityReporter→SecurityReporter/SecurityAnalyticsComplianceReporter→ComplianceReporter/ComplianceAnalyticsCustomReportBuilder→CustomReportBuilder/ReportGeneratorScheduledReporter→ScheduledReporter/ScheduledReportGeneratorBilling & Metering:
UsageTracker→UsageTracker/UsageMonitorQuotaManager→QuotaManager/QuotaSystemRateLimiter→RateLimiter/RateControllerBillingIntegrator→BillingIntegrator/BillingAdapterInvoiceGenerator→InvoiceGenerator/InvoiceCreatorPaymentProcessor→PaymentProcessor/PaymentHandlerSLA Management:
SLOManager→SLOManager/ServiceLevelManagerSLITracker→SLITracker/ServiceLevelTrackerErrorBudget→ErrorBudget/ErrorAllowanceUptimeMonitor→UptimeMonitor/AvailabilityMonitorIncidentManager→IncidentManager/IncidentSystemPostMortemTemplate→PostMortemTemplate/PostMortemGeneratorPhase 19: Plugin Ecosystem (Planned)
Plugin System:
Plugin→Plugin/ExtensionPluginInterface→PluginInterface/ExtensionInterfacePluginLifecycle→PluginLifecycle/ExtensionLifecyclePluginIsolation→PluginIsolation/ExtensionIsolationPluginSandbox→PluginSandbox/ExtensionSandboxPluginDependencies→PluginDependencies/ExtensionDependenciesPluginVersioning→PluginVersioning/ExtensionVersioningPluginHotReload→PluginHotReload/ExtensionHotReloadPlugin APIs:
CoreExtensionPoint→CoreExtensionPoint/CoreHookUIExtensionPoint→UIExtensionPoint/UIHookDataExtensionPoint→DataExtensionPoint/DataHookCLIExtensionPoint→CLIExtensionPoint/CLIHookBuildExtensionPoint→BuildExtensionPoint/BuildHookPlugin Development:
PluginCLIGenerator→PluginCLIGenerator/ExtensionGeneratorPluginTestingFramework→PluginTestingFramework/ExtensionTestingFrameworkPluginDebugger→PluginDebugger/ExtensionDebuggerPluginDocumentationGenerator→PluginDocumentationGenerator/ExtensionDocumentationGeneratorPlugin Distribution:
PluginMarketplace→PluginMarketplace/ExtensionMarketplacePluginDiscovery→PluginDiscovery/ExtensionDiscoveryPluginRatings→PluginRatings/ExtensionRatingsPluginReviews→PluginReviews/ExtensionReviewsPluginAnalytics→PluginAnalytics/ExtensionAnalyticsOfficial Plugins:
DatabasePlugin→DatabasePlugin/DatabaseAdapterStoragePlugin→StoragePlugin/StorageAdapterAuthPlugin→AuthPlugin/AuthAdapterPaymentPlugin→PaymentPlugin/PaymentAdapterEmailPlugin→EmailPlugin/EmailAdapterAnalyticsPlugin→AnalyticsPlugin/AnalyticsAdapterPlugin Security:
PermissionSystem→PermissionSystem/CapabilitySystemCapabilityBasedSecurity→CapabilityBasedSecurity/CapabilitySecurityCodeSigning→CodeSigning/CodeVerificationSecurityAudit→SecurityAudit/SecurityReviewVulnerabilityScanner→VulnerabilityScanner/VulnerabilityDetectorPhase 20: Advanced UI & Visualization (Planned)
Visualization Components:
LineChart→LineVisualization(see Phase 3)BarChart→BarVisualization(see Phase 3)PieChart→PieVisualization(see Phase 3)ScatterPlot→ScatterVisualization(see Phase 3)Heatmap→HeatmapVisualization/HeatVisualizationNetworkGraph→NetworkVisualization/GraphVisualizationTreeMap→TreeMapVisualization/HierarchicalVisualizationGanttChart→GanttVisualization/TimelineVisualizationRealTimeChart→RealTimeVisualization/LiveVisualization3DChart→3DVisualization/ThreeDimensionalVisualizationCanvas-based Rendering:
CanvasRenderer→CanvasRenderer/CanvasEngineWebGLRenderer→WebGLRenderer/WebGLEngineGPUAccelerator→GPUAccelerator/GPUEngineCustomShader→CustomShader/ShaderProgramParticleSystem→ParticleSystem/ParticleEngineData Visualization:
GeographicMap→GeographicMap/MapVisualizationNetworkTopology→NetworkTopology/TopologyVisualizationFlowDiagram→FlowDiagram/FlowVisualizationSankeyDiagram→SankeyDiagram/SankeyVisualizationChordDiagram→ChordDiagram/ChordVisualizationForceDirectedGraph→ForceDirectedGraph/ForceGraphInteractive Features:
ZoomAndPan→ZoomAndPan/ZoomControllerBrushSelection→BrushSelection/SelectionBrushTooltip→Tooltip/HintCell(see Phase 9)Crosshairs→Crosshairs/CrosshairIndicatorAnnotations→Annotations/AnnotationLayerExportToImage→ExportToImage/ImageExporterExportToPDF→ExportToPDF/PDFExporterAnimation System:
AnimationSystem→AnimationSystem/AnimationEngineSpringPhysics→SpringPhysics/SpringAnimationEasingFunctions→EasingFunctions/EasingCurvesStaggeredAnimations→StaggeredAnimations/SequentialAnimationsGestureAnimations→GestureAnimations/GestureBasedAnimationsScrollTriggeredAnimations→ScrollTriggeredAnimations/ScrollAnimationsPageTransitions→PageTransitions/TransitionAnimations3D Rendering:
WebGLRenderer→WebGLRenderer/WebGLEngine(duplicate)ThreeJSIntegration→ThreeJSIntegration/ThreeJSAdapter3DModelLoader→3DModelLoader/ModelLoaderSceneManager→SceneManager/SceneControllerCameraControls→CameraControls/CameraControllerLighting→Lighting/LightSystemMaterials→Materials/MaterialSystemTextures→Textures/TextureSystemAdvanced UI Patterns:
VirtualScrolling→VirtualScrolling/VirtualListInfiniteScrolling→InfiniteScrolling/InfiniteListWindowing→Windowing/WindowManagerMasonryLayout→MasonryLayout/MasonryGridDragAndDrop→DragAndDrop/DragDropSystemGestureRecognition→GestureRecognition/GestureSystemTouchInteractions→TouchInteractions/TouchSystemVoiceInteractions→VoiceInteractions/VoiceSystemTheater System (Planned - Phase 6)
Core Components:
Theater- Already correctStage- Already correctAmphitheater- Already correctSpecimen- Already correctObservation- Already correctDissection- Already correctLaboratory- Already correctExperiment- Already correctHypothesis- Already correctAtlas- Already correctProtocol- Already correctInstrument- Already correctMicroscope- Already correctMicroscope Tools:
SignalTracer→SignalTracer/SignalTrackerStateExplorer→StateExplorer/StateInspectorPerformanceProfiler→PerformanceProfiler/PerformanceAnalyzerHealthMonitor→HealthMonitor/HealthCheckerLaboratory Components:
PetriDish→PetriDish/TestContainerCulture→Culture/TestEnvironmentExperiment- Already correctAtlas Components:
ComponentCatalogue→ComponentCatalogue/ComponentRegistryDiagram→Diagram/VisualizationProtocol- Already correctServer & Hot Reload:
TheaterServer→TheaterOrgan/TheaterSystem(see Phase 6)HotReload→Regeneration/Renewal(see Phase 6)WebSocketCommunication→WebSocketSynapse/WebSocketConnection(see Phase 6)CLI & Configuration:
TheaterCLI→TheaterCLI/TheaterCommandLineTheaterConfiguration→TheaterConfiguration/TheaterConfigSpecimenFileLoader→SpecimenFileLoader/SpecimenLoaderPlanned 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:
Implementation Guidelines
Naming Conventions
SkinCell,TouchReceptor)SkinCellConfig,TouchReceptorProps)ReceptorType,SkinCellState)activate(),receive())signalQueue,activationTime)MAX_RETRIES,DEFAULT_TTL)Migration Strategy
Backward Compatibility
For critical breaking changes, consider adding deprecated aliases:
Testing Requirements
Before Each Phase
During Each Phase
After Each Phase
npm testnpm test -- --passWithNoTestsnpm run test:coveragenpm run type-checknpm run buildnpm run lintAcceptance Criteria
Phase 1 (Critical)
VisualNeuronreferences migrated toSkinCellSensoryNeuronreferences migrated toReceptorMotorNeuronreferences migrated toEffectorInterneuronUIreferences migrated toDermalLayerVisualAstrocytereferences migrated toAdipocyteVisualOligodendrocytereferences migrated toMelanocyteComponentPropsreferences migrated to system-specific propsComponentStatereferences migrated to system-specific stateOverall Success Criteria
npm testnpm run type-checknpm run buildnpm run lintVerification Checklist (Per Phase)
After completing each phase, verify:
npm testnpm run type-checknpm run buildnpm run lintRisk Mitigation
High Risk Changes
VisualNeuron → SkinCell (42 files, Critical)
ComponentProps/State → System-specific (100+ files, Critical)
SensoryNeuron → Receptor (25 files, Critical)
Testing Strategy
Decision Points
Before starting, decide on these ambiguous terms:
EventBus → Heart or Artery?
Heart(already exists, is message broker)Event → BloodCell or Signal?
BloodCellfor messages,Signalfor neural communicationRouter → Bronchus or Trachea?
Bronchus(branches airways, more flexible)Resource → Oxygen or Nutrient?
Oxygen(more specific, fits respiratory metaphor)ResourcePool → Alveolus or Capillary?
Alveolus(exchanges oxygen, fits pooling metaphor)Server → Organ or System?
Organ(more specific, fits medical metaphor)Client → Receptor or Effector?
Receptor(receives, fits client role)Bridge → Synapse or Connection?
Synapse(connects neurons, fits bridge role)HotReload → Regeneration or Renewal?
Regeneration(cells regenerate, fits hot reload)Notes
Project Rename Analysis: Synapse → Full Body Metaphor
Current State
Current Name: "Synapse Framework"
@synapse-framework/coresynapsesynapseThe 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):
Conclusion: The framework is about the entire body/organism, not just the nervous system.
Rename Options
Option 1: Anatomy Framework ⭐ (Recommended)
Pros:
@anatomy-framework/coreanatomyCons:
Tagline: "A TypeScript framework inspired by human anatomy"
Option 2: Organism Framework
Pros:
@organism-framework/coreorganismCons:
Tagline: "A TypeScript framework inspired by biological organisms"
Option 3: Physiology Framework
Pros:
@physiology-framework/corephysiologyCons:
Tagline: "A TypeScript framework inspired by human physiology"
Option 4: Body Framework
Pros:
@body-framework/corebodyCons:
Tagline: "A TypeScript framework inspired by the human body"
Option 5: Keep "Synapse" but Rebrand
Pros:
Cons:
Tagline: "A TypeScript framework inspired by biological systems" (vague)
Impact Assessment
Breaking Changes Required:
Package Name:
@synapse-framework/core→@anatomy-framework/coreCLI Command:
synapse→anatomyRepository Name:
synapse→anatomy(oranatomy-framework)Documentation:
Code References:
src/index.tsMigration 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:
Timing:
Alternative if keeping current name:
Decision Matrix
Next Steps
If proceeding with rename:
Questions to Consider
Reference
See
COMPREHENSIVE_REFACTORING_PLAYBOOK.mdfor complete details.See
PROJECT_RENAME_ANALYSIS.mdfor 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