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 - TypeScript)
npm start

# Development mode options:
npm run dev           # TypeScript development with auto-reload
npm run dev:js        # Legacy JavaScript development mode
npm run dev-with-css:ts  # TypeScript + CSS watching (recommended)
npm run dev-with-css     # Legacy JS + CSS watching

The application runs on port 3000 by default. Visit http://localhost:3000 to view the website.

API Documentation

Interactive OpenAPI/Swagger documentation is available at /api-docs when the server is running:

• Development: http://localhost:3000/api-docs
• Production: https://yourapp.com/api-docs

The documentation includes:

• Complete API endpoint specifications
• Request/response schemas and examples
• Authentication requirements
• Interactive testing interface

TypeScript Development

The backend is written in TypeScript and compiles to dist/ directory.

# Build TypeScript (production)
npm run build:ts

# Build everything (TypeScript + CSS)
npm run build

# Development with TypeScript watching
npm run dev:ts

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

Code Quality

# Run ESLint to check code style and quality
npm run lint

# Auto-fix ESLint issues where possible
npm run lint:fix

Testing

# Run all tests (128+ tests with TypeScript)
npm test

# Run tests with coverage report (76% overall coverage)
npm run test:coverage

Test Coverage:

• Unit Tests: Location/ProfanityWord models, DatabaseService, ProfanityFilterService
• Integration Tests: Public API routes, Admin API routes with authentication
• Security Tests: Rate limiting, input validation, authentication flows
• Coverage: 76% statements, 63% branches, 78% lines

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 and static map generation (get free token at https://account.mapbox.com/access-tokens/)
  • Important: For server-side static map generation, use an unrestricted token (no URL restrictions)
• ADMIN_PASSWORD: Password for admin panel access at /admin
• PORT: Server port (default: 3000)

Architecture Overview

Backend (Node.js/Express + TypeScript)

• src/server.ts: Main Express server with modular route architecture (compiles to dist/server.js)
  • 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
  • Full TypeScript with strict type checking

Route Architecture

Routes are organized as factory functions accepting dependencies with full TypeScript typing:

• src/routes/config.ts: Public API configuration endpoints
• src/routes/locations.ts: Location submission and retrieval with profanity filtering
• src/routes/admin.ts: Admin panel functionality with authentication middleware

Models & Services (TypeScript)

• src/models/Location.ts: Type-safe database operations for location data
• src/models/ProfanityWord.ts: Type-safe database operations for profanity words
• src/services/DatabaseService.ts: Centralized database connection management
• src/services/ProfanityFilterService.ts: Content moderation with type safety
• src/services/MapImageService.ts: Server-side static map generation using Mapbox Static Images API
• src/types/index.ts: Shared TypeScript interfaces and type definitions

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 (Progressive Enhancement)

The application uses progressive enhancement to work with and without JavaScript:

JavaScript-Enhanced Experience:

• public/app.js: Main implementation using Leaflet.js

  • Auto-detects available geocoding services (Mapbox preferred, Nominatim fallback)
  • Interactive map with real-time updates
  • Autocomplete and form validation

• 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

• public/utils.js: Shared utilities across implementations

Non-JavaScript Fallback:

• Server-side /table route: Complete HTML table view of all locations
• HTML form submission: Works via POST to /submit-report endpoint
• Static map generation: Auto-fitted Mapbox static images showing all report locations
• Progressive enhancement: noscript tags and "Basic View" button for accessibility

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 (rate limited: 10/15min per IP)
  • Input Validation: Address ≤500 chars, Description ≤1000 chars, coordinate validation
  • Profanity Filtering: Automatic content moderation with rejection
  • Security: Rate limiting prevents spam and DoS attacks

Server-side routes (Progressive Enhancement):

• GET /: Main application page with JavaScript-enhanced features
• GET /table: Non-JavaScript table view with static map and HTML forms
• POST /submit-report: Server-side form submission for non-JavaScript users
• GET /map-image.png: Dynamic static map generation using Mapbox Static Images API
  • Auto-fit positioning: Centers on actual location coordinates
  • Numbered pins: Color-coded markers (red=regular, orange=persistent)
  • Query parameters: ?width=800&height=600&padding=50 for customization

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 (admin-only)
• Profanity management: /api/admin/profanity-words (GET, POST, PUT, DELETE)

Security Features:

• Rate Limiting: Express-rate-limit middleware on public endpoints
• Authentication: Bearer token authentication for admin routes
• Input Validation: Strict length limits and type checking
• Audit Logging: Suspicious activity detection and logging

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. TypeScript-First Architecture: Full type safety with strict type checking
2. Progressive Enhancement: Works completely without JavaScript via server-side rendering
3. Security-by-Design: Rate limiting, input validation, and authentication built into core routes
4. Modular Route Architecture: Routes accept dependencies as parameters for testability
5. Dual Database Design: Separate databases for application data and content moderation
6. Type-Safe Database Operations: All database interactions use typed models
7. Comprehensive Testing: 125+ tests covering units, integration, and security scenarios
8. Graceful Degradation: Fallback geocoding providers and error handling
9. Automated Maintenance: Cron-based cleanup of expired reports
10. Accessibility-First: noscript fallbacks and server-side static map generation

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