# Architektur v2

## Kernidee

OpenRefine spricht nur mit einem eigenen Reconciliation-Service. Dieser Service agiert als Orchestrator und verteilt die Suche an Provider.

```text
OpenRefine
  ↓
public/reconcile.php
  ↓
TenantContext über api_key
  ↓
Manifest / Reconciliation / Preview
  ↓
Orchestrator
  ├── xTree Provider
  ├── Künsterdatei
  ├── Wikidata Provider
  ├── GBIF Provider
  └── GND Provider
  ↓
Ranking
  ↓
OpenRefine Mapping durch Mensch
```

## Mandantenfähigkeit

Der API-Key erzeugt einen TenantContext. Dieser entscheidet:

- welche Vokabulare sichtbar sind
- welche Provider erlaubt sind
- welche Subvokabulare / Teilbäume verwendet werden dürfen
- welche Features aktiv sind, z. B. externe Fallbacks, LLM, spaCy

## SubVocabulary / Teilbaum

OpenRefine hat kein Standardfeld `subVocabulary`. Deshalb gibt es zwei Wege:

1. Hierarchieknoten werden als `type` im Manifest angeboten.
2. Der Service interpretiert einen ausgewählten Hierarchieknoten intern als SubVocabulary.

Langfristig sollte ein eigener `suggest/type`-Endpoint ergänzt werden.

## Fallback-Ketten

Beispiel oWoT:

```text
xTree Objekttyp
  ↓ falls keine guten Treffer
AAT
  ↓ falls keine guten Treffer
GND 
  ↓ falls keine guten Treffer
WD 
```

Konfiguriert in `config/providers.php`.

## Nächste technische Schritte

1. Bestehende xTree-SQL-Suche aus v1 in `XtreeProvider::search()` portieren.
2. SubVocabulary-Auswertung über xTree-Hierarchietabelle ergänzen.
3. OpenRefine-Properties aus Kontextspalten in Ranking einbeziehen.
4. Preview aus v1 in `XtreeProvider::preview()` übernehmen.
5. Externe Provider mit HTTP-Client und Caching ergänzen.