# 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)
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.
```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
npm test

# Run tests with coverage report
npm run test:coverage
```

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