Skip to content

Commit 4edb6de

Browse files
airsliceairslice
authored
chore: update documents (#8)
1 parent d47e5d0 commit 4edb6de

File tree

4 files changed

+190
-1
lines changed

4 files changed

+190
-1
lines changed

‎README.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# Re:Earth Visualizer Plugin with Backend Demo
2+
3+
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.
4+
5+
## Project Structure
6+
7+
This repository contains three main components:
8+
9+
- **`/plugin`** - Re:Earth Visualizer plugin frontend (React + TypeScript)
10+
- **`/server`** - Backend API server (Node.js + TypeScript, Vercel deployment)
11+
- **Root** - Main project configuration and coordination
12+
13+
## Architecture Overview
14+
15+
The project demonstrates a complete workflow:
16+
17+
1. **Plugin Frontend** creates interactive visualizations in Re:Earth
18+
2. **Backend Server** manages data persistence and CMS integration
19+
3. **Integration** between plugin and server via REST API
20+
21+
## Key Features
22+
23+
- Street photography visualization plugin for Re:Earth Visualizer
24+
- CMS integration for data management
25+
- Image upload and processing capabilities
26+
- **Security features** - Rate limiting and honeypot protection
27+
- TypeScript throughout the stack
28+
- Modern tooling (Vite, Vercel, ShadCN/UI)
29+
30+
## Quick Start
31+
32+
### Prerequisites
33+
34+
- Node.js >= 20.11.0
35+
- Yarn package manager
36+
37+
### 1. Setup Backend Server
38+
39+
```bash
40+
cd server
41+
yarn install
42+
cp .env.example .env
43+
# Configure environment variables in .env
44+
yarn dev:local
45+
```
46+
47+
### 2. Setup Plugin Frontend
48+
49+
```bash
50+
cd plugin
51+
yarn install
52+
yarn dev-build
53+
```
54+
55+
### 3. Integration with Re:Earth Visualizer
56+
57+
1. Run Re:Earth Visualizer locally
58+
2. Set environment variable: `REEARTH_WEB_DEV_PLUGIN_URLS='["http://localhost:5005"]'`
59+
3. Use development buttons in Re:Earth editor to install and reload the plugin
60+
61+
## Development Workflow
62+
63+
Each component can be developed independently:
64+
65+
```bash
66+
# Plugin development
67+
cd plugin && yarn dev-build
68+
69+
# Server development
70+
cd server && yarn dev:local
71+
```
72+
73+
## Tech Stack
74+
75+
### Frontend Plugin
76+
77+
- React 19.1.0 + TypeScript 5.7.2
78+
- Vite 6.0.3 for build tooling
79+
- TailwindCSS 4.1.10 + ShadCN/UI
80+
- Re:Earth Core API integration
81+
82+
### Backend Server
83+
84+
- Node.js 22.x + TypeScript 5.9.3
85+
- Vercel serverless functions
86+
- Re:Earth CMS integration
87+
- Rate limiting and honeypot security features
88+
- Comprehensive test coverage with Vitest
89+
90+
## API Endpoints
91+
92+
- `GET /api/photographs` - Retrieve street photographs
93+
- `POST /api/photographs` - Create new photograph entry
94+
- `POST /api/assets/upload` - Upload image files
95+
96+
## Testing
97+
98+
```bash
99+
# Server tests
100+
cd server && yarn test
101+
102+
# Plugin linting and type checking
103+
cd plugin && yarn lint && yarn type
104+
```
105+
106+
## Deployment
107+
108+
### Backend (Vercel)
109+
110+
1. Connect repository to Vercel
111+
2. Configure environment variables
112+
3. Deploy automatically on push
113+
114+
### Plugin
115+
116+
1. Build with `cd plugin && yarn build`
117+
2. Upload generated zip file from `plugin/package/`
118+
3. Install in Re:Earth Visualizer
119+
120+
## Documentation
121+
122+
For detailed instructions, see the README files in each subdirectory:
123+
124+
- [Plugin README](./plugin/README.md) - Frontend development guide
125+
- [Server README](./server/README.md) - Backend API documentation
126+
127+
## License
128+
129+
This project is licensed under the MIT License - see individual component licenses for details.

‎plugin/AGENTS.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ A Re:Earth Visualizer plugin that provides interactive street photography visual
1616
- **TailwindCSS 4.1.10** with ShadCN/UI components
1717
- **Radix UI** primitives for accessible components
1818
- **Re:Earth Core** 0.0.7-alpha.38 for plugin API
19+
- **Security features** - Honeypot protection for bot prevention
1920

2021
## Architecture
2122

@@ -76,6 +77,19 @@ yarn format # Format with Prettier
7677
yarn type # TypeScript type checking
7778
```
7879

80+
## Security Features
81+
82+
### Honeypot Protection
83+
84+
The submitter form includes client-side honeypot protection:
85+
86+
- **Hidden field** - `website` input field hidden via CSS (`.hp` class)
87+
- **Bot detection** - Client-side validation rejects submissions with filled honeypot
88+
- **Silent rejection** - Prevents form submission without alerting bots
89+
- **Accessibility** - Properly configured with `tabIndex={-1}` and `aria-hidden`
90+
91+
Works with server-side honeypot validation for comprehensive bot protection.
92+
7993
## Backend Integration
8094

8195
This plugin integrates with the companion server (../server) for:

‎plugin/README.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ This template provides a minimal setup to develop a Re:Earth Visualizer Plugin w
88
- **Vite 6.0.3** for build tooling
99
- **TailwindCSS 4.1.10** for styling
1010
- **Radix UI** components with **ShadCN/UI**
11+
- **Security features** - Honeypot protection against bots
1112

1213
## Re:Earth Visualizer Plugin Structure
1314

@@ -161,6 +162,20 @@ yarn preview
161162

162163
Starts the preview server on port `5005`.
163164

165+
## Security Features
166+
167+
### Honeypot Protection
168+
169+
The street photography submitter includes honeypot protection to prevent automated bot submissions:
170+
171+
- **Hidden Website Field** - A hidden `website` input field (`src/extensions/sp_submitter/submitter/App.tsx:157-167`)
172+
- **CSS Concealment** - Field is hidden using `.hp` class with `display: none` (`src/extensions/sp_submitter/submitter/app.css:5-8`)
173+
- **Accessibility Considerations** - Field includes `tabIndex={-1}`, `autoComplete="off"`, and `aria-hidden="true"`
174+
- **Client-side Validation** - Submissions are silently rejected if honeypot field is filled (`src/extensions/sp_submitter/submitter/hooks.ts:121-123`)
175+
- **Bot Detection** - Legitimate users won't see or fill the field, while bots typically fill all form fields
176+
177+
The honeypot works in conjunction with server-side validation for complete bot protection.
178+
164179
## Development Workflow with Re:Earth Visualizer
165180

166181
### Traditional Way

‎server/README.md‎

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@ Node.js server for Re-Earth visualizer plugin with CMS integration, designed for
99
- Image upload handling
1010
- JWT authentication
1111
- CORS support
12+
- **Rate limiting** - IP-based request throttling
13+
- **Honeypot protection** - Bot detection and silent blocking
1214
- TypeScript support
1315

1416
## API Endpoints
@@ -89,18 +91,47 @@ Deploy to Vercel:
8991
2. Set environment variables in Vercel dashboard
9092
3. Deploy automatically on push to main branch
9193

94+
## Security Features
95+
96+
### Rate Limiting
97+
98+
The server implements IP-based rate limiting to prevent abuse:
99+
100+
- **General API**: 30 requests per minute per IP
101+
- **Photograph Creation**: 30 requests per 15 minutes per IP
102+
- Returns appropriate HTTP 429 status and `Retry-After` headers
103+
- Automatic cleanup of expired rate limit entries
104+
105+
Rate limit headers included in responses:
106+
- `X-RateLimit-Limit` - Maximum requests allowed
107+
- `X-RateLimit-Remaining` - Requests remaining in current window
108+
- `X-RateLimit-Reset` - Time when rate limit resets
109+
110+
### Honeypot Protection
111+
112+
Protection against automated bot submissions:
113+
114+
- Hidden `website` field in photograph submission forms
115+
- Legitimate users won't fill this field (hidden via CSS)
116+
- Bots often fill all available form fields
117+
- Submissions with filled `website` field are silently rejected
118+
- Returns successful response to avoid tipping off bots
119+
92120
## Project Structure
93121

94122
```
95123
server/
96124
├── api/ # Vercel serverless functions
97-
│ ├── photographs.ts # Photographs endpoint
125+
│ ├── photographs.ts # Photographs endpoint with rate limiting & honeypot
98126
│ └── assets/
99127
│ └── upload.ts # Upload endpoint
100128
├── src/
101129
│ ├── services/ # Business logic
102130
│ ├── types/ # TypeScript types
103131
│ └── utils/ # Utility functions
132+
│ ├── rateLimiter.ts # Rate limiting implementation
133+
│ ├── validation.ts # Request validation with honeypot
134+
│ └── ...
104135
├── docs/ # API documentation
105136
└── package.json
106137
```

0 commit comments

Comments
 (0)