BuyingAgent/docs/buying-agent-architecture-addendum-v1.md

# Buying Agent – Architecture Addendum v1

**Status:** ergänzende Architekturvorgabe  
**Gültig zusammen mit:** `buying-agent-v0.1-spec-v1.1.md`  
**Stand:** 2026-10-03

## 1. Zweck

Dieses Addendum ergänzt die bestehende Spezifikation um übergreifende Architekturentscheidungen für das spätere Zielsystem.

Es ersetzt **nicht** die fachliche Spezifikation `buying-agent-v0.1-spec-v1.1.md`.

Bei Konflikten zwischen beiden Dokumenten hat dieses Addendum für die hier behandelten Architekturthemen Vorrang.

Ziel ist, den aktuellen v0.1-Slice schlank zu halten, ohne spätere Erweiterungen auf Frontend, mehrere Kaufprojekte und mehrere Benutzer unnötig zu erschweren.

---

## 2. Zielstruktur des Repositories

Das Projekt wird als Monorepo strukturiert:

```text
buying-agent/
├── README.md
├── docker-compose.yml
├── .env.example
├── .gitignore
├── docs/
│   ├── buying-agent-v0.1-spec-v1.1.md
│   └── buying-agent-architecture-addendum-v1.md
├── backend/
│   ├── Dockerfile
│   ├── pyproject.toml
│   ├── uv.lock
│   ├── alembic.ini
│   ├── migrations/
│   ├── app/
│   ├── rules/
│   ├── profiles/
│   ├── fixtures/
│   ├── scripts/
│   └── tests/
└── frontend/
    └── README.md
```

### Regeln

- `docker-compose.yml` bleibt im Repository-Root.
- Das Backend ist der aktuell implementierte v0.1-Scope.
- `frontend/` wird in v0.1 **nicht implementiert**.
- `frontend/README.md` dokumentiert lediglich, dass dort später die Benutzeroberfläche entsteht.
- Keine zusätzliche `infra/`-Struktur in v0.1, solange sie nicht konkret benötigt wird.

---

## 3. Backend-/Frontend-Grenze

Das Backend bleibt das **System of Record** und besitzt:

- Domain-Modell
- Constraints
- Scoring
- Evaluation
- Persistenz
- Preis- und Produktlogik
- zukünftige Kaufentscheidungslogik

Das spätere Frontend konsumiert ausschließlich die versionierte Backend-API, primär unter:

```text
/api/v1
```

Das Frontend enthält keine fachlich verbindliche Business-Logik.

---

## 4. Zukünftige Multi-User-Architektur

Das Zielsystem soll später von Familie und gegebenenfalls engen Freunden genutzt werden können.

Die Architektur darf daher nicht von einem impliziten Single-User-Modell ausgehen.

Zielmodell:

```text
User
  ↕
WorkspaceMember
  ↕
Workspace
  ↓
BuyingProject
  ↓
ProjectCandidate
  ↓
ProductVariant
```

Ein Benutzer kann Mitglied in mehreren Workspaces sein.

Beispiele:

```text
Lars
├── Privat
├── Familie
└── Freunde
```

### Noch nicht Bestandteil von v0.1

Nicht implementieren:

- Login
- Authentifizierung
- Passwortverwaltung
- Einladungen
- RBAC
- komplexe ACLs
- Sharing-UI
- Workspace-Administration

Die aktuelle Architektur darf deren spätere Einführung aber nicht unnötig erschweren.

---

## 5. Globale versus Workspace-bezogene Daten

### Global wiederverwendbare Daten

Diese Entitäten bleiben systemweit gemeinsam nutzbar:

- Product
- ProductVariant
- Offer
- PriceObservation
- AttributeDefinition
- Source

Sie erhalten **keine** `user_id` oder `workspace_id`.

Ein Produkt oder Angebot darf nicht pro Benutzer oder Workspace dupliziert werden.

### Workspace-bezogene Daten

Spätere benutzerbezogene Beschaffungskontexte gehören zu einem Workspace:

- BuyingProject
- ProjectCandidate
- projektspezifische Profil-/Anforderungsauswahl
- Notification Preferences
- Beschaffungsdeadline
- Zielpreis
- Kaufentscheidungsstatus
- gegebenenfalls spätere Warenkorb-/Beschaffungsinformationen

Diese Objekte werden erst in späteren Slices implementiert.

---

## 6. BuyingProject als zukünftiges Kernobjekt

Ein `BuyingProject` repräsentiert ein konkretes Beschaffungsvorhaben.

Beispiele:

- Mobiler Entwicklungsrechner
- Lokaler LLM-Server
- Fernseher
- Kamera

Ein Workspace kann mehrere BuyingProjects parallel besitzen.

Ein BuyingProject kann mehrere ProjectCandidates beobachten.

```text
BuyingProject
├── Candidate A → ProductVariant
├── Candidate B → ProductVariant
└── Candidate C → ProductVariant
```

### Wichtig für v0.1

`BuyingProject` und `ProjectCandidate` müssen in v0.1 noch nicht implementiert werden.

Die aktuelle Implementierung darf jedoch nicht annehmen:

- es existiert genau ein aktives Profil,
- es existiert genau ein Kaufvorhaben,
- es gibt globale Singleton-Konfiguration für einen aktuellen Kauf,
- alle Daten gehören automatisch demselben Benutzer,
- es existiert nur eine gleichzeitig relevante Evaluation.

Mehrere unabhängige Profile und Evaluationen müssen bereits parallel koexistieren können.

---

## 7. Rolle von n8n

n8n bleibt eine externe Orchestrierungsschicht.

Spätere mögliche Aufgaben:

- Scheduler
- Preisabfragen
- Datenimport
- Benachrichtigungen
- externe Integrationen
- volatile oder häufig veränderte Workflows

Kern-Business-Logik bleibt im Programmcode, insbesondere wenn sie:

- deterministisch sein soll,
- versioniert werden muss,
- getestet werden muss,
- fachliche Entscheidungen reproduzierbar machen soll.

n8n darf für veränderliche Prozesslogik eingesetzt werden, aber nicht zur Voraussetzung für das Funktionieren der Buying Engine werden.

---

## 8. Zukünftiges Frontend

Das Zielsystem soll später eine einfach bedienbare Oberfläche erhalten.

Die Standardoberfläche soll auch für nichttechnische Familienmitglieder verständlich bleiben.

Die Engine darf gleichzeitig deutlich leistungsfähiger sein als die Oberfläche.

Voraussichtliche spätere Kernbereiche:

- Übersicht laufender Kaufprojekte
- Kandidaten je Projekt
- aktueller bester Deal
- Preisverlauf
- Produkt-Fit
- Offer-Fit
- DealScore
- verständliche Gründe
- Beobachtungsstatus
- konkrete Kaufempfehlung
- ggf. spätere Benachrichtigungs- und Warenkorbfunktionen

Keine dieser UI-Funktionen ist Bestandteil von v0.1.

---

## 9. Kaufentscheidungslogik

Langfristig soll das System nicht nur Scores liefern, sondern auch konfigurierbare Kaufentscheidungen unterstützen.

Beispiele möglicher Einflussfaktoren:

- Zielpreis
- Maximalpreis
- spätestes Beschaffungsdatum
- aktueller Preis
- Preisentwicklung der letzten Tage/Wochen/Monate
- Abstand zu historischem Median
- Produkt-Fit
- Offer-Fit
- Verfügbarkeit
- Lieferzeit
- Händlerqualität
- alternative Kandidaten
- Beschaffungsdringlichkeit

Die Kaufentscheidung soll nachvollziehbar und möglichst deterministisch bleiben.

LLMs dürfen später Erklärungen, Normalisierung oder qualitative Interpretation unterstützen, sollen aber keine nicht nachvollziehbare Blackbox-Entscheidung erzwingen.

---

## 10. Datenquellen

Das Zielsystem muss mehrere Produkt- und Preisquellen unterstützen können.

Mögliche spätere Quellen:

- Amazon / Keepa
- Preisvergleichsportale
- Hersteller
- Händler
- weitere APIs

v0.1 implementiert weiterhin **keine reale externe Quelle**.

Die bestehende Source-Adapter-Grenze bleibt die vorgesehene Erweiterungsstelle.

---

## 11. Scope-Grenze für die laufende v0.1-Implementierung

Dieses Addendum darf nicht als Anlass dienen, v0.1 unnötig zu vergrößern.

Insbesondere **nicht jetzt implementieren**:

- echtes Frontend
- Authentifizierung
- User Management
- Workspace Management
- RBAC
- Einladungen
- BuyingProject
- ProjectCandidate
- Notifications
- n8n
- externe Preisquellen
- automatische Produktsuche
- Warenkorbmanagement

Ziel ist Architekturkompatibilität, nicht vorgezogene Feature-Entwicklung.

---

## 12. Arbeitsauftrag für die laufende Implementierung

Der Coding-Agent soll vor Fortsetzung des laufenden Builds einen kurzen Architecture-Alignment-Check durchführen.

### Prüfen

1. Entspricht die Repository-Struktur bereits der Monorepo-Struktur mit:
   - `backend/`
   - `frontend/`
   - `docs/`
   - Root-`docker-compose.yml`

2. Gibt es Annahmen über:
   - genau einen Benutzer,
   - genau ein aktives Profil,
   - genau ein Kaufprojekt,
   - globale Singleton-Zustände?

3. Sind Product, ProductVariant, Offer und PriceObservation weiterhin global und unabhängig von späteren Workspaces modelliert?

4. Ist das Backend klar von zukünftiger Frontend- und n8n-Logik getrennt?

### Änderungen

Nur notwendige strukturelle Anpassungen durchführen.

Keine vorgezogene Multi-User- oder Frontend-Funktionalität implementieren.

Die fachlichen Anforderungen aus `buying-agent-v0.1-spec-v1.1.md` bleiben vollständig gültig.

### Abschlussbericht

Dokumentieren:

- geänderte oder verschobene Dateien,
- notwendige Architekturänderungen,
- Änderungen an Datenbank/Migrationen,
- ausgeführte Tests,
- Testergebnisse,
- verbleibende Risiken für spätere Workspace-/BuyingProject-Erweiterung.

---

## 13. Vorrang und Weiterentwicklung

Dieses Dokument ist ein Architektur-Addendum zur v0.1-Spezifikation.

Nach Abschluss von v0.1 sollen die Erkenntnisse aus:

- `buying-agent-v0.1-spec-v1.1.md`
- diesem Addendum
- der realen Implementierung

in eine konsolidierte Folgespezifikation für den nächsten Slice übernommen werden.

Die Kernregel lautet:

> Nicht vorzeitig bauen, aber bekannte Zielanforderungen nicht architektonisch verbauen.