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
```bash
# 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:

```bash
# 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
```bash
# 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):**
```bash
# Build backend TypeScript to dist/ directory
npm run build:ts

# Development with TypeScript watching
npm run dev:ts
```

**Frontend TypeScript (Browser):**
```bash
# Build frontend TypeScript to public/dist/ directory
npm run build:frontend

# Watch frontend TypeScript for changes
npm run watch:frontend
```

**Full Build:**
```bash
# Build everything (backend + frontend + CSS + i18n)
npm run build
```

### 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
```

**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
```bash
# Run ESLint to check code style and quality
npm run lint

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

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