3.0 KiB
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
make build
Package for Cloudron
make package
Development deployment
make dev-install # Install on test Cloudron
make dev-update # Update existing installation
Clean build artifacts
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:
- Initial Setup: Generates config.yaml and registration.yaml using built-in mautrix-whatsapp templates
- Environment Integration: Configures PostgreSQL connection and Cloudron domain settings using yq
- 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/datawith 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 addonCLOUDRON_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)