Hoard/CLAUDE.md

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

# 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.