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
```bash
# 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.
```bash
# 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.
```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 (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:
```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 + 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`)**:
```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 (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