insertr/DEVELOPMENT.md

Insertr Development Guide

Quick Start

1. Install dependencies:

   npm install
   

2. Start development server:

   npm run dev
   

   This will start live-server on http://localhost:3000 and automatically open the demo site.

3. Alternative commands:

   npm run dev:about    # Open about page directly
   npm run serve        # Alias for npm run dev
   

Development Workflow

Frontend Development (Current Phase)

• Demo Site: demo-site/ contains the prototype website
• Core Library: demo-site/insertr/insertr.js - the main Insertr library
• Styling: demo-site/insertr/insertr.css - edit interface styles
• Mock API: demo-site/mock-api/content.json - sample backend data structure

Testing the Three User Types

1. Customer View: Open the site normally - clean, no edit interface
2. Client View: Click "Login as Client" then "Edit Mode: On" - see edit buttons
3. Developer View: Look at the HTML source to see simple integration

Making Changes

• Live Reload: The server automatically refreshes when you save changes
• JavaScript: Edit demo-site/insertr/insertr.js to modify core functionality
• Styling: Edit demo-site/insertr/insertr.css for UI changes
• Content: Edit HTML files to test different content structures

Adding New Features

1. Content Types: Extend the createEditForm() method in insertr.js
2. UI Components: Add new CSS classes and corresponding JavaScript
3. Authentication: Modify the mock auth system in toggleAuthentication()

Project Structure

insertr/
├── INITIAL.md              # Project requirements and research
├── DEVELOPMENT.md          # This file
├── package.json            # Node.js project configuration
├── .gitignore             # Git ignore rules
│
├── demo-site/             # Frontend prototype
│   ├── index.html         # Demo homepage
│   ├── about.html         # Demo about page
│   ├── README.md          # Demo usage instructions
│   │
│   ├── assets/            # Demo site assets
│   │   └── style.css      # Demo site styling
│   │
│   ├── insertr/           # Core Insertr library
│   │   ├── insertr.js     # Main library file
│   │   ├── insertr.css    # Edit interface styles
│   │   └── components/    # Future: reusable edit components
│   │
│   └── mock-api/          # Backend planning
│       └── content.json   # Sample data structure
│
└── backend/               # Future: Go backend
    ├── main.go           # Future: HTTP server
    ├── api/              # Future: REST endpoints
    └── storage/          # Future: file-based storage

Development Scripts

• npm run dev - Start development server with live reload
• npm run dev:about - Start server opening about page
• npm run build - Future: Bundle library for distribution
• npm run test - Future: Run tests
• npm run lint - Future: Code linting

Testing Different Scenarios

Content Types

• Simple Text: Logo, titles, short descriptions
• Rich Content: Paragraphs with markdown, lists, links
• Mixed Content: Cards with multiple editable sections

User Flows

1. First Visit: Customer sees clean site
2. Client Login: Authentication state changes
3. Edit Mode: Toggle editing interface
4. Content Editing: Click edit → modify → save
5. Multi-page: Test persistence across pages

Browser Testing

Test in different browsers to ensure compatibility:

• Chrome/Edge (Chromium)
• Firefox
• Safari (if on macOS)

Future Development Phases

Phase 2: Backend Integration

• Go HTTP server with REST API
• Real authentication with Authentik OAuth
• File-based content persistence
• Git version control

Phase 3: Production Features

• Multi-tenant support
• Admin dashboard
• Content validation
• Image upload
• Deployment automation

Contributing Guidelines

1. Make changes in small, focused commits
2. Test thoroughly across different content types
3. Update documentation when adding new features
4. Follow existing code style and patterns

Debugging Tips

JavaScript Console

• Open browser dev tools (F12)
• Check for errors in Console tab
• Use window.insertr to inspect library state

Local Storage

• View saved content: localStorage.getItem('insertr_content')
• Clear saved content: localStorage.clear()

Network Simulation

• The library simulates network delays and occasional failures
• Check browser Network tab to see mock API calls (when implemented)

Common Issues

Live Server Not Working

• Ensure port 3000 is available
• Try different port: live-server demo-site --port=3001

Changes Not Reflecting

• Hard refresh browser (Ctrl+F5 / Cmd+Shift+R)
• Check browser cache settings
• Verify file paths are correct

Edit Buttons Not Showing

• Check authentication state (click "Login as Client")
• Enable edit mode (click "Edit Mode: Off" → "Edit Mode: On")
• Verify elements have class="insertr" and data-content-id