Linus Waldowsky
73e768a0ad
JWT was never used - auth uses X-User-Id header. Removes jwt.ts utility, jsonwebtoken dependency, stubbed refresh/logout endpoints, and updates all docs (PUML diagrams, api-routes, tex, CLAUDE.md) accordingly.
233 lines
8.5 KiB
TeX
233 lines
8.5 KiB
TeX
\documentclass[a4paper,11pt]{article}
|
|
\usepackage[
|
|
a4paper,
|
|
top=2cm,
|
|
bottom=2cm,
|
|
left=2cm,
|
|
right=2cm,
|
|
marginparwidth=1.75cm
|
|
]{geometry}
|
|
\usepackage[utf8]{inputenc}
|
|
\usepackage[ngerman]{babel}
|
|
\usepackage{parskip} % spacing and indent of paragraphs
|
|
\usepackage{setspace} % line spacing
|
|
\usepackage{graphicx}
|
|
\usepackage{fontspec} % needed to use system fonts
|
|
\usepackage{cite}
|
|
\usepackage{hyperref} % adds clickable links
|
|
\usepackage{float} % to show figures where i want them
|
|
\usepackage{natbib} % quote styling (activates citep)
|
|
\usepackage{enumitem} % list spacing
|
|
|
|
\bibliographystyle{apalike}
|
|
|
|
\graphicspath{ {./res} {./} }
|
|
\setmainfont{ITC Officina Sans Std Book}
|
|
\renewcommand{\baselinestretch}{1.15} % linespace
|
|
\newcommand{\q}[1]{``#1''} % short hand quotation marks
|
|
|
|
\begin{document}
|
|
|
|
% Sollte erst am Ende auskommentiert werden um die letzten 'overfull' hboxes zu
|
|
% beseitigen
|
|
%\tolerance=500
|
|
|
|
\title{Technisches brainstorm}
|
|
\author{Linus Waldowsky}
|
|
\date{\today}
|
|
|
|
\maketitle
|
|
|
|
\tableofcontents
|
|
|
|
\section{CalChat}
|
|
|
|
Bei dem Projekt CalChat handelt es sich um eine Kalender-Mobile-App mit
|
|
KI-Unterstützung. Das Besondere an der Sache ist, dass die Kalender-Events
|
|
größtenteils über ein Chatinterface mit Hilfe eines KI-Chatbots erstellt werden
|
|
sollen.
|
|
|
|
CalChat wird als Fullstack Typescript Applikation aufgesetzt.
|
|
|
|
\section{Technologien}
|
|
|
|
\begin{table}[H]
|
|
\centering
|
|
\begin{tabular}{|l|l|l|}
|
|
\hline
|
|
\textbf{Bereich} & \textbf{Technologie} & \textbf{Zweck} \\
|
|
\hline
|
|
Frontend & React Native & Mobile UI Framework \\
|
|
& Expo & Entwicklungsplattform \\
|
|
& Expo-Router & Dateibasiertes Routing \\
|
|
& Tailwind / Nativewind & Styling \\
|
|
\hline
|
|
Backend & Express.js & Web-App Framework \\
|
|
& MongoDB & Datenbank \\
|
|
& Mongoose & ODM \\
|
|
& Claude (Anthropic) & KI / LLM \\
|
|
& X-User-Id Header & Authentifizierung \\
|
|
\hline
|
|
Geplant & iCalendar & Event-Export \\
|
|
\hline
|
|
\end{tabular}
|
|
\caption{Technologie-Stack}
|
|
\end{table}
|
|
|
|
|
|
\subsection{Frontend}
|
|
|
|
Das Frontend wird \textbf{React Native} in Kombination mit dem Framework
|
|
\textbf{Expo} nutzen. Expo bietet u.a. einer eigenen Standard-Bibliothek von
|
|
nativen Modulen. Außerdem vereinfach es die Entwicklung plattformübergreifender
|
|
Apps (IOS, Android und sogar Web) nochmal deutlich.
|
|
|
|
Expo's Routing-Framework, genannt \textbf{Expo-Router}, ist von Next.js
|
|
inspiriert und verwendet ein dateibasiertes Routing (ähnlich wie Next.js). Bei
|
|
diesem System wird bei jeder im app-Ordner erstellten Datei automatisch eine
|
|
neue Route in der Anwendung generiert.
|
|
|
|
Das Styling für die App übernimmt, neben dem bereits eingebauten Styling über
|
|
CSS, \textbf{Tailwind}. Tailwind ist ein CSS Framework, welches hauptsächlich
|
|
aus einer großen Anzahl an vorbereiteten CSS-Klassen besteht, aus denen jedes
|
|
Design zusammengesetzt werden kann. \textbf{Nativewind} macht diese Klassen in
|
|
React Native nutzbar.
|
|
|
|
\subsection{Backend}
|
|
|
|
\textbf{Express.js} dient als Web-App Framework. Es ist leichtgewichtig, auf
|
|
Node.js basierend und bietet ein minimales Grundgerüst, das nach Bedarf
|
|
erweitert werden kann.
|
|
|
|
Die Daten werden in \textbf{MongoDB}, einer dokumentenorientierten
|
|
NoSQL-Datenbank gespeichert. Statt starrer Tabellen arbeitet MongoDB mit
|
|
JSON-ähnlichen Dokumenten, was flexible Schemas und eine natürliche Integration
|
|
mit JavaScript ermöglicht.
|
|
|
|
\textbf{Mongoose} übernimmt die Kommunikation mit MongoDB. Als ODM (Object
|
|
Document Mapper) stellt es Schema-Definitionen, Validierung und
|
|
Typkonvertierung bereit.
|
|
|
|
Der wichtigste Teil der App ist die KI-Integration über \textbf{Claude}
|
|
(Anthropic). Dieses LLM verarbeitet natürlichsprachliche Eingaben der Nutzer und
|
|
generiert daraus strukturierte Event-Vorschläge.
|
|
|
|
Die Authentifizierung erfolgt über einen \textbf{X-User-Id Header}, der bei
|
|
jedem Request die User-ID mitschickt. Diese einfache Lösung reicht für den
|
|
aktuellen Entwicklungsstand aus.
|
|
|
|
Geplant ist außerdem die Unterstützung des \textbf{iCalendar}-Formats (ICAL)
|
|
für den Export von Kalender-Events.
|
|
|
|
\section{Architektur}
|
|
|
|
\subsection{Frontend}
|
|
|
|
\begin{figure}[H]
|
|
\centering
|
|
\includegraphics[width=0.9\textwidth]{{Frontend Klassendiagramm}.png}
|
|
\caption{Frontend Klassendiagramm}
|
|
\end{figure}
|
|
|
|
Das Frontend ist in vier Bereiche gegliedert. Die Screens bilden die
|
|
Hauptansichten der App: Login, Kalenderübersicht, Chat, Event-Details und
|
|
Notizen. Die Services kapseln die Kommunikation mit dem Backend. Ein zentraler
|
|
API Client übernimmt alle HTTP-Anfragen, während spezialisierte Services (Auth,
|
|
Event, Chat) die jeweilige Fachlogik bereitstellen. Die Components sind
|
|
wiederverwendbare UI-Bausteine wie EventCard, ChatBubble oder der
|
|
EventConfirmDialog. In den Stores wird der Anwendungszustand verwaltet. Der Auth
|
|
Store speichert User und Token, der Events Store die Kalender-Events.
|
|
|
|
\subsection{Shared Bereich}
|
|
|
|
Im Shared-Paket (\texttt{@caldav/shared}) befinden sich TypeScript-Typen und
|
|
Interfaces, die sowohl vom Frontend als auch vom Backend verwendet werden. Dazu
|
|
gehören vor allem die Datenmodelle für User, CalendarEvent (inkl. optionalem
|
|
Notiz-Feld) und ChatMessage.
|
|
|
|
\subsection{Backend}
|
|
|
|
\begin{figure}[H]
|
|
\centering
|
|
\includegraphics[width=0.9\textwidth]{{Backend Klassendiagramm}.png}
|
|
\caption{Backend Klassendiagramm}
|
|
\end{figure}
|
|
|
|
\subsubsection{Controller Layer}
|
|
|
|
Der Controller Layer bildet die Schnittstelle zwischen Frontend und
|
|
Backend-Logik. Die Routes definieren die API-Endpunkte, die Controller
|
|
verarbeiten die eingehenden Requests und reichen diese an die Services weiter.
|
|
Eine Auth Middleware prüft bei geschützten Routen den X-User-Id Header.
|
|
|
|
\subsubsection{Service Layer}
|
|
|
|
Der Service Layer enthält die Geschäftslogik der Anwendung. Er definiert
|
|
Interfaces für den Zugriff auf Datenbank und KI, die von den darunterliegenden
|
|
Schichten implementiert werden. Der AuthService kümmert sich um Login und
|
|
Token-Erstellung, der EventService um das Erstellen, Bearbeiten und Löschen von
|
|
Events. Der ChatService verarbeitet Nachrichten, kommuniziert mit der KI und
|
|
generiert Event-Vorschläge.
|
|
|
|
\subsubsection{AI Layer}
|
|
|
|
Der AI Layer implementiert das AIProvider-Interface aus dem Service Layer. Der
|
|
ClaudeAdapter kapselt die Kommunikation mit der Claude API und übersetzt
|
|
natürlichsprachliche Eingaben in strukturierte Event-Daten.
|
|
|
|
\subsubsection{Data Access Layer}
|
|
|
|
Der Data Access Layer implementiert die Repository-Interfaces aus dem Service
|
|
Layer. Die MongoDB-Repositories übernehmen alle Datenbankoperationen über
|
|
Mongoose. So bleibt die Geschäftslogik von der konkreten Datenbank entkoppelt.
|
|
|
|
\subsubsection{Models}
|
|
|
|
Die Models definieren die Datenstrukturen, die von allen Schichten verwendet
|
|
werden. Gemeinsame Models (User, CalendarEvent, ChatMessage) liegen im
|
|
Shared-Paket. Backend-spezifische Models, die z.B. zusätzliche Datenbankfelder
|
|
enthalten, liegen im Server und erweitern teilweise die Shared-Models.
|
|
|
|
\section{Funktionsumfang für das MVP}
|
|
|
|
\subsection{Must-Haves}
|
|
|
|
\begin{itemize}[noitemsep]
|
|
\item \textbf{Chat-Interface mit KI-Assistent}: Texteingabe reicht für den
|
|
Anfang. Die KI kann Events hinzufügen, bearbeiten und löschen.
|
|
\item \textbf{Kalender-Übersicht}: Visuelle Darstellung aller Events.
|
|
\item \textbf{Manuelle Event-Verwaltung}: Events auch ohne KI hinzufügen,
|
|
bearbeiten und löschen.
|
|
\item \textbf{Übersicht beendeter Events}: Abgeschlossene Events einsehen.
|
|
\item \textbf{Erinnerungsfunktion}: Einfache Benachrichtigungen.
|
|
\item \textbf{Notizen}: Eine Notiz pro Event.
|
|
\item \textbf{Wiederkehrende Events}: Events mit Wiederholungsintervall.
|
|
\end{itemize}
|
|
|
|
\subsection{Nice-to-Haves}
|
|
|
|
\begin{itemize}[noitemsep]
|
|
\item \textbf{iCalendar-Import/Export}: Events im standardisierten Format
|
|
exportieren und aus diesem Format importieren.
|
|
\item \textbf{Mehrere Kalender}: Events in verschiedene Kalender einordnen.
|
|
\item \textbf{CalDAV-Synchronisation}: Anbindung an externe
|
|
Kalender-Dienste.
|
|
\end{itemize}
|
|
|
|
\section{Aktueller Entwicklungsstand}
|
|
|
|
Das Projekt ist als Monorepo mit npm Workspaces aufgesetzt. Die drei Pakete
|
|
(\texttt{apps/client}, \texttt{apps/server}, \texttt{packages/shared}) teilen
|
|
sich gemeinsame Abhängigkeiten. Client und Server können Types aus dem
|
|
Shared-Paket importieren.
|
|
|
|
Im Frontend läuft eine Expo-App mit React Native und Nativewind für das
|
|
Styling. Das dateibasierte Routing über Expo-Router ist eingerichtet. Der
|
|
Kalender- und der Chat-Screen sind bereits teilweise implementiert.
|
|
|
|
Das Backend besteht aus einem Express.js-Grundgerüst, das auf Port 3000 läuft.
|
|
|
|
Im Shared-Paket liegt die Struktur für gemeinsame TypeScript-Typen bereit.
|
|
|
|
\end{document}
|