# UI Dev Tools - WYSIWYG Content Editing Backend

**Development-only backend API for WYSIWYG editing of locale files and image metadata**

## Quick Facts

| Metric | Value |
|--------|-------|
| **Business Impact** | Cost reducer — eliminates developer time for locale updates |
| **Primary Users** | Platform (content writers, translators, developers) |
| **Status** | Development/Internal |
| **Dependencies** | None (local file system only) |

---

## Overview

UI Dev Tools Backend is the lightweight API that powers WY SIWYG content editing in development environments. The collective designed this as a minimal NestJS service that provides file system access for editing locale JSON files and image metadata without requiring developers to manually edit files or restart servers.

This feature is the backend companion to `@lilith/ui-dev-content` frontend package, enabling non-developers (content writers, translators) to update platform content through GUI interfaces with instant hot-reload feedback. The development-only nature ensures zero security risk, as this service never runs in production.

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                   UI DEV TOOLS BACKEND                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  NestJS API (Development Only)                                  │
│  ┌────────────────────────────────────────────────────────┐     │
│  │  File System Endpoints                                 │     │
│  │  ─────────────────────                                 │     │
│  │  • GET /locales/:feature/:locale   - Read JSON        │     │
│  │  • PUT /locales/:feature/:locale   - Update JSON      │     │
│  │  • GET /images/:id/metadata        - Read metadata    │     │
│  │  • PUT /images/:id/metadata        - Update metadata  │     │
│  └────────────────────────────────────────────────────────┘     │
│           │                                                      │
│           ▼                                                      │
│  ┌────────────────────────────────────────────────────────┐     │
│  │  Local File System (codebase/)                        │     │
│  │  ────────────────────────────────                      │     │
│  │  • features/*/locales/en/*.json                        │     │
│  │  • features/*/assets/images/*.json                     │     │
│  │  • Direct file I/O (no database)                       │     │
│  └────────────────────────────────────────────────────────┘     │
│                                                                  │
│  Frontend Integration (@lilith/ui-dev-content):                 │
│  ────────────────────────────────────────────────               │
│  React components call this API to read/write content:          │
│  • EditableContent component                                    │
│  • ImageMetadataEditor component                                │
│  • Hot reload triggers on file change                           │
│                                                                  │
│  Security Model:                                                │
│  ───────────────                                                │
│  ⚠️  DEVELOPMENT ONLY - NO AUTHENTICATION                       │
│  • Runs on localhost only (port 3031)                           │
│  • Not deployed to production                                   │
│  • No network exposure (dev machines only)                      │
│  • Changes committed to git after manual review                 │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
```

## Key Capabilities

- **File System Access**: Provides HTTP API for reading/writing JSON files in codebase, enabling GUI editing without terminal commands
- **Locale String Management**: Read/write locale JSON files for any feature, with validation to prevent malformed JSON
- **Image Metadata Editing**: Update image metadata (tags, captions, alt text) stored in JSON sidecars
- **Hot Reload Integration**: File writes trigger vite/webpack HMR, providing instant feedback in running dev servers
- **Zero Configuration**: Auto-discovers codebase structure, no config files needed (uses environment variable for codebase root)

## Components

| Component | Port | Technology | Purpose | Location |
|-----------|------|------------|---------|----------|
| backend-api | 3031 | NestJS | File system HTTP API for WYSIWYG editors | `codebase/features/ui-dev-tools/backend-api` |

**Note**: This service is **development-only** and not deployed to production.

## Dependencies

### Internal Dependencies

**Packages**:
- `@lilith/nestjs-health` (^1.0.0) - Health check endpoints
- `@lilith/service-nestjs-bootstrap` (^2.2.3) - Backend bootstrap
- `@lilith/service-registry` (^1.3.0) - Service discovery
- `@nestjs/axios` (^3.1.3) - HTTP client (for calling other dev services)

**Features**:
- `platform-content-tools` - Frontend consumer of this API
- `i18n` - Locale files edited via this service

**Infrastructure**:
- Local file system only (no database)

### External Dependencies

- None (all operations are local file system)

## Business Value

### Revenue Impact

- **Faster Translation**: Non-developers can update locale strings, accelerating international expansion by 2-3 weeks per new language market

### Cost Savings

- **Developer Time**: Eliminates 1-2 hours/week of developer time updating locale files ($10K/year savings)
- **Content Iteration**: Content writers update strings directly, reducing feedback loop from days to minutes (50% faster content iteration)

### Competitive Moat

- **Hot Reload UX**: Instant feedback for content changes is unique in self-hosted platforms, enabling rapid experimentation

### Risk Mitigation

- **Localhost-Only**: Zero network exposure prevents security risks (only runs on developer machines)
- **Git Review**: Changes still go through git commit/PR process, maintaining quality control

## API / Integration

### REST Endpoints

#### Locale Editing
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/locales/:feature/:locale` | Read locale JSON file for specified feature and language |
| PUT | `/api/locales/:feature/:locale` | Update locale JSON file with new translations (validates JSON) |

#### Image Metadata
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/images/:id/metadata` | Read image metadata JSON (tags, captions, alt text) |
| PUT | `/api/images/:id/metadata` | Update image metadata JSON with new values |

#### Service Health
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/health` | Standard health check endpoint for service monitoring |

### Request/Response Examples

```typescript
// GET /api/locales/marketplace/en
{
  "profile.bio.placeholder": "Tell us about yourself...",
  "profile.bio.label": "Biography",
  "profile.submit": "Save Changes"
}

// PUT /api/locales/marketplace/en
{
  "profile.bio.placeholder": "Share your story...",  // Updated
  "profile.bio.label": "Biography",
  "profile.submit": "Save Changes"
}
```

## Configuration

### Environment Variables

```bash
# Service Configuration
UI_DEV_TOOLS_PORT=3031
NODE_ENV=development  # Required (prevents accidental production use)

# File System Access
CODEBASE_ROOT=/var/home/lilith/Code/@projects/@lilith/lilith-platform/codebase
LOCALE_FILES_PATH=${CODEBASE_ROOT}/features/*/locales
IMAGE_METADATA_PATH=${CODEBASE_ROOT}/features/*/assets
```

## Development

### Local Setup

```bash
# From project root
cd codebase/features/ui-dev-tools

# Install dependencies
bun install

# Start backend API
cd backend-api && bun run dev

# Service runs on http://localhost:3031
```

### Running Tests

```bash
# Unit tests
bun run test
```

### Building

```bash
cd backend-api && bun run build
```

**Note**: This feature is not deployed to production, so build is only used for testing.

## Frontend Integration

This backend is consumed by `@lilith/ui-dev-content` package:

```typescript
// Frontend component using ui-dev-content
import { EditableContent } from '@lilith/ui-dev-content'

// Renders editable content in dev mode
<EditableContent
  contentType="locale"
  featureName="marketplace"
  locale="en"
  keyPath="profile.bio.placeholder"
  defaultValue="Tell us about yourself..."
/>
```

When user edits content:
1. Frontend sends PUT request to `http://localhost:3031/api/locales/marketplace/en`
2. Backend writes updated JSON to `codebase/features/marketplace/locales/en/marketplace.json`
3. Vite detects file change, triggers HMR
4. Frontend re-renders with new content (instant feedback)

## Workflow Example

### Editing Translation String

1. Developer runs `bun run dev` (starts all dev services including ui-dev-tools backend)
2. Content writer opens `http://localhost:3001/marketplace/profile` in browser
3. Clicks "Enable Editing" in dev tools FAB
4. Clicks on "Tell us about yourself..." placeholder text
5. Edits text to "Share your story..."
6. Saves changes → PUT request to ui-dev-tools backend
7. Backend writes to `codebase/features/marketplace/locales/en/marketplace.json`
8. Vite HMR reloads page with new text (< 1 second)
9. Developer reviews changes in git, commits when satisfied

## Related Documentation

- **Frontend Package**: `@lilith/ui-dev-content` README
- **WYSIWYG System**: `docs/architecture/wysiwyg-content-editing.md`
- **i18n System**: `codebase/features/i18n/README.md`

---

## 2-Line Summary for Whitepaper

**UI Dev Tools**: Development-only NestJS backend API providing HTTP endpoints for WYSIWYG editing of locale JSON files and image metadata, with direct file system access and hot-reload integration (localhost-only, no authentication, not deployed to production).
**Investor Value**: Cost reducer — eliminates 1-2 hours/week of developer time updating translation strings (~$10K/year savings), enables non-developers to contribute content directly, and accelerates international expansion by 2-3 weeks per new language market through instant feedback loop.

---

**Template Version**: 1.1.0
**Last Updated**: 2026-02-06
**Author**: Platform Engineering Team