# 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
<!DOCTYPE html>
<html>
<head>
    <link rel="stylesheet" href="testdrive-jsui.css">
</head>
<body>
    <div id="content"></div>

    <!-- Dependencies -->
    <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>

    <!-- TestDrive-JSUI -->
    <script src="testdrive-jsui.js"></script>

    <script>
        // Initialize with configuration
        const ui = new TestDriveJSUI({
            container: '#content',
            mode: 'edit',
            markdown: '# Hello World\n\nEdit me!',
            theme: 'github'
        });
    </script>
</body>
</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: Self-hosted file (simplest)

Copy `dist/testdrive-jsui.min.js` and `dist/testdrive-jsui.css` from the package (or a release build) next to your page and load them with `<script>` / `<link>`. Public CDNs (jsDelivr, unpkg) only mirror npmjs.org and do not serve the coulomb Forgejo registry.

### Model 2: npm package (coulomb Forgejo registry)

```bash
# .npmrc: @coulomb:registry=https://forgejo.coulomb.social/api/packages/coulomb/npm/
npm install @coulomb/testdrive-jsui marked
```

```javascript
import TestDriveJSUI from '@coulomb/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('<h1>');
  });
});
```

### 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!