collabrix/ANNAHMEN.md

# Annahmen und Design-Entscheidungen

## Architektur

### Backend
- **Framework:** FastAPI wurde gewählt wegen nativem async-Support, automatischer API-Dokumentation und moderner Type Hints
- **ORM:** SQLModel kombiniert SQLAlchemy mit Pydantic für typsichere Datenbankmodelle
- **Datenbank:** PostgreSQL 17 wie gefordert, mit vorkonfigurierter Test-DB

### Frontend
- **Framework:** React + TypeScript für typsichere Komponenten
- **Build-Tool:** Vite für schnelle Development-Experience
- **State Management:** React Context API (Auth, Theme) - ausreichend für mittlere Komplexität
- **Styling:** Tailwind CSS für schnelle, konsistente UI-Entwicklung

## Datenmodell

### User ↔ Department (Many-to-Many)
- Ein User kann mehreren Abteilungen angehören
- Implementiert via Link-Tabelle `user_department`

### Channel ↔ Department (One-to-Many)
- Jeder Channel gehört zu genau einer Abteilung
- Zugriff nur für Members dieser Abteilung

### Message ↔ Snippet (Optional Reference)
- Nachrichten können optional auf ein Snippet verweisen
- `snippet_id` ist nullable
- Bei Anzeige wird der Snippet-Code formatiert dargestellt

### Snippet Visibility
- **Private:** Nur Owner sieht es
- **Department:** Alle User in der gleichen Abteilung
- **Organization:** Alle authentifizierten User
- Implementiert via Enum `SnippetVisibility`

## Authentifizierung & Autorisierung

### JWT Bearer Tokens
- **Ablauf:** 30 Minuten (konfigurierbar)
- **Claims:** `sub` (username), `exp` (expiration)
- **Storage:** LocalStorage im Frontend (für Produktiv: HttpOnly Cookies erwägen)

### Passwörter
- **Hashing:** bcrypt via passlib
- **Rounds:** Default (12), sicher für Standard-Anwendungen

### Zugriffskontrolle
- **Channel:** User muss Member der zugehörigen Abteilung sein
- **Message:** Über Channel-Zugriff geprüft
- **Snippet:** Je nach Visibility-Level
- **File:** Über Message-Zugriff geprüft

## Datei-Upload

### Speicherung
- **Lokal:** Filesystem im `UPLOAD_DIR` (konfigurierbar)
- **Pfadstruktur:** Flat (alle Dateien in einem Verzeichnis)
- **Dateinamen:** UUID-basiert zur Vermeidung von Kollisionen
- **Metadaten:** In DB (FileAttachment-Tabelle)

### Limits
- **Max. Größe:** 20 MB (konfigurierbar)
- **Validierung:** Serverseitig vor Speicherung
- **MIME-Types:** Keine Einschränkung (in Production: Whitelist empfohlen)

### Download
- **Berechtigung:** Nur User mit Zugriff auf den Channel
- **Methode:** FileResponse via FastAPI
- **Original-Dateiname:** Wird im Response-Header gesetzt

## WebSocket

### Connection Management
- **Pro Channel:** Separate WebSocket-Verbindung
- **Authentifizierung:** Token via Query-Parameter `?token=...`
- **Broadcast:** Neue Nachrichten an alle aktiven Clients im Channel
- **Reconnect:** Client-seitig (im Frontend implementiert)

### Nachrichtenformat
```json
{
  "type": "message",
  "content": "...",
  "sender": "username",
  "channel_id": 1
}
```

## Code-Snippet-Bibliothek

### Tags
- **Format:** Kommagetrennte Strings in einem Feld
- **Suche:** Einfache LIKE/ILIKE-Queries
- **Rationale:** Einfach zu implementieren, ausreichend für MVP
- **Alternative:** Separate Tag-Tabelle (für Produktiv mit vielen Tags)

### Syntax-Highlighting
- **Frontend:** Manuelles `<pre><code>` ohne externe Library
- **Erweiterung:** Prism.js oder Highlight.js können leicht integriert werden
- **Theme-Support:** Code-Blöcke passen sich an Light/Dark-Theme an

### Filter & Suche
- **Language:** Exakte Übereinstimmung
- **Tags:** Enthält-Suche (any of)
- **Search:** Volltextsuche in Title + Content
- **Performance:** Für große Mengen: Full-Text-Search in PostgreSQL nutzen

## UI/UX

### Layout
- **3-Spalten-Ansicht:** Sidebar | Chat/Snippet-Liste | Detail
- **Teams-ähnlich:** Linke Sidebar für Navigation, Hauptbereich für Inhalt
- **Responsive:** Mobile-First mit Tailwind-Breakpoints

### Theme
- **Persistenz:** LocalStorage
- **Default:** System-Präferenz (könnte via `prefers-color-scheme` erweitert werden)
- **Toggle:** Globaler Button im Header
- **CSS:** Tailwind's `dark:` Klassen

### Navigation
- **React Router:** Client-side Routing
- **Protected Routes:** HOC `ProtectedRoute` prüft Auth-Status
- **Tabs:** Chat vs. Snippets über Links im Header

## Tests

### Test-Datenbank
- **SQLite In-Memory:** Schneller als PostgreSQL für Unit-Tests
- **Alternative:** Separate PostgreSQL-DB für Integration-Tests
- **Fixtures:** pytest Fixtures für User, Dept, Channel, etc.

### Test-Coverage
- **Auth:** Registrierung, Login, Token-Validierung
- **Channels:** CRUD, Zugriffskontrolle
- **Messages:** Erstellen, Laden, Channel-Berechtigung
- **Files:** Upload, Download, Größenlimit
- **Snippets:** CRUD, Visibility, Suche, Filter

### Test-Framework
- **pytest:** Standard für Python-Testing
- **TestClient:** FastAPI's HTTPX-basierter Client
- **Async:** pytest-asyncio für async Tests

## Skalierung & Performance

### Optimierungen (nicht implementiert, aber empfohlen für Produktiv)
1. **Caching:** Redis für Sessions, häufig abgerufene Daten
2. **Pagination:** Implementiert für Messages, sollte auch für Snippets erweitert werden
3. **Rate-Limiting:** Schutz vor Missbrauch (slowapi oder middleware)
4. **File-Storage:** S3-kompatible Lösung statt Filesystem
5. **WebSocket-Scaling:** Redis Pub/Sub für Multi-Server-Setup
6. **DB-Indizes:** Auf häufig gesuchten Feldern (language, tags, created_at)
7. **Query-Optimierung:** Eager Loading für Relations

## Sicherheit

### Implementiert
- ✅ Passwort-Hashing (bcrypt)
- ✅ JWT-Authentifizierung
- ✅ Zugriffskontrolle pro Ressource
- ✅ CORS-Konfiguration
- ✅ SQL-Injection-Schutz (via ORM)
- ✅ Dateigrößen-Limits

### Für Produktiv noch nötig
- ⚠️ HTTPS/TLS
- ⚠️ Rate-Limiting
- ⚠️ CSRF-Protection
- ⚠️ Content Security Policy
- ⚠️ Input-Sanitization (XSS)
- ⚠️ Datei-Type-Whitelist
- ⚠️ Audit-Logging
- ⚠️ 2FA/MFA

## Deployment

### Docker
- **Multi-Stage Build:** Optimierte Images
- **Health-Checks:** PostgreSQL-Readiness vor Backend-Start
- **Volumes:** Persistente Daten (DB, Uploads)
- **Networks:** Isolierte Container-Kommunikation

### Umgebungsvariablen
- Alle sensiblen Daten via `.env`
- Produktiv: Secrets-Management (Vault, AWS Secrets Manager)

## Erweiterungsmöglichkeiten

### Kurzfristig
1. **Snippet-Versioning:** Historie von Snippet-Änderungen
2. **User-Profil:** Avatar, Bio, Präferenzen
3. **Notifications:** In-App-Benachrichtigungen für @mentions
4. **Emoji-Reactions:** React auf Nachrichten
5. **Thread-Replies:** Diskussionen organisieren

### Mittelfristig
1. **Video/Voice-Calls:** WebRTC-Integration
2. **Screen-Sharing:** Für Präsentationen
3. **Advanced Search:** ElasticSearch für bessere Suche
4. **Analytics:** Dashboard für Chat-Aktivität
5. **Admin-Panel:** User-/Department-Management

### Langfristig
1. **Mobile Apps:** React Native oder native iOS/Android
2. **Desktop App:** Electron-Wrapper
3. **Integrations:** Jira, GitHub, GitLab, Slack
4. **Bot-Framework:** Automatisierte Antworten, Workflows
5. **AI-Features:** Smart Replies, Sentiment-Analyse

## Technische Schulden & Kompromisse

### Bekannte Limitierungen
1. **Tag-System:** Einfache String-Liste, keine Autovervollständigung
2. **WebSocket-Auth:** Token in Query-String (Alternative: Cookie-basiert)
3. **File-Storage:** Lokal statt Object-Storage
4. **No Email:** Keine E-Mail-Benachrichtigungen implementiert
5. **No Pagination:** Snippets ohne Pagination (bei vielen Snippets Problem)

### Rationale
- **MVP-Fokus:** Schnelle Entwicklung, Kernfunktionen zuerst
- **Einfachheit:** Weniger externe Dependencies
- **Verständlichkeit:** Code für Team leicht wartbar

## Lessons Learned

### Was gut funktioniert
- SQLModel: Sehr typsicher, wenig Boilerplate
- FastAPI: Automatische Docs, schnelle Entwicklung
- Tailwind: Schnelles Styling ohne Custom CSS
- Docker-Compose: Einfaches lokales Setup

### Was verbessert werden könnte
- WebSocket-Reconnect-Logik robuster machen
- Mehr End-to-End-Tests
- CI/CD-Pipeline aufsetzen
- Monitoring & Logging strukturieren

---

**Autor:** Senior-Entwickler  
**Datum:** 2025-12-06  
**Version:** 1.0