# TestDrive-JSUI Architecture **Last Updated**: 2025-12-16 **Status**: Refactoring to JavaScript-first architecture --- ## 🎯 Core Principle **TestDrive-JSUI is a JavaScript library, not a Python package.** The JavaScript code provides all functionality. Python, Ruby, Java, or other language bindings are **integration adapters** that help serve, configure, and test the JavaScript library - they do not provide core functionality. --- ## πŸ“ Architectural Layers ### Layer 1: Core JavaScript Library (Functionality) **Location**: `/js/` **Purpose**: Complete standalone JavaScript UI framework **Dependencies**: Only `marked.js` (markdown parsing) **Language**: Pure JavaScript (ES6+) ``` js/ β”œβ”€β”€ testdrive-jsui.js # Main library bundle (future) β”œβ”€β”€ core/ # Core systems β”‚ β”œβ”€β”€ debug-system.js # Debug infrastructure β”‚ └── section-manager.js # Document section management β”œβ”€β”€ components/ # UI components β”‚ β”œβ”€β”€ dom-renderer.js # DOM rendering engine β”‚ β”œβ”€β”€ debug-panel.js # Debug UI β”‚ └── document-controls.js # Document control UI β”œβ”€β”€ controls/ # Interactive control panels β”‚ β”œβ”€β”€ control-base.js # Base control class β”‚ β”œβ”€β”€ edit-control.js # Edit mode controls β”‚ β”œβ”€β”€ debug-control.js # Debug controls β”‚ β”œβ”€β”€ status-control.js # Status indicator β”‚ └── contents-control.js # Table of contents β”œβ”€β”€ widgets/ # Reusable UI widgets β”œβ”€β”€ plugins/ # Extension system └── utils/ # Shared utilities ``` **Key Characteristics**: - βœ… Works standalone in any browser - βœ… No backend required (can load from file://) - βœ… Self-contained markdown rendering - βœ… All UI logic in JavaScript - βœ… Configuration via JSON **Standalone Usage**: ```html
``` --- ### Layer 2: Language Adapters (Integration) **Purpose**: Integration helpers for different backend languages **Function**: Serve assets, provide testing, backend integration **NOT**: Core functionality implementation #### Python Adapter **Location**: `/src/testdrive_jsui/` (optional, for Python projects) **Purpose**: Python project integration ```python # Python is just a helper to serve/test the JS library from testdrive_jsui import TestDriveJSUIAdapter adapter = TestDriveJSUIAdapter() # Adapter helps with: # 1. Asset serving assets = adapter.get_asset_urls() # 2. HTML template generation html = adapter.generate_html( markdown="# Content", mode="edit", config={...} ) # 3. Testing JavaScript test_result = adapter.run_js_tests() ``` **Python Adapter Responsibilities**: - βœ… Asset path resolution - βœ… HTML template generation - βœ… Configuration serialization (Python dict β†’ JSON) - βœ… JavaScript test runner integration (pytest ↔ Jest) - βœ… Development server (optional) - ❌ **NOT** markdown rendering (JS does this) - ❌ **NOT** UI logic (JS does this) - ❌ **NOT** content transformation (JS does this) #### Ruby Adapter (Future) ```ruby # Similar concept for Ruby/Rails projects adapter = TestDriveJSUI::Adapter.new # Generate view helper <%= testdrive_jsui_editor( markdown: @document.content, mode: :edit ) %> ``` #### Java Adapter (Future) ```java // Similar concept for Java/Spring projects TestDriveJSUIAdapter adapter = new TestDriveJSUIAdapter(); String html = adapter.generateHtml(markdown, "edit", config); ``` --- ## πŸ”„ Data Flow ### Standalone Mode (No Backend) ``` 1. Browser loads HTML 2. HTML includes testdrive-jsui.js 3. JS initializes with config 4. JS fetches/parses markdown β†’ marked.js 5. JS renders UI β†’ DOM 6. User interacts β†’ JS handles everything 7. Save via JS (localStorage, download, etc.) ``` ### With Backend Adapter (Python/Ruby/Java) ``` 1. Backend serves HTML template 2. Backend injects config JSON 3. Backend includes JS/CSS assets 4. Browser runs JavaScript (same as standalone) 5. JS may call backend APIs for save/load ``` **Key Point**: Backend is optional and only for convenience! --- ## 🎨 Current vs Target Architecture ### Current (Hybrid - Needs Refactoring) ``` ❌ Python generates HTML structure ❌ Python does markdown fallback rendering ❌ JavaScript enhances the Python-generated HTML ❌ Tight coupling between Python and JavaScript ``` ### Target (Clean Separation) ``` βœ… JavaScript is the complete UI library βœ… JavaScript handles all rendering (markdown β†’ HTML β†’ DOM) βœ… Python/Ruby/Java are thin adapters βœ… Zero coupling - JS works without any backend ``` --- ## πŸ“¦ Distribution Models ### Model 1: CDN (Simplest) ```html ``` ### Model 2: npm Package ```bash npm install testdrive-jsui ``` ```javascript import TestDriveJSUI from 'testdrive-jsui'; ``` ### Model 3: With Language Adapter ```bash # Python projects pip install testdrive-jsui-python # Ruby projects gem install testdrive-jsui # Java projects maven: com.testdrive:testdrive-jsui-java ``` **Important**: Language adapters are separate packages that bundle/reference the core JS library. --- ## πŸ§ͺ Testing Architecture ### JavaScript Tests (Core) **Framework**: Jest with jsdom **Location**: `/js/tests/` **What**: Tests the JavaScript library itself ```javascript describe('TestDriveJSUI', () => { test('renders markdown to HTML', () => { const ui = new TestDriveJSUI({...}); expect(ui.render('# Hello')).toContain('

'); }); }); ``` ### Python Integration Tests (Adapter) **Framework**: pytest **Location**: `/tests/` (in Python adapter) **What**: Tests Python ↔ JavaScript integration ```python def test_python_adapter_runs_js_tests(): adapter = TestDriveJSUIAdapter() result = adapter.run_js_tests() assert result.success ``` **Key**: Python tests verify the adapter works, not the JS functionality! --- ## πŸ”§ Configuration System ### JavaScript Configuration (Core) ```javascript { // Core JS library config "mode": "edit", // 'edit' | 'view' "theme": "github", // CSS theme "markdown": "# Content", // Initial content "autosave": false, // Auto-save behavior "shortcuts": true, // Keyboard shortcuts "sections": true, // Section management "debug": false // Debug mode } ``` ### Adapter Configuration (Language-specific) ```python # Python adapter config (separate from JS) { "asset_base_url": "/static", # Where to serve JS/CSS "development_mode": True, # Dev vs production "template_path": "...", # HTML template location } ``` **Separation**: JS config controls the library, adapter config controls integration. --- ## 🎯 Migration Path ### Phase 1: Improve Current Structure βœ… (Starting) 1. βœ… Document architecture (this file) 2. ⏸️ Rename Python code to clearly show it's an adapter 3. ⏸️ Ensure JS can work standalone 4. ⏸️ Separate JS config from adapter config ### Phase 2: Pure JavaScript Rendering 1. ⏸️ Move all markdown rendering to JavaScript (use marked.js) 2. ⏸️ Remove Python HTML generation 3. ⏸️ Make Python adapter purely serve assets + config 4. ⏸️ Create standalone HTML example ### Phase 3: Proper Distribution 1. ⏸️ Bundle JavaScript library (`testdrive-jsui.js`) 2. ⏸️ Publish to npm 3. ⏸️ Publish to CDN 4. ⏸️ Separate Python adapter package ### Phase 4: Additional Adapters 1. ⏸️ Ruby adapter 2. ⏸️ Java adapter 3. ⏸️ PHP adapter (if needed) --- ## πŸ“š Documentation Structure ``` docs/ β”œβ”€β”€ javascript/ # Core JS library docs β”‚ β”œβ”€β”€ getting-started.md # Standalone usage β”‚ β”œβ”€β”€ api-reference.md # JavaScript API β”‚ β”œβ”€β”€ configuration.md # JS config options β”‚ └── examples/ # Pure JS examples β”œβ”€β”€ adapters/ # Language adapter docs β”‚ β”œβ”€β”€ python/ β”‚ β”‚ β”œβ”€β”€ installation.md β”‚ β”‚ β”œβ”€β”€ django-integration.md β”‚ β”‚ └── flask-integration.md β”‚ β”œβ”€β”€ ruby/ β”‚ β”‚ └── rails-integration.md β”‚ └── java/ β”‚ └── spring-integration.md └── architecture/ └── ARCHITECTURE.md # This file ``` --- ## πŸ”‘ Key Principles 1. **JavaScript First**: All functionality in JavaScript 2. **Backend Optional**: Works without any backend 3. **Adapters Not Implementations**: Language bindings help integrate, don't implement 4. **Clear Boundaries**: JS does UI, backend does serving/storage 5. **Language Agnostic**: Core library works with any backend 6. **Zero Lock-in**: Use testdrive-jsui without any specific backend framework --- ## 🚫 Anti-Patterns to Avoid ❌ **Don't**: Implement UI logic in Python/Ruby/Java βœ… **Do**: Implement UI logic in JavaScript ❌ **Don't**: Render markdown in backend βœ… **Do**: Render markdown in JavaScript (marked.js) ❌ **Don't**: Generate HTML structure in backend βœ… **Do**: Generate HTML structure in JavaScript ❌ **Don't**: Make JavaScript depend on backend APIs βœ… **Do**: Make JavaScript work standalone, optionally call APIs ❌ **Don't**: Create language-specific forks βœ… **Do**: Create thin adapters around single JS library --- ## πŸ“ˆ Success Metrics - [ ] Can use testdrive-jsui with pure HTML file (no backend) - [ ] Can use testdrive-jsui with Python/Flask - [ ] Can use testdrive-jsui with Ruby/Rails - [ ] Can use testdrive-jsui with Java/Spring - [ ] JavaScript library < 100KB minified - [ ] Zero runtime dependencies except marked.js - [ ] Works in all modern browsers - [ ] Published to npm and CDN --- ## 🀝 Contributing When contributing: - Core functionality β†’ JavaScript - Integration helpers β†’ Language adapters - Keep adapters thin and similar across languages - Test JavaScript with Jest - Test adapters with language-native tools (pytest, rspec, junit) --- **Remember**: TestDrive-JSUI is a JavaScript library with optional backend adapters, not a backend framework with JavaScript assets!