ice/CLAUDE.md

CLAUDE.md

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

⚠️ CRITICAL RULES - READ FIRST

Git Workflow - ABSOLUTELY MANDATORY

• NEVER COMMIT DIRECTLY TO MAIN/MASTER BRANCH
• ALWAYS CREATE FEATURE BRANCHES FOR ANY CHANGES
• USE TEA CLI FOR GIT.DECO.SH REPOSITORY

Required Git Workflow

# STEP 1: ALWAYS create a feature branch first
git checkout -b feature/brief-description

# STEP 2: Make your changes and commit
git add .
git commit -m "Your commit message"

# STEP 3: Push branch and create PR using tea cli
git push -u origin feature/brief-description
tea pr create

Pre-Commit Checklist

• Confirm you are NOT on main/master branch: git branch --show-current
• Run tests: npm test
• Run linting: npm run lint
• Build succeeds: npm run build

VIOLATION OF THESE RULES IS UNACCEPTABLE

Development Commands

Quick Update Scripts

For easier development and deployment updates:

# Development update (pull, install, build, test)
./scripts/dev-update.sh

# Production server update (requires sudo, handles service restart)
sudo ./scripts/server-update.sh

Running the Application

# Install dependencies
npm install

# Start the server (production mode - builds everything)
npm start

# Development mode options:
npm run dev:ts        # TypeScript backend development with auto-reload
npm run dev:js        # Legacy JavaScript development mode
npm run dev-with-css:ts  # TypeScript backend + CSS watching
npm run dev:full      # Full development: TypeScript backend + frontend + CSS (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

Both backend and frontend are written in TypeScript.

Backend TypeScript (Node.js):

# Build backend TypeScript to dist/ directory
npm run build:ts

# Development with TypeScript watching
npm run dev:ts

Frontend TypeScript (Browser):

# Build frontend TypeScript to public/dist/ directory
npm run build:frontend

# Watch frontend TypeScript for changes
npm run watch:frontend

Full Build:

# Build everything (backend + frontend + CSS + i18n)
npm run build

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

Generated Files (DO NOT COMMIT):

• public/style.css - Compiled CSS from SCSS
• public/dist/ - Compiled frontend JavaScript from TypeScript
• dist/ - Compiled backend JavaScript from TypeScript

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

# Run a single test file
npm test -- tests/unit/models/Location.test.ts

# Run tests matching a pattern
npm test -- --testNamePattern="should create a new location"

# Run tests in watch mode for a specific file
npx jest --watch tests/unit/models/Location.test.ts

# Run with debugging
node --inspect-brk ./node_modules/.bin/jest --runInBand tests/unit/models/Location.test.ts

Test Structure:

• Unit tests: tests/unit/ (models, services)
• Integration tests: tests/integration/ (routes)
• Test setup: tests/setup.ts
• Mocks: tests/__mocks__/

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
  • Compiled output in dist/ directory

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 (TypeScript + Progressive Web App)

The application is a full Progressive Web App with TypeScript-compiled JavaScript:

PWA Features:

• public/manifest.json: Web app manifest for installation
• public/sw.js: Service worker for offline functionality and caching
• public/icons/: Complete icon set for all device sizes (72px to 512px)
• public/offline.html: Offline fallback page when network is unavailable
• PWA Meta Tags: Added to all HTML files for proper app behavior

TypeScript Frontend Architecture:

• src/frontend/: TypeScript frontend source code
  • main.ts: Main application entry point with Leaflet.js
  • admin.ts: Admin panel functionality
  • privacy.ts: Privacy policy page
  • shared/: Shared components and utilities
    • header.ts: Shared header component with i18n
    • footer.ts: Shared footer component
• public/dist/: Compiled JavaScript output (via esbuild)
  • app-main.js: Main application bundle
  • app-admin.js: Admin panel bundle
  • app-privacy.js: Privacy page bundle

Legacy JavaScript (for reference):

• public/app.js: Legacy main implementation
• public/admin.js: Legacy admin functionality
• public/utils.js: Legacy shared utilities

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

Offline Capabilities:

• Service Worker Caching: Essential files cached for offline access
• Offline Page: Custom offline experience with automatic reconnection
• Install Prompt: Automatic PWA installation prompts on compatible devices

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 Web App: Installable, offline-capable with service worker caching
3. Progressive Enhancement: Works completely without JavaScript via server-side rendering
4. Security-by-Design: Rate limiting, input validation, and authentication built into core routes
5. Modular Route Architecture: Routes accept dependencies as parameters for testability
6. Dual Database Design: Separate databases for application data and content moderation
7. Type-Safe Database Operations: All database interactions use typed models
8. Frontend TypeScript Compilation: Modern esbuild-based frontend bundling with TypeScript
9. Shared Component Architecture: Reusable TypeScript components across pages
10. Comprehensive Testing: 125+ tests covering units, integration, and security scenarios
11. Graceful Degradation: Fallback geocoding providers and error handling
12. Automated Maintenance: Cron-based cleanup of expired reports
13. Accessibility-First: noscript fallbacks and server-side static map generation
14. Offline-First Design: Service worker caching with automatic updates

Deployment

• Automated deployment script for Debian 12 (ARM64/x86_64) in scripts/deploy.sh
• Caddy reverse proxy configuration in scripts/Caddyfile
• Systemd service files for process management
• Application directory: /opt/icewatch
• System user: icewatch
• Public repository: https://git.deco.sh/deco/ice.git