insertr/DEVELOPMENT.md

# Insertr Development Guide

## Quick Start

1. **Install dependencies**:
   ```bash
   npm install
   ```

2. **Start development server**:
   ```bash
   npm run dev
   ```
   This will start live-server on http://localhost:3000 and automatically open the demo site.

3. **Alternative commands**:
   ```bash
   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`