# CLAUDE.md – Projektkontext für Hoard

Diese Datei gibt Claude (und allen weiteren Beitragenden) den nötigen Kontext, um an Hoard sinnvoll und konsistent weiterzubauen. Sie ersetzt die alte `codexInfo.md`.

## Projektidee
Hoard ist eine self-hosted Web-App, die sich funktional zwischen Google Drive, Notion und Obsidian einordnet. Der Schwerpunkt liegt auf einer **Google-Drive-artigen Oberfläche** mit Dateien und Ordnern. Markdown-Dateien sollen direkt im Browser bearbeitet werden, andere Dateien gespeichert und – wenn möglich – als Vorschau angezeigt werden.

## Ziel des Projekts
Hoard ist ein bewusst einfach gehaltenes Solo-Projekt neben einer Ausbildung. Es soll mehrere Benutzer unterstützen, dabei aber technisch und funktional schlank bleiben. Wichtig ist ein realistisches MVP, das sauber läuft und später erweitert werden kann.

## Tech-Stack
- **Frontend:** Vue 3 + TypeScript + Vite + Vuetify 4 + Pinia + Vue Router
- **Markdown-Editor:** md-editor-v3 (geplant)
- **Backend:** ASP.NET Core (C#)
- **Datenbank:** PostgreSQL (EF Core, Migrationen beim Start)
- **Identity:** ASP.NET Identity, Cookie-basierte Auth, Rollenmodell (`admin`)
- **Dateispeicher:** MinIO als S3-kompatibler Storage (geplant)
- **Deployment:** Self-hosted; Frontend-Build geht direkt nach `API/wwwroot`

## Kernfunktionen für das MVP
- Login mit bestehenden Accounts (kein öffentliches Registrieren)
- Initialer Admin-Account, weitere Benutzer manuell durch Admins
- Dateien und Ordner anlegen, hochladen, öffnen, navigieren
- Dateiliste + Vorschau als Hauptansicht
- Markdown direkt im Browser bearbeiten
- PDFs und Bilder als Vorschau
- Andere Dateien speichern, herunterladen oder öffnen

## Was bewusst nicht im MVP ist
- Keine offene Registrierung
- Kein Teilen oder Freigeben
- Keine Suche, keine Versionierung
- Keine Echtzeit-Zusammenarbeit
- Keine Desktop-/Mobile-Apps
- Keine komplexe Rechteverwaltung
- Kein JWT/OAuth/SSO

## Sprachregel für UI-Texte
- Umlaute ausdrücklich erwünscht (`ä`, `ö`, `ü`, `Ä`, `Ö`, `Ü`).
- Keine Umschreibungen mit `ae`, `oe`, `ue` in sichtbaren deutschen Texten.

## Design-Quelle
- Maßgeblich ist `GUI/style.md`. Dort liegen Farbpalette, Typografie, Spacing, Radien, Schatten, Komponentenregeln, Motion- und Responsive-Standards.
- Die App ist **light-first**, dateiorientiert und nutzt **Grün als kontrollierte Markenfarbe** statt Dauerakzent.
- Der modernisierte Look (siehe `GUI/style.md` → „Modernisierungs-Direktive") darf hochwertiger und visuell präziser wirken, bleibt aber ruhig, klar und produktiv – kein Gaming-, Glassmorphism- oder Marketing-Look.

## Globale CSS-Basis
- `GUI/src/global.css` hält alle Design-Tokens (`:root`/`[data-theme='dark']`), Basis-Resets, Vuetify-Anpassungen und wiederverwendbare Patterns (`hoard-panel`, `hoard-toolbar`, `hoard-list-row`, `hoard-empty-state`, `hoard-status`, …).
- `GUI/src/styles/global/page-layouts.css` enthält Page-Shells (`hoard-page`, `hoard-page--centered`, `hoard-shell-grid`).
- `GUI/src/styles/global/surface-patterns.css` enthält wiederkehrende Surface-/Inhaltsbausteine (`hoard-kicker`, `hoard-action-row`, `hoard-panel-gradient`, `hoard-chip`, `hoard-spotlight` …).
- Alle drei werden in `GUI/src/main.ts` einmalig importiert.
- Neue Layouts/Patterns immer **zuerst** dort ergänzen, nicht in `scoped`-Styles duplizieren.

## Anleitung: CSS-Patterns verwenden
- Neue Seiten standardmäßig mit `hoard-page` aufbauen; für zentrierte Vollhöhen-Ansichten zusätzlich `hoard-page--centered`.
- Karten-/Shell-Container als `hoard-shell-grid hoard-panel` verwenden; Breite/Abstände pro Seite über CSS-Variablen setzen (`--hoard-shell-width`, `--hoard-shell-gap`, `--hoard-shell-padding`).
- Wiederkehrende Headlines/Kicker mit `hoard-kicker` (+ ggf. `--wide`/`--xs`).
- Aktionszeilen mit `hoard-action-row` bauen statt eigene Flex-Definitionen pro Seite.
- Gradient-Flächen über `hoard-panel-gradient` + Variablen steuern.
- Lokales `scoped` CSS nur für wirklich seitenspezifische Sonderfälle.

## Aktueller Stand (Identity-Branch)
- `GUI/src/Layout.vue` ist die zentrale App-Shell: Topbar, Sidebar, Footer, responsiver Drawer, globaler Banner-Stack.
- Light-/Dark-Mode global integriert (Toggle in der Topbar, Persistenz in `localStorage`, Theme-Tokens in CSS und Vuetify).
- Öffentliche Kernseiten im Hoard-Stil: `Home.vue` (Landing), `Login.vue`, `404NotFound.vue`, `Impressum.vue`, `Forbidden.vue`.
- Geschützter Bereich: `Dashboard.vue`, `ChangePassword.vue`, `AdminUsers.vue`, `AdminUserDetail.vue`.
- Sidebar berücksichtigt Auth-/Rollen-Status; Admin-Bereich ist visuell abgesetzt.
- Mobile Touch-Optimierung (Safe-Area, 44/48px Mindestgrößen, Bottom-Drawer) ist aktiv.
- Backend-API: Health (`GET /api/health`), Auth (`POST /auth/login`, `POST /auth/logout`, `GET /auth/me`, `POST /auth/password`), Admin-User (`GET /auth/user`, `GET /auth/user/{id}`).
- Swagger nur in Development (`/swagger`).
- Frontend-Build (`npm run build` in `GUI`) schreibt nach `API/wwwroot`; das Backend liefert SPA + statische Assets.
- PostgreSQL via `ConnectionStrings:Postgres`, EF Core, automatische Migrationen beim Start.
- ASP.NET Identity mit `AppUser` (Guid-Key, `IsActive`, `MustChangePassword`, `CreatedAt`, `UpdatedAt`); Admin-Rechte über Rolle `admin`.
- `IdentitySeedService` legt nach Migrationen die `admin`-Rolle an und sichert einen initialen Admin-Account.
- Lokale Entwicklung: `API/Dev/docker-compose.yml` mit PostgreSQL (`localhost:5432`) und pgAdmin (`localhost:5050`).
- API lädt optional `API/appsettings.custom.json` (in `.gitignore`).
- Strukturierte Console-/HTTP-Logs aktiv.
- Frontend-Auth: Login → `/auth/login`, Dashboard auf `/`, Router-Guards prüfen Auth/Rollen, erzwingen Passwortwechsel bei `mustChangePassword=true`.
- Public Landingpage liegt auf `/welcome`; 404/Impressum referenzieren entsprechend.
- Topbar zeigt User-Menü (Dashboard, Passwort ändern, Abmelden).
- Globaler Banner-Stack am unteren Rand (stapelbar, manuell schließbar, opake Hintergründe, kontrolliertes `z-index`).

## Konventionen für Beitragende (auch Claude)
- **Erst Patterns, dann Custom-CSS:** Globale Klassen aus `global.css`/`page-layouts.css`/`surface-patterns.css` nutzen, bevor neue Stile lokal entstehen.
- **Tokens statt Hex:** Farben/Spacings/Radien immer aus CSS-Variablen ziehen, damit Light-/Dark-Mode automatisch funktionieren.
- **Mobile QA Pflicht** auf `360x800`, `390x844`, `768x1024`, `1024x768` und `>=1280`. Light- und Dark-Mode jeweils mindestens auf Desktop und Mobile prüfen.
- **Animationen:** kurz (160–280 ms), `prefers-reduced-motion` immer respektieren.
- **API-Kontrakte stabil halten:** Frontend-Refactorings dürfen Backend-Endpunkte oder Auth-Flow nicht brechen.

## Befehle
```bash
# Frontend dev
cd GUI && npm install && npm run dev

# Frontend build (geht nach API/wwwroot)
cd GUI && npm run build

# Type-Check ohne Build
cd GUI && npm run type-check

# Lokale Datenbank
cd API/Dev && docker compose up -d
```

## Projektbeschreibung für eine KI
Hoard ist eine self-hosted Web-App für mehrere Benutzer, die eine Google-Drive-artige Dateiverwaltung mit einfacher Markdown-Bearbeitung kombiniert. Benutzer navigieren durch Ordner und Dateien, sehen Bilder und PDFs in einer Vorschau und bearbeiten Markdown direkt im Browser. Es gibt keine offene Registrierung, kein Teilen, keine Suche und keine Versionierung. Benutzerkonten werden manuell angelegt, beginnend mit einem initialen Admin-Account. Tech-Stack: Vue 3 (TypeScript, Vuetify, Pinia) im Frontend, ASP.NET Core mit C# im Backend, PostgreSQL für Metadaten, MinIO als S3-kompatibler Dateispeicher, Cookie-basierte Authentifizierung. Design: light-first, dateiorientiert, ruhig, mit kontrolliertem Grün als Markenfarbe – modernisiert und visuell präzise, aber bewusst nicht spektakulär.