kbcrm/mistral-context.md

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

Das Projekt besteht aus 2 Teilen:

• Die GUI, die im Browser läuft und mit Typescript und mithril.js erstellt wird
• Das Backend, welches im wesentlichen mit Python, flask und sqlalchemy entwickelt wird Daraus ergibt sich die folgende Struktur:

.
├── ai-context/                       # Anweisungen und Information für Mistral AI
├── App_Server/                       # Enthält Alles, was auf den Server (Backend) gehört
│   ├── data/                         # enthält die SQLite-Datenbanken			
│   ├── Dockerfile
│   ├── root/                         # Enthält alle Python-Programme
│   │   ├── approot.py	
│   │   ├── auth                      # Enthält Programme zu Benutzerverwaltung		 
│   │   │   ├── model/		            # Enthält die Datenmodelle der Benutzerverwaltung
│   │   │   └── routes.py
│   │   ├── config.ini
│   │   ├── db.py
│   │   ├── requirements.txt
│   │   ├── routes/                   # Enthält die Route-Definitionen für Flask
│   │   ├── runserver.py
│   │   ├── settings.py
│   │   └── templates/                # enthält die Vorlagen für Jinja2
│   └── scripts/                      # enthält Scripts, die im Dockjer-Container ausgeführt werden
├── Client/                           # Enthält alles, was für die Browser-basierte GUI erforderlich ist
│   ├── Components/	                  # enthält die mit mithril.js entwickelten GUI-Komponenten
│   │   ├── auth/		                  # enthält die GUI-Komponenten für die Benutzer-Verwaltung
│   │   │   └── models/               # enthält die Datenmodelle für die Benutzerverwaltung
│   │   └── widgets                   # enthält einzelne GUI-Elemente wie Eingabefelder u.ä., 
│   │                                 # die dann in den Komponenten verwendet werden
│   ├── index.ts
│   ├── inireader.mjs
│   ├── node_modules/
├── docker-compose.base.yaml
├── docker-compose.dev.yaml
├── docker-compose.prod.yaml
├── docker-compose.save.yaml
├── Dokumentationen/                   # enthält Dokumente, die für die Entwicklung wichtig sind
├── mistral-context.md
├── NGINX_Server/                      # enthält die Konfiguration für den im Docker-Container laufenden NGINX-Server
│   ├── certs/			                   # enthält die Zertifikatsdateien für die SSL-Verschlüsselung
│   ├── configtemplates
│   ├── Dockerfile
│   └── html/
│       └── static/                    # enthält die statischen Elemente der GUI, wie css-Dateien und Javascript-Dateien
└── README.md

Datenmodell

Tabelle	Zweck
Benutzer	Anwendungsnutzer; Primärschlüssel ist der Zitadel-sub
Kunden	Kundenstamm (Firmen oder Privatpersonen)
Kontakte	Ansprechpartner bei einem Kunden (ForeignKey → Kunden)
Projekte	Akquise-Projekte, einem Kunden zugeordnet (ForeignKey → Kunden)
Benutzer_Projekt	n:m-Zuordnung Benutzer ↔ Projekte (Zugriffskontrolle)
Kontaktadressen	Anrufziele innerhalb eines Projekts; importierbar via CSV/Excel (ForeignKey → Projekte)
Gesprächsnotizen	Anrufdokumentation mit Metadaten, Freitext und Tags (ForeignKey → Projekte, Kontaktadressen)
Tags	Benutzerdefinierte hierarchische 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

Alle Dateien, die sich im Verzeichnis ai-context befinden, enthalten für das Projekt wichtige Information. Die wichtigsten sind dabei die folgenden:

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