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

Testing

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

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. Security-by-Design: Rate limiting, input validation, and authentication built into core routes
3. Modular Route Architecture: Routes accept dependencies as parameters for testability
4. Dual Database Design: Separate databases for application data and content moderation
5. Type-Safe Database Operations: All database interactions use typed models
6. Comprehensive Testing: 125+ tests covering units, integration, and security scenarios
7. Graceful Degradation: Fallback geocoding providers and error handling
8. Automated Maintenance: Cron-based cleanup of expired reports

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