PlainBridge Framework

A Human-AI Bridge Framework for Building Explainable Web Applications

Purpose

PlainBridge is a lightweight framework designed to help developers build maintainable web applications where both humans and AI can collaborate effectively. It combines three core pillars:

1. Explainable Software Engineering (XSE) - Structured documentation embedded directly in code
2. Semantic Vanilla Components (SVCs) - Convention-based Web Components with zero framework dependencies
3. Living Architecture Maps - Metadata-driven visualization of system structure

The framework prioritizes readability, debuggability, and long-term maintainability over short-term convenience.

Core Principles

1. Explainability First

Every piece of code must answer these questions:

• What does it do? (@xse-summary)
• Why does it exist? (@xse-purpose)
• Why was it built this way? (@xse-rationale)
• How would you explain it to a beginner? (@xse-eli5)
• What goes wrong and how do you fix it? (@xse-debug-hints)
• Who created or modified it? (@xse-ai-trace)

2. Convention Over Configuration

PlainBridge uses strict conventions to eliminate configuration:

• One component = one folder
• Predictable file naming (component-name.js, component-name.css, etc.)
• Standard metadata format (.meta.json)
• No build configuration required

3. Human-in-the-Loop Development

Code is written for junior developers to understand:

• Verbose explanations over terse code
• Clear debugging hints at error sites
• Manual review checkpoints for complex code
• Plain-language summaries (ELI5) for all components

4. Zero Framework Dependencies

PlainBridge uses only browser-native APIs:

• Web Components (Custom Elements + Shadow DOM)
• Standard JavaScript (ES6+)
• No React, Vue, Angular, or other large frameworks
• Minimal learning curve, maximum longevity

5. Living Documentation

Documentation stays synchronized with code:

• Metadata files (.meta.json) describe every component
• Architecture maps generated from metadata
• Documentation is machine-readable and human-readable
• Provenance tracking for all changes

Project Organization

plainbridge-framework/
├── core/ # Core utilities and base classes
│ ├── explainable-error.js # XSE-enriched error handling
│ └── logger.js # XSE-aware logging system
│
├── components/ # Semantic Vanilla Components (SVCs)
│ └── hello-world/ # Example component
│ ├── hello-world.html # Template (optional)
│ ├── hello-world.css # Styles
│ ├── hello-world.js # Component logic
│ ├── hello-world.meta.json # Metadata
│ └── hello-world.test.js # Tests (optional)
│
├── services/ # Shared services (future)
│
├── maps/ # Generated architecture visualizations
│ └── .gitignore # Maps are generated, not committed
│
├── docs/ # Framework documentation
│ └── conventions/ # Convention specifications
│ ├── xse-format.md
│ ├── svc-conventions.md
│ ├── hitl-debugging.md
│ └── architecture-maps.md
│
└── README.md # This file

How Semantic Vanilla Components (SVCs) Work

Component Structure

Each SVC is a self-contained folder with these files:

component-name/
├── component-name.html # Template (optional, can be in JS)
├── component-name.css # Styles
├── component-name.js # Component logic (Custom Element)
├── component-name.meta.json # Metadata for architecture maps
└── component-name.test.js # Tests (optional)

Component Interface

Inputs:

• HTML attributes (for string values)
• JavaScript properties (for any type)

Outputs:

• CustomEvents with descriptive names (kebab-case)
• Event detail payload contains data

Example:

<!-- Using the component --><hello-worlddata-name="Alice"></hello-world><script>constcomponent=document.querySelector('hello-world');// Listen for eventscomponent.addEventListener('hello-click',(event)=>{console.log('Clicked!',event.detail);});// Set propertiescomponent.name='Bob';</script>

Component Implementation

/** * @xse-summary A simple greeting component that displays hello messages * @xse-purpose Demonstrates SVC conventions and XSE documentation * @xse-rationale Built as a minimal example to teach the framework * @xse-eli5 This is like a reusable greeting card that says hello * @xse-debug-hints Check that the component is registered before use * @xse-ai-trace Created by Kiro on 2025-12-04 */classHelloWorldextendsHTMLElement{connectedCallback(){this.attachShadow({mode: 'open'});this.render();}render(){this.shadowRoot.innerHTML=` <style> /* Styles scoped to this component */ </style> <div>Hello, world!</div> `;}}customElements.define('hello-world',HelloWorld);

The Role of XSE (Explainable Software Engineering)

XSE is a documentation methodology that makes code understandable by both humans and AI systems.

Required XSE Tags

Every code file must include these JSDoc-style tags:

/** * @xse-summary Brief one-line description * @xse-purpose Why this component/function exists in the system * @xse-rationale Design decisions, trade-offs, and alternatives considered * @xse-eli5 Plain-language explanation a 5-year-old could understand * @xse-debug-hints Common issues and troubleshooting steps * @xse-ai-trace Provenance: who created/modified this and when */

Why XSE Matters

1. Onboarding - New developers understand code faster
2. Debugging - Debug hints guide troubleshooting
3. Maintenance - Rationale prevents "why was this done?" questions
4. AI Collaboration - AI can understand and modify code safely
5. Knowledge Transfer - ELI5 explanations bridge experience gaps

The Role of HITL (Human-in-the-Loop) Debugging

HITL debugging ensures humans stay in control of the development process.

Key Concepts

1. Explainable Errors - All errors include context and debug hints
2. Review Checkpoints - Complex code requires human review
3. Manual QA Hints - Components include testing guidance
4. Junior-Developer-First - Code is written for the least experienced team member

Example Error

thrownewExplainableError('Component failed to initialize',{component: 'hello-world',reason: 'Missing required attribute',attribute: 'data-name'}).withDebugHints(['Check that the component has a data-name attribute','Verify the attribute value is not empty','Look at the component documentation for required attributes']).withEli5('This component needs a name to display, but none was provided');

The Role of Living Architecture Maps

Architecture maps are automatically generated from component metadata.

Component Metadata (.meta.json)

Every component includes a metadata file:

{
"name": "hello-world",
"version": "1.0.0",
"purpose": "Display a greeting message",
"rationale": "Demonstrates SVC conventions",
"inputs": [
{
"name": "data-name",
"type": "string",
"required": false,
"description": "Name to greet"
}
],
"outputs": [
{
"event": "hello-click",
"payload": { "timestamp": "number" },
"description": "Fired when component is clicked"
}
],
"dependencies": [],
"complexity": "low",
"lastHumanReview": "2025-12-04T00:00:00Z",
"xse": {
"summary": "A simple greeting component",
"eli5": "Like a reusable greeting card",
"debugHints": ["Check component is registered"]
}
}

Architecture Map Generation

A future tool will:

1. Scan all .meta.json files
2. Build a dependency graph
3. Generate visual diagrams (Mermaid, D3.js)
4. Identify complexity hotspots
5. Suggest refactoring opportunities

Getting Started

1. Start the Development Server

npm run serve
# or
node server.js

Then open http://localhost:3000 in your browser.

2. Run Tests

• Integration Test: http://localhost:3000/integration-test.html
• Component Demo: http://localhost:3000/test-hello-world.html

3. Create a New Component

mkdir components/my-component
cd components/my-component
touch my-component.js my-component.css my-component.meta.json

4. Implement the Component

Follow the SVC conventions (see docs/conventions/svc-conventions.md)

5. Add XSE Documentation

Include all required XSE tags (see docs/conventions/xse-format.md)

6. Create Metadata

Document inputs, outputs, and dependencies (see docs/conventions/architecture-maps.md)

7. Test and Review

Write tests and mark the component for human review

Documentation

Framework Conventions

• docs/conventions/xse-format.md - XSE tag definitions and examples
• docs/conventions/svc-conventions.md - Component structure and naming standards
• docs/conventions/hitl-debugging.md - Error handling and debugging workflows
• docs/conventions/architecture-maps.md - Metadata schema and map generation

Usage Guides

• docs/usage-guide.md - How to use PlainBridge in real-world projects
• docs/npm-package-setup.md - How to package and distribute PlainBridge components

Example Component

See components/hello-world/ for a complete working example that demonstrates all framework conventions.

Philosophy

PlainBridge is built on the belief that:

1. Code is read more than written - Optimize for readability
2. Humans and AI should collaborate - Not compete
3. Documentation should be mandatory - Not optional
4. Simplicity beats cleverness - Always
5. Conventions reduce cognitive load - Consistency matters
6. Junior developers are the target audience - If they understand it, everyone will

Browser Compatibility

PlainBridge targets modern browsers with native Web Components support:

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+

No polyfills required.

License

[Your license here]

Contributing

[Your contribution guidelines here]

---

Built with explainability, maintained by humans and AI together.