reearth-plugins · airslice · Oct 24, 2025 · Oct 24, 2025
diff --git a/README.md b/README.md
@@ -0,0 +1,129 @@
+# Re:Earth Visualizer Plugin with Backend Demo
+
+This is a full-stack demo project showcasing a Re:Earth Visualizer plugin with a backend server integration. The project demonstrates street photography visualization with CMS integration.
+
+## Project Structure
+
+This repository contains three main components:
+
+- **`/plugin`** - Re:Earth Visualizer plugin frontend (React + TypeScript)
+- **`/server`** - Backend API server (Node.js + TypeScript, Vercel deployment)
+- **Root** - Main project configuration and coordination
+
+## Architecture Overview
+
+The project demonstrates a complete workflow:
+
+1. **Plugin Frontend** creates interactive visualizations in Re:Earth
+2. **Backend Server** manages data persistence and CMS integration
+3. **Integration** between plugin and server via REST API
+
+## Key Features
+
+- Street photography visualization plugin for Re:Earth Visualizer
+- CMS integration for data management
+- Image upload and processing capabilities
+- **Security features** - Rate limiting and honeypot protection
+- TypeScript throughout the stack
+- Modern tooling (Vite, Vercel, ShadCN/UI)
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js >= 20.11.0
+- Yarn package manager
+
+### 1. Setup Backend Server
+
+```bash
+cd server
+yarn install
+cp .env.example .env
+# Configure environment variables in .env
+yarn dev:local
+```
+
+### 2. Setup Plugin Frontend
+
+```bash
+cd plugin
+yarn install
+yarn dev-build
+```
+
+### 3. Integration with Re:Earth Visualizer
+
+1. Run Re:Earth Visualizer locally
+2. Set environment variable: `REEARTH_WEB_DEV_PLUGIN_URLS='["http://localhost:5005"]'`
+3. Use development buttons in Re:Earth editor to install and reload the plugin
+
+## Development Workflow
+
+Each component can be developed independently:
+
+```bash
+# Plugin development
+cd plugin && yarn dev-build
+
+# Server development
+cd server && yarn dev:local
+```
+
+## Tech Stack
+
+### Frontend Plugin
+
+- React 19.1.0 + TypeScript 5.7.2
+- Vite 6.0.3 for build tooling
+- TailwindCSS 4.1.10 + ShadCN/UI
+- Re:Earth Core API integration
+
+### Backend Server
+
+- Node.js 22.x + TypeScript 5.9.3
+- Vercel serverless functions
+- Re:Earth CMS integration
+- Rate limiting and honeypot security features
+- Comprehensive test coverage with Vitest
+
+## API Endpoints
+
+- `GET /api/photographs` - Retrieve street photographs
+- `POST /api/photographs` - Create new photograph entry
+- `POST /api/assets/upload` - Upload image files
+
+## Testing
+
+```bash
+# Server tests
+cd server && yarn test
+
+# Plugin linting and type checking
+cd plugin && yarn lint && yarn type
+```
+
+## Deployment
+
+### Backend (Vercel)
+
+1. Connect repository to Vercel
+2. Configure environment variables
+3. Deploy automatically on push
+
+### Plugin
+
+1. Build with `cd plugin && yarn build`
+2. Upload generated zip file from `plugin/package/`
+3. Install in Re:Earth Visualizer
+
+## Documentation
+
+For detailed instructions, see the README files in each subdirectory:
+
+- [Plugin README](./plugin/README.md) - Frontend development guide
+- [Server README](./server/README.md) - Backend API documentation
+
+## License
+
+This project is licensed under the MIT License - see individual component licenses for details.
diff --git a/plugin/AGENTS.md b/plugin/AGENTS.md
@@ -16,6 +16,7 @@ A Re:Earth Visualizer plugin that provides interactive street photography visual
 - **TailwindCSS 4.1.10** with ShadCN/UI components
 - **Radix UI** primitives for accessible components
 - **Re:Earth Core** 0.0.7-alpha.38 for plugin API
+- **Security features** - Honeypot protection for bot prevention
 
 ## Architecture
 
@@ -76,6 +77,19 @@ yarn format               # Format with Prettier
 yarn type                 # TypeScript type checking
 ```
 
+## Security Features
+
+### Honeypot Protection
+
+The submitter form includes client-side honeypot protection:
+
+- **Hidden field** - `website` input field hidden via CSS (`.hp` class)
+- **Bot detection** - Client-side validation rejects submissions with filled honeypot
+- **Silent rejection** - Prevents form submission without alerting bots
+- **Accessibility** - Properly configured with `tabIndex={-1}` and `aria-hidden`
+
+Works with server-side honeypot validation for comprehensive bot protection.
+
 ## Backend Integration
 
 This plugin integrates with the companion server (../server) for:

diff --git a/plugin/README.md b/plugin/README.md
@@ -8,6 +8,7 @@ This template provides a minimal setup to develop a Re:Earth Visualizer Plugin w
 - **Vite 6.0.3** for build tooling
 - **TailwindCSS 4.1.10** for styling
 - **Radix UI** components with **ShadCN/UI**
+- **Security features** - Honeypot protection against bots
 
 ## Re:Earth Visualizer Plugin Structure
 
@@ -161,6 +162,20 @@ yarn preview
 
 Starts the preview server on port `5005`.
 
+## Security Features
+
+### Honeypot Protection
+
+The street photography submitter includes honeypot protection to prevent automated bot submissions:
+
+- **Hidden Website Field** - A hidden `website` input field (`src/extensions/sp_submitter/submitter/App.tsx:157-167`)
+- **CSS Concealment** - Field is hidden using `.hp` class with `display: none` (`src/extensions/sp_submitter/submitter/app.css:5-8`)
+- **Accessibility Considerations** - Field includes `tabIndex={-1}`, `autoComplete="off"`, and `aria-hidden="true"`
+- **Client-side Validation** - Submissions are silently rejected if honeypot field is filled (`src/extensions/sp_submitter/submitter/hooks.ts:121-123`)
+- **Bot Detection** - Legitimate users won't see or fill the field, while bots typically fill all form fields
+
+The honeypot works in conjunction with server-side validation for complete bot protection.
+
 ## Development Workflow with Re:Earth Visualizer
 
 ### Traditional Way

diff --git a/server/README.md b/server/README.md
@@ -9,6 +9,8 @@ Node.js server for Re-Earth visualizer plugin with CMS integration, designed for
 - Image upload handling
 - JWT authentication
 - CORS support
+- **Rate limiting** - IP-based request throttling
+- **Honeypot protection** - Bot detection and silent blocking
 - TypeScript support
 
 ## API Endpoints
@@ -89,18 +91,47 @@ Deploy to Vercel:
 2. Set environment variables in Vercel dashboard
 3. Deploy automatically on push to main branch
 
+## Security Features
+
+### Rate Limiting
+
+The server implements IP-based rate limiting to prevent abuse:
+
+- **General API**: 30 requests per minute per IP
+- **Photograph Creation**: 30 requests per 15 minutes per IP
+- Returns appropriate HTTP 429 status and `Retry-After` headers
+- Automatic cleanup of expired rate limit entries
+
+Rate limit headers included in responses:
+- `X-RateLimit-Limit` - Maximum requests allowed
+- `X-RateLimit-Remaining` - Requests remaining in current window  
+- `X-RateLimit-Reset` - Time when rate limit resets
+
+### Honeypot Protection
+
+Protection against automated bot submissions:
+
+- Hidden `website` field in photograph submission forms
+- Legitimate users won't fill this field (hidden via CSS)
+- Bots often fill all available form fields
+- Submissions with filled `website` field are silently rejected
+- Returns successful response to avoid tipping off bots
+
 ## Project Structure
 
 ```
 server/
 ├── api/                 # Vercel serverless functions
-│   ├── photographs.ts   # Photographs endpoint
+│   ├── photographs.ts   # Photographs endpoint with rate limiting & honeypot
 │   └── assets/
 │       └── upload.ts    # Upload endpoint
 ├── src/
 │   ├── services/        # Business logic
 │   ├── types/           # TypeScript types
 │   └── utils/           # Utility functions
+│       ├── rateLimiter.ts  # Rate limiting implementation
+│       ├── validation.ts   # Request validation with honeypot
+│       └── ...
 ├── docs/                # API documentation
 └── package.json
 ```