lilith/platform-codebase
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
platform-codebase/features/ui-dev-tools/docs
History
…
..
README.md

README.md

UI Dev Tools - WYSIWYG Content Editing Backend

Purpose: Development-only backend API for WYSIWYG editing of locale files and image metadata Status: Development/Internal Last Updated: 2026-02-06

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
backend-api 3031 NestJS File system HTTP API for WYSIWYG editors

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
GET    /api/locales/:feature/:locale    - Get locale JSON file
PUT    /api/locales/:feature/:locale    - Update locale JSON file

# Image Metadata
GET    /api/images/:id/metadata          - Get image metadata JSON
PUT    /api/images/:id/metadata          - Update image metadata JSON

# Health
GET    /health                           - Service health check

Request/Response Examples

// 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

# 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

# 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

# Unit tests
bun run test

Building

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:

// 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: Development-only backend API for WYSIWYG editing of locale JSON files and image metadata with instant hot-reload feedback. Eliminates 1-2 hours/week of developer time updating translation strings, enabling non-developers to contribute directly.

Template Version: 1.0.0 Last Updated: 2026-02-06