CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Projekt

kbcrm ist eine Flask-basierte Webanwendung zur Unterstützung der Kundenakquise. Sie verwaltet Kunden, Kontakte, Projekte, Kontaktadressen (Anrufziele) und Gesprächsnotizen. Authentifizierung wird vollständig an Zitadel (OIDC-IdP) delegiert; Benutzer- und Rollendaten werden lokal in SQLite gehalten.

Befehle

# Lokale Entwicklung
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env      # Zitadel-Credentials eintragen
flask db-init             # Datenbankschema anlegen
flask seed-db             # Testdaten mit Zitadel-User-IDs einspielen
flask run                 # http://localhost:5000

# Sphinx-Dokumentation
sphinx-apidoc -o docs/source/ app/
cd docs/ && make html     # Ergebnis: docs/_build/html/index.html

Architektur

app/
├── __init__.py    # App-Factory, Flask-Initialisierung, CLI-Kommandos (db-init, seed-db)
├── config.py      # Konfiguration aus .env (12-Factor)
├── database.py    # SQLAlchemy-Instanz und Session-Setup
├── models.py      # Alle ORM-Modelle (siehe Datenmodell unten)
├── auth.py        # Zitadel-OIDC-Flow via Authlib; Rollen aus Token-Claims
├── routes.py      # Flask-Blueprints und View-Funktionen
├── templates/     # Jinja2-Templates
└── static/        # CSS, JS, Assets
data/              # SQLite-Datenbankdatei (nicht im Docker-Image, persistiert als Volume)
wsgi.py            # Gunicorn-Einstiegspunkt

Datenmodell

Tabelle	Zweck
`Benutzer`	Anwendungsnutzer; Primärschlüssel ist der Zitadel-`sub`
`Kunden`	Kundenstamm (Firmen oder Privatpersonen)
`Kontakte`	Ansprechpartner bei einem Kunden (FK → Kunden)
`Projekte`	Akquise-Projekte, einem Kunden zugeordnet
`Benutzer_Projekt`	n:m-Zuordnung Benutzer ↔ Projekte (Zugriffskontrolle)
`Kontaktadressen`	Anrufziele innerhalb eines Projekts; importierbar via CSV/Excel (FK → Projekte)
`Gesprächsnotizen`	Anrufdokumentation mit Metadaten, Freitext und Tags (FK → Kontaktadressen)
`Tags`	Benutzerdefinierte Kategorien für Gesprächsnotizen
`Gesprächsnotizen_Tags`	n:m-Verknüpfung Gesprächsnotizen ↔ Tags

Authentifizierung & Autorisierung

Authlib übernimmt den OIDC Authorization-Code-Flow gegen https://id.vmlx.de.
Die drei Rollen (Admin, Mitarbeiter, Kunde) werden in Zitadel definiert und landen als Claims im Token.
auth.py liest den sub-Wert und die Rollen aus dem Token; beim ersten Login wird der Benutzer lokal angelegt.
Projektzugriff: Normale Benutzer sehen nur ihre zugewiesenen Projekte; Admins haben vollen Zugriff.
Zitadel-Einrichtung (Projekt, Rollen, Testnutzer, Client-Credentials) ist in ai-context/AI-auth-vorgaben.md Schritt für Schritt beschrieben.

Pflicht-Dateiheader

Jede neue Quelldatei beginnt mit einem standardisierten Header.

Python (.py) — wird von Sphinx ausgewertet:

"""
<Einzeiliger Modultitel>

<Optionale längere Beschreibung.>

:author:  Vorname Nachname <email@beispiel.de>
:date:    YYYY-MM-DD
:version: 1.0
"""

Jinja2/HTML (.html):

{#
  Datei:   templates/beispiel.html
  Autor:   Vorname Nachname <email@beispiel.de>
  Datum:   YYYY-MM-DD
  Zweck:   Kurze Beschreibung der Seite und erwarteter Jinja2-Variablen
#}

Vorlagen liegen unter _templates/_template.py und _templates/_template.html.

Konfiguration

Alle Laufzeitvariablen kommen aus .env (nie in Git einchecken):

ZITADEL_CLIENT_ID=...
ZITADEL_CLIENT_SECRET=...
ZITADEL_DISCOVERY_URL=https://id.vmlx.de/.well-known/openid-configuration
SECRET_KEY=...

Weitere Vorgabedokumente

Datei	Inhalt
`ai-context/AI-operative_Vorgaben.md`	Tech-Stack, Verzeichnisstruktur, Docker-Setup
`ai-context/strukturelle-vorgaben.md`	Dateiheader-Konventionen, Sphinx-Setup
`ai-context/AI-auth-vorgaben.md`	Zitadel-Einrichtung Schritt für Schritt
`ai-context/grob-kozept-vom-interview.md`	Vollständige fachliche Anforderungen und UX-Workflows

4.1 KiB Raw Blame History