From 09832c2cf4805ed096f70ed25568a4f53e16ccce Mon Sep 17 00:00:00 2001
From: Claude <claude@webklar.local>
Date: Sun, 4 Oct 2026 10:04:05 +0000
Subject: [PATCH] =?UTF-8?q?docs:=20README=20f=C3=BCr=20AirCard-IOS?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 README.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 68 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index a7c7615..3a85366 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,76 @@
 # AirCard-IOS
 
-Inoffizielles Hobbyprojekt: AirCard-IOS ist ein Editor, mit dem man eigene Kartenmotive für https://aircard-ios.org gestalten kann. Keine Verbindung zu Apple, Visa, Mastercard, UnionPay, American Express, JCB oder Discover.
+Inoffizielles Hobbyprojekt, mit dem man eigene Kartenmotive für Apple Wallet unter https://aircard-ios.org gestalten kann. Bilder hochladen, Vorlage und Netzwerk-Logo wählen, herunterladen – oder mit Konto speichern. Keine Verbindung zu Apple, Visa, Mastercard, UnionPay, American Express, JCB oder Discover.
 
-Die Website liegt in `web/` (statisches Vite + TypeScript, ohne UI-Framework). Die Design-Spec steht in `docs/superpowers/specs/2026-10-04-aircard-website-design.md`.
+## Aufbau
 
-## Entwicklung
+**`web/`** – Vite + TypeScript ohne Framework. Frontend-Module in `src/`:
+  - `card/` – Geometrie, Zuschnitt, Canvas-Rendering (keine DOM-Abhängigkeiten, einzeln testbar)
+  - `editor/` – UI (Vorlagen, Vorschau, Download, Speichern)
+  - `account/` – Appwrite-Client, Auth, Kartenverwaltung
+  - `pages/` – Routen (`/`, `/karten`, `/passwort-neu` via History-API)
+
+**`deploy/`** – Webhook-Router (Port 8087), Build-Skript (`deploy.sh`), nginx-Config, Traefik-Route für Appwrite.
+
+**`docs/`** – Spec, Plan, Appwrite-Konfiguration.
+
+## Lokal entwickeln
 
 ```sh
 cd web
-npm install
-npm run dev      # Entwicklungsserver
-npm test         # Tests (Vitest)
-npm run build    # Typprüfung + Produktions-Build nach web/dist
+npm ci
+npm run dev          # Entwicklungsserver http://localhost:5173
 ```
+
+Login und Speichern brauchen die Appwrite-Route. Der lokale Host wird nur dann erkannt, wenn die Web-Plattform `localhost` in der Appwrite-Console eingetragen ist (unter Projekt → Overview → Integrations → Platforms). Die Umgebungsvariablen `VITE_APPWRITE_ENDPOINT` und `VITE_APPWRITE_PROJECT_ID` müssen für die lokale Entwicklung verfügbar sein (Standard: `https://appwrite.webklar.com/v1` und `6ac2130a00289343d6d5`).
+
+## Tests
+
+```sh
+cd web && npx vitest run     # Unit-Tests (card/*, editor/*, account/*)
+npx tsc --noEmit             # TypeScript-Prüfung
+node --test deploy/webhook-server.test.js      # Webhook und Build-Logik
+node --test web/scripts/appwrite-setup.test.mjs  # Appwrite-Schema
+```
+
+## Deploy
+
+**Automatisch:** Push auf `main` → Gitea-Webhook → Container `webklar-aircard-build` führt `npm ci` und `vite build` aus → Ergebnis nach `out/` → nginx `webklar-aircard` liefert.
+
+**Manuell:**
+```sh
+docker exec webklar-aircard-build sh /deploy.sh
+```
+
+Starten nur mit:
+```sh
+docker compose up -d aircard-build aircard
+```
+
+Die Appwrite-API wird über `/home/webklar/apps/traefik/dynamic/aircard.yml` geroutet: Requests auf `aircard-ios.org/v1` mit Header `X-Appwrite-Project: aircard` gehen an den Appwrite-Container.
+
+## Appwrite
+
+Projekt `aircard` auf `appwrite.webklar.com`:
+- Projekt-ID (öffentlich): `6ac2130a00289343d6d5`
+- Datenbank: `aircard`, Tabelle: `cards`, Bucket: `card-images`
+- Auth: E-Mail + Passwort, Sitzungsdauer 30 Tage, max. 5 pro Nutzer, Nutzerlimit 2000
+- Web-Plattformen: `aircard-ios.org`, `localhost`
+
+**Schema prüfen:**
+```sh
+node --env-file=/home/webklar/apps/.env web/scripts/appwrite-setup.mjs --check
+```
+
+**Schema erstmalig anlegen:**
+```sh
+node --env-file=/home/webklar/apps/.env web/scripts/appwrite-setup.mjs
+```
+
+Umgebungsvariablen (in `/home/webklar/apps/.env`):
+- `AIRCARD_APPWRITE_PROJECT_ID` – Projekt-ID (idempotent im Skript lesbar)
+- `AIRCARD_APPWRITE_API_KEY` – API-Key `aircard-provision` (nur für Setup)
+
+## Hinweis
+
+Inoffizielles Hobbyprojekt. Alle Marken gehören ihren Inhabern.