ice/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

Running the Application

# 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.

# 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

# 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:

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):

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