a0fffcf4f0
Major architectural improvements: - Created models/services layer for better separation of concerns - Location model with async methods for database operations - ProfanityWord model for content moderation - DatabaseService for centralized database management - ProfanityFilterService refactored to use models - Refactored frontend map implementations to share common code - MapBase class extracts 60-70% of duplicate functionality - Refactored implementations extend MapBase for specific features - Maintained unique geocoding capabilities per implementation - Updated server.js to use new service architecture - All routes now use async/await with models instead of raw queries - Enhanced error handling and maintainability 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
143 lines
No EOL
4.6 KiB
Markdown
143 lines
No EOL
4.6 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Development Commands
|
|
|
|
### Running the Application
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Start the server (production mode)
|
|
npm start
|
|
|
|
# Start with auto-reload (development mode)
|
|
npm run dev
|
|
|
|
# Development with CSS watching (recommended for frontend work)
|
|
npm run dev-with-css
|
|
```
|
|
|
|
The application runs on port 3000 by default. Visit http://localhost:3000 to view the website.
|
|
|
|
### CSS Development
|
|
CSS is generated from SCSS and should NOT be committed to git.
|
|
```bash
|
|
# Build CSS once (compressed for production)
|
|
npm run build-css
|
|
|
|
# Build CSS with source maps (for development)
|
|
npm run build-css:dev
|
|
|
|
# Watch SCSS files and auto-compile changes
|
|
npm run watch-css
|
|
```
|
|
|
|
### Testing
|
|
```bash
|
|
# Run all tests
|
|
npm test
|
|
|
|
# Run tests with coverage report
|
|
npm run test:coverage
|
|
```
|
|
|
|
### Environment Setup
|
|
Before running the application, you must configure environment variables:
|
|
```bash
|
|
cp .env.example .env
|
|
# Edit .env to add your MapBox token and admin password
|
|
```
|
|
|
|
Required environment variables:
|
|
- `MAPBOX_ACCESS_TOKEN`: MapBox API token for geocoding (get free token at https://account.mapbox.com/access-tokens/)
|
|
- `ADMIN_PASSWORD`: Password for admin panel access at /admin
|
|
- `PORT`: Server port (default: 3000)
|
|
|
|
## Architecture Overview
|
|
|
|
### Backend (Node.js/Express)
|
|
- **server.js**: Main Express server with modular route architecture
|
|
- Uses two SQLite databases: `icewatch.db` (locations) and `profanity.db` (content moderation)
|
|
- Automatic cleanup of reports older than 48 hours via node-cron
|
|
- Bearer token authentication for admin endpoints
|
|
- Environment variable configuration via dotenv
|
|
|
|
### Route Architecture
|
|
Routes are organized as factory functions accepting dependencies:
|
|
|
|
- **routes/config.js**: Public API configuration endpoints
|
|
- **routes/locations.js**: Location submission and retrieval with profanity filtering
|
|
- **routes/admin.js**: Admin panel functionality with authentication middleware
|
|
|
|
### Database Schema
|
|
**Main Database (`icewatch.db`)**:
|
|
```sql
|
|
CREATE TABLE locations (
|
|
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
address TEXT NOT NULL,
|
|
latitude REAL,
|
|
longitude REAL,
|
|
timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
|
|
description TEXT,
|
|
persistent INTEGER DEFAULT 0,
|
|
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
|
|
);
|
|
```
|
|
|
|
**Profanity Database (`profanity.db`)**:
|
|
Managed by the `ProfanityFilter` class for content moderation.
|
|
|
|
### Frontend (Vanilla JavaScript)
|
|
Multiple map implementations for flexibility:
|
|
|
|
- **public/app.js**: Main implementation using Leaflet.js
|
|
- Auto-detects available geocoding services (MapBox preferred, Nominatim fallback)
|
|
|
|
- **public/app-mapbox.js**: MapBox GL JS implementation for enhanced features
|
|
|
|
- **public/app-google.js**: Google Maps implementation (alternative)
|
|
|
|
- **public/admin.js**: Admin panel functionality
|
|
- Location management (view, edit, delete)
|
|
- Persistent location toggle
|
|
- Profanity word management
|
|
|
|
- **public/utils.js**: Shared utilities across implementations
|
|
|
|
### API Endpoints
|
|
|
|
Public endpoints:
|
|
- `GET /api/config`: Returns MapBox token for frontend geocoding
|
|
- `GET /api/locations`: Active locations (< 48 hours old or persistent)
|
|
- `POST /api/locations`: Submit new location report (with profanity filtering)
|
|
|
|
Admin endpoints (require Bearer token):
|
|
- `POST /api/admin/login`: Authenticate and receive token
|
|
- `GET /api/admin/locations`: All locations including expired
|
|
- `PUT /api/admin/locations/:id`: Update location details
|
|
- `PATCH /api/admin/locations/:id/persistent`: Toggle persistent status
|
|
- `DELETE /api/admin/locations/:id`: Delete location
|
|
- Profanity management: `/api/admin/profanity-words` (GET, POST, PUT, DELETE)
|
|
|
|
### SCSS Organization
|
|
SCSS files are in `src/scss/`:
|
|
- `main.scss`: Entry point importing all other files
|
|
- `_variables.scss`: Theme colors and configuration
|
|
- `_mixins.scss`: Reusable style patterns
|
|
- `pages/`: Page-specific styles (home, admin, privacy)
|
|
- `components/`: Component styles (navbar, map, cards, forms)
|
|
|
|
### Key Design Patterns
|
|
|
|
1. **Modular Route Architecture**: Routes accept dependencies as parameters for testability
|
|
2. **Dual Database Design**: Separate databases for application data and content moderation
|
|
3. **Graceful Degradation**: Fallback geocoding providers and error handling
|
|
4. **Automated Maintenance**: Cron-based cleanup of expired reports
|
|
5. **Security**: Server-side content filtering, environment-based configuration
|
|
|
|
### Deployment
|
|
- Automated deployment script for Debian 12 ARM64 in `scripts/deploy.sh`
|
|
- Caddy reverse proxy configuration in `scripts/Caddyfile`
|
|
- Systemd service files for process management |