shop/CLAUDE.md

Shopsystem — Projektrichtlinien

Projekt

Custom E-Commerce Shopsystem (B2C + B2B), weltweit einsetzbar, als verkaufbares Produkt geplant.

Architektur

• App-basiertes System: Jede Funktion ist eine App mit Manifest (Abhängigkeiten, Konflikte, Pflicht/Optional)
• Core: Minimaler Kern (Auth, API-Router, App-Loader, Event-Bus, DI-Container)
• Kommunikation zwischen Apps: Events (lose Kopplung) und Dependency Injection (keine direkten Imports)
• Dritt-Entwickler können eigene Apps bauen (Marketplace-Konzept)

Tech-Stack

• Backend: Python + FastAPI — Tooling: uv, ruff, pytest
• Datenbank: PostgreSQL (Write-Store) + Redis (Read-Store)
• Frontend: Vue 3 + Vite + TypeScript + Pinia + Vue Router — Tooling: pnpm, eslint, prettier, vitest. Nur Web, responsives Design. Zwei getrennte Vue-Apps mit separatem Build: shop und admin.
• Auth: JWT (Access + Refresh), argon2 für Passwort-Hashing
• KI: Ollama (lokal) via RAG — Standard-Modelle llama3.1 (Chat) + nomic-embed-text (Embeddings), per Abstraktion austauschbar
• Suche: austauschbar per Such-Abstraktion (Standard Meilisearch)
• DB-Migrationen: Alembic (SQLAlchemy)
• i18n: DE + EN initial
• Dev-Infrastruktur: docker-compose mit Postgres, Redis, Meilisearch, Ollama
• Jede App bringt Manifest (manifest.yaml), Migrationen, API-Endpunkte, Frontend-Komponenten, Events und Übersetzungen mit

Betrieb

• Single-Shop pro Instanz (kein Multi-Tenant). Mehrere Shops → mehrere Deployments.

Repo-Struktur

/backend        FastAPI-Core + App-Loader
/frontend/shop  Vue-App Kundensicht
/frontend/admin Vue-App Admin
/apps           Core-Apps und optionale Apps als Python-Packages

KI-Integration

• Shop-Seite: KI-Helfer für natürlichsprachliche Produktsuche (RAG über Produkte/Kategorien).
• Admin-Seite: KI-Chatbox auf der Startseite. Befehle und JSON-Bulk-Input werden als Vorschlags-Cards dargestellt. Fehlende Felder sind in der Card editierbar. Ausführung erst nach Bestätigung durch den Admin — KI führt nie direkt aus.

Datenfluss

• PostgreSQL ist die Quelle der Wahrheit (alle Schreiboperationen)
• Redis ist die Lese-Schicht (Frontend liest NUR aus Redis)
• Sync: Sofort-Aktualisierung bei Änderungen + Scheduler als Sicherheitsnetz
• Frontend sieht nie die DB-Komplexität, nur schnelle Redis-Reads

Umgebungen

• APP_ENV=dev|staging|production steuert Verhalten
• Dev: Seed-Daten, Mock-Services, Hot-Reload, Debug-Logging
• Staging: Stripe Testmodus, Catch-All E-Mails
• Production: Echte Zahlungen, Caching an

Implementierter Stand (Prototyp)

• Alle 8 Module aus module.md sind lauffähig: Core, Auth, Catalog, Cart, Checkout, Orders+Mail, AI-Core (RAG/pgvector), AI-Shop-Suche (hybrid), AI-Admin-Chat (Plan/Execute mit Vorschlags-Cards).
• Keine Tests (Prototyp).
• Dummy-Payment, Mailhog für Dev-Mails, Bild-Upload lokal in ./uploads.
• Starten per make install && make infra && make migrate && make seed && make reindex && make dev. Details in QUICKSTART.md.

Analyse-Dokument

• shopsystem-analyse.tex — Vollständige Analyse (34 Seiten), nicht mehr anpassen.

Arbeitsweise

• Antworten kompakt halten.
• KI-gestützter Workflow: Prototyp → Refactoring → Refactoring.