skrift-programme/CLAUDE.md

CLAUDE.md

Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.

Tradeoff: These guidelines bias toward caution over speed. For trivial tasks, use judgment.

1. Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

Before implementing:

• State your assumptions explicitly. If uncertain, ask.
• If multiple interpretations exist, present them - don't pick silently.
• If a simpler approach exists, say so. Push back when warranted.
• If something is unclear, stop. Name what's confusing. Ask.

2. Simplicity First

Minimum code that solves the problem. Nothing speculative.

• No features beyond what was asked.
• No abstractions for single-use code.
• No "flexibility" or "configurability" that wasn't requested.
• No error handling for impossible scenarios.
• If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

3. Surgical Changes

Touch only what you must. Clean up only your own mess.

When editing existing code:

• Don't "improve" adjacent code, comments, or formatting.
• Don't refactor things that aren't broken.
• Match existing style, even if you'd do it differently.
• If you notice unrelated dead code, mention it - don't delete it.

When your changes create orphans:

• Remove imports/variables/functions that YOUR changes made unused.
• Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

4. Goal-Driven Execution

Define success criteria. Loop until verified.

Transform tasks into verifiable goals:

• "Add validation" → "Write tests for invalid inputs, then make them pass"
• "Fix the bug" → "Write a test that reproduces it, then make it pass"
• "Refactor X" → "Ensure tests pass before and after"

For multi-step tasks, state a brief plan:

1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

---

These guidelines are working if: fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

---

Projekt: Skrift

Handschriftliche Dokumente als Service. Kunden konfigurieren Briefe/Postkarten/Umschläge im Web; ein Backend rendert sie als SVG in echter Handschrift; ein Schreibroboter (Pen-Plotter) schreibt sie physisch. Alle Software in diesem Ordner gehört zu Skrift. Sprache im Projekt: Deutsch.

Ebenen und Komponenten

Drei Ebenen, getrennt gehalten für einfachere Wartung:

Docker/ — serverseitig, hinter Nginx Proxy Manager (NPM)

• skrift-backend (Node/Express, :4000, Domain backend.skrift.de) — Main-Backend. Generiert Brief-/Umschlag-SVGs: Text → Scriptalizer-API (natürliche Handschrift-Variation) → eigene Font-Engine (src/lib/svg-font-engine.js). Preview-Cache + finaler Order-Output. Platzhalter-System ([[Name]] → CSV). Kein PayPal im Backend — die PayPal-Zahlung läuft rein client-seitig im configurator über das PayPal-JS-SDK (actions.order.create/capture direkt gegen PayPal). SVG-Fonts unter fonts/ (tilda=PremiumUltra79, alva=PremiumUltra23, ellie=PremiumUltra39). Struktur: src/api/{routes,controllers,middleware}, src/services (scriptalizer, placeholder), src/lib (svg-generator, svg-font-engine, page-layout).
• signature-service (FastAPI, :8000, Domain api-sign.skrift.de) — zustandslos. Findet unsichtbare Marker-Token (§§SIG1§§) in einem gedruckten PDF, platziert die zugeordnete Unterschrift-SVG relativ dazu und liefert eine A4-SVG pro Seite (/render, ZIP) bzw. ein Vorschau-PDF (/preview). Keine Plotter-Kalibrierung/Offsets im Service — Mechanik wird in der Druckersoftware behandelt. Geometrie-Logik in core.py.

Webseite/ — WordPress-Plugins (öffentlich)

• skrift-configurator — öffentlicher Haupt-Konfigurator, Shortcode [skrift_konfigurator]. Spricht das Backend nur über einen serverseitigen PHP-Proxy an (includes/api-proxy.php, REST-Namespace skrift/v1/proxy/*), damit der API-Token nie ins Frontend gelangt. Liefert außerdem das Basis-CSS (--sk-*-Variablen, .sk-*-Klassen) sowie Admin-Settings (Backend-Verbindung, Preise, Produkte, Gutscheine).
• skrift-job-manager — Kunden-Auftragsportal, Shortcode [skrift_kundenauftrag]. Hängt hart am configurator (nutzt dessen CSS + Backend-Verbindungseinstellungen). Eigener Namespace skrift/v1/job/*; ruft Backend u.a. /api/order/register, /api/order/files. Signaturen: Kunde zeichnet auf einem <canvas> → Striche werden client-seitig via pathsToSvg() als Polyline-SVG (M/L-Pfade) erzeugt und als Platzhalter [[signatur1..3]] mitgeschickt.

Produktion/ — lokale Windows-Software

• skrift-produktion — Main-Produktion. FastAPI auf 127.0.0.1:8765 (öffnet Browser automatisch). Worker: FTPPollWorker pollt SFTP nach neuen Aufträgen, MachinePollWorker überwacht die Plotter-Maschine, QueueWorker arbeitet die Queue ab. Sendet SVGs an die Maschinen-API (Default http://192.168.2.32:90) mit Format-Templates (Maße/Position/Rotation) aus config.json. Signaturen-Tab ruft signature-service /render über den eigenen Endpunkt POST /api/signature/print und schickt die A4-Signaturen an den Plotter (Service-URL in config.json unter app.signature_backend_url, Default http://localhost:8000).
• AutoRecover — kleines win32-Skript (auto_recover.py). Erkennt das Java-„Error"-Fenster des Plotters (kein Papier) und klickt max. 3× „Recover".

Datenfluss (End-to-End)

1. Kunde konfiguriert im configurator (oder job-manager) → WordPress-Proxy → skrift-backend generiert SVGs.
2. skrift-backend schreibt den fertigen Order-Ordner nach /var/skrift-output (docker-compose-Volume). Dieses Verzeichnis ist gleichzeitig das SFTP-Ziel, auf das per SFTP zugegriffen wird — kein Zwischenschritt.
3. skrift-produktion holt den Auftrag per SFTP und schickt die SVGs formatgerecht an den Plotter.
4. Bei Unterschriften: gedrucktes PDF mit Marker-Token → signature-service platziert Signaturen → produktion sendet die A4-Signatur-SVGs an den Plotter.
5. AutoRecover hält den Druck bei Papierende am Laufen.

Befehle

skrift-backend (Docker/skrift-backend)

npm install
npm start            # node src/server.js → :4000
npm run dev          # nodemon
docker-compose up -d # Prod (Volume: /var/skrift-output, fonts/ read-only)

signature-service (Docker/signature-service)

pip install -r requirements.txt
uvicorn app:app --host 0.0.0.0 --port 8000
pytest                    # ein Test: pytest tests/test_x.py::test_name
docker compose up -d --build

signature-to-svg (Docker/signature-to-svg) — uvicorn app.main:app --host 0.0.0.0 --port 8765 bzw. docker-compose up -d.

skrift-produktion (Produktion/skrift-produktion) — Einrichten.bat (venv + deps einmalig), dann Starten.bat (bzw. Starten (Debug).bat). Läuft auf 127.0.0.1:8765.

AutoRecover — python auto_recover.py; EXE-Build via build_exe.bat.

WordPress-Plugins haben keinen Build-Schritt (reines PHP/JS).

Wichtige Hinweise / Fallstricke

• NPM-Netz: signature-service hängt im externen Docker-Netz nginx-proxy-manager_default und veröffentlicht keinen Host-Port — NPM proxyt intern per container_name.
• SCRIPTALIZER_ERR_FREQUENCY=0 setzen: sonst erzeugt Scriptalizer absichtlich durchgestrichene „Fehler"-Wörter.
• Secrets liegen im Repo: Docker/skrift-backend/.env enthält reale Keys — nicht in Ausgaben/Commits streuen.
• Der job-manager ist ohne den configurator nicht lauffähig (CSS + Backend-Settings kommen von dort).
• FRONTEND_BACKEND_ZUSAMMENFASSUNG.md stammt aus der Zeit vor dieser Ordnerstruktur (spricht von „WordPress Plugin" / „Docker Backend") und ist teils veraltet — diese CLAUDE.md hat Vorrang.