# CLAUDE.md

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

## Project Overview

This is a Cloudron package for the mautrix-whatsapp Matrix-WhatsApp bridge. It wraps the Go implementation of mautrix-whatsapp into a Cloudron-compatible app with automatic configuration, database setup, and health monitoring.

## Build and Development Commands

### Build the Docker image
```bash
make build
```

### Package for Cloudron
```bash
make package
```

### Development deployment
```bash
make dev-install    # Install on test Cloudron
make dev-update     # Update existing installation
```

### Clean build artifacts
```bash
make clean
```

## Architecture

### Core Components
- **Dockerfile.cloudron**: Multi-stage build using Go compiler with Cloudron base image
- **start.sh**: Bootstrap script handling configuration generation and WhatsApp authentication setup
- **CloudronManifest.json**: Defines PostgreSQL and localstorage addons, health check endpoint on port 29318

### Configuration Flow
The start.sh script implements a streamlined configuration process:

1. **Initial Setup**: Generates config.yaml and registration.yaml using built-in mautrix-whatsapp templates
2. **Environment Integration**: Configures PostgreSQL connection and Cloudron domain settings using yq
3. **Authentication Ready**: Sets up for WhatsApp QR code authentication workflow

### Key Design Patterns
- Uses Go binary compiled during Docker build for optimal performance
- All data persisted to `/app/data` with proper cloudron user ownership  
- Configuration via yq YAML manipulation for cleaner updates
- Health check implemented using netcat since bridge doesn't provide native endpoint
- PostgreSQL connection string automatically injected from Cloudron addon

### Environment Integration
- `CLOUDRON_POSTGRESQL_URL`: Database connection from PostgreSQL addon
- `CLOUDRON_APP_DOMAIN`: Used to derive Matrix homeserver domain and appservice URL
- Automatic domain extraction for homeserver configuration
- Port 29318 for appservice and health check endpoints

## Development Notes

### Go Binary Management
The bridge binary is built during Docker image creation from the official mautrix-whatsapp repository. Version updates require updating the git clone in Dockerfile.cloudron.

### Database Schema
Uses PostgreSQL addon for persistence. The bridge handles its own schema migrations via the mautrix-whatsapp package.

### WhatsApp Authentication
Unlike Telegram bridges, WhatsApp authentication requires QR code scanning or pairing codes. The bridge provides interactive authentication commands after startup.

### Health Monitoring
Custom health check endpoint created using netcat on port 29318 since the bridge doesn't provide native health endpoints.

### Configuration Differences from Telegram Bridge
- Go-based instead of Python (single binary deployment)
- Simpler configuration workflow (no complex token synchronization)
- WhatsApp Web protocol authentication instead of API tokens
- Different port allocation (29318 vs 29317)