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

{
  "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