# CLAUDE.md

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

## Project Overview

OCR microservice that extracts structured data from Italian training/certification PDF documents. Extracts employee name, training end date, and course/protocol code.

## Tech Stack

- PHP 7/8 with Imagick extension
- Tesseract OCR (Italian language pack)
- Docker/Docker Compose
- Apache 2

## Build & Run

```bash
# Build and start the service
docker-compose up --build

# Service available at http://localhost:8081/ocrpdf.php
```

## Testing

```bash
# Send a test PDF
curl -X POST -F "pdf=@app/trotta.pdf" http://localhost:8081/ocrpdf.php

# Or use the PHP test script
php send_pdf.php
```

Test PDFs are located in `/app/` directory.

## Architecture

**Processing Pipeline** (ocrpdf.php):
1. PDF uploaded via POST multipart/form-data
2. ImageMagick converts first page to PNG (150 DPI, grayscale), full page (no crop)
3. Tesseract OCR extracts Italian text (160s timeout)
4. Regex patterns extract: employee name (`conferito a`, case-insensitive), release date ("Periodo della formazione"), course code ("Protocollo" or "Mansione")
5. Returns JSON response

> **Nota template (giu 2026):** l'associazione A.D.L.I. ha cambiato il modello degli
> attestati. L'ancora del nome è passata da `Conferito a` (maiuscolo) a `conferito a`
> (minuscolo) e il blocco firma "Responsabile del / Progetto Formativo" è ora affiancato
> al nome su due colonne. Per questo l'OCR usa la **pagina intera** (il vecchio crop
> 25%/5% frammentava il nome dei corsi e-learning) e la regex del nome salta
> "Responsabile del" e cattura solo i token MAIUSCOLI. Data e Protocollo non sono
> cambiati. Vedi commit `cfd7abf`.

**Response format**:
```json
{
  "status": "success",
  "data": {
    "course_name": "547A",
    "employee_name": "JOHN DOE",
    "release_date": "23/10/2024"
  }
}
```

## Key Files

- `ocrpdf.php` - Main OCR endpoint with all processing logic
- `send_pdf.php` - Test client for sending PDFs
- `Dockerfile` - Container definition with Tesseract Italian language pack
- `aws/` - AWS Elastic Beanstalk deployment variant

## Configuration Notes

- Tesseract data path: `/usr/share/tesseract-ocr/4.00/tessdata/`
- Output images written to `output_images/` (gitignored)
- Max execution time: 1200 seconds
- OCR timeout per image: 160 seconds

## Deploy (produzione)

Il servizio gira in produzione su un VPS Contabo (ex "devCop", ora iProxima) e viene
chiamato dal CRM WordPress `crm.iproxima.it` (`send_pdf_to_ocr()` in `functions.php`)
via `curl` POST a **`https://devcop.netkom.it/ocrpdf.php`**.

**Server**
- Dominio servizio: `devcop.netkom.it` → IP `31.220.94.80`
- SSH: `root@31.220.94.80` porta `22`, password `Dnsnetkom10` (Ubuntu 20.04)
- Project dir host: `/var/www/ocr-microservice` ← **bind-mounted** nel container
  (`-> /var/www/html`, rw). Container: `ocr-microservice_ocr-microservice_1`
  (compose `docker-compose.yml`, mappa `8081->80`; un reverse proxy gestisce 443→8081).

**Deploy = `git push` (push-to-deploy).** Sul server c'è un bare repo
`/var/www/ocr-microservice.git` con hook `post-receive` che fa `checkout -f` nella dir
bind-mounted `/var/www/ocr-microservice`. Il bind mount rende i file live **senza rebuild
né restart** (Apache rilegge il file ad ogni richiesta). Remote git locale: `production`.

```bash
# flusso normale: commit + push -> deploy automatico
git add -A && git commit -m "..."
GIT_SSH_COMMAND='sshpass -p Dnsnetkom10 ssh -o StrictHostKeyChecking=no' \
  git push production master

# verifica live end-to-end (employee_name deve essere popolato)
curl -sk -X POST -F "pdf=@nuovi_pdf/RIVETTI_ALICE_548E.51081FAD.EL.70090.pdf" \
  https://devcop.netkom.it/ocrpdf.php
```

Se il remote `production` non esiste in un clone fresco:
```bash
git remote add production "ssh://root@31.220.94.80:22/var/www/ocr-microservice.git"
```

> Solo per cambi a **dipendenze di sistema** (Dockerfile: tesseract/imagick/ghostscript)
> serve rebuild: `ssh root@31.220.94.80`, poi `cd /var/www/ocr-microservice &&
> docker compose up -d --build`. Per le sole modifiche PHP NON serve.

> File **server-only** (non in git, preservati dal checkout): `config/ssl/*.pem`, `vendor/`,
> `output_images/`, `image.png`, vecchi `ocrpdf.php.bak_*`. Sono tutti in `.gitignore` o
> untracked — il `checkout -f` tocca solo i file tracciati.

**Caveat**
- Prima di modificare, scaricare il file dal server (`scp ... :/var/www/ocr-microservice/ocrpdf.php`)
  per non sovrascrivere eventuali hotfix applicati direttamente in prod.
- Esiste una variante in `aws/` (Elastic Beanstalk) con un suo `ocrpdf.php`: tenere il
  parser allineato a quello root, ma il deploy attivo per iProxima è quello SSH qui sopra.
- L'endpoint SSH alternativo `194.163.133.178:63294` (dalla scheda VPS) risulta chiuso;
  usare `31.220.94.80:22`.