Hoard/codexInfo.md

# Projektübersicht – self-hosted Datei- und Markdown-App

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

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

## Geplanter Tech-Stack
- Frontend: Vue 3
- Markdown-Editor: md-editor-v3
- Backend: ASP.NET Core mit C#
- Datenbank: PostgreSQL
- Dateispeicher: MinIO als S3-kompatibler Storage
- Authentifizierung: klassische Cookie-basierte Authentifizierung, keine JWTs
- Deployment: self-hosted Web-App auf meinem eigenen Server

## Kernfunktionen für das MVP
- Login mit bestehenden Accounts
- Kein öffentliches Registrieren
- Ein initialer Admin-Account wird zuerst erstellt
- Weitere Benutzer werden später nur manuell durch den Admin angelegt
- Dateien und Ordner anlegen, hochladen und öffnen
- Durch Ordnerstrukturen navigieren
- Google-Drive-artige Hauptansicht mit Dateiliste und Vorschau
- Markdown-Dateien direkt im Browser bearbeiten
- PDFs und Bilder als Vorschau anzeigen
- Andere Dateien einfach speichern und bei Bedarf herunterladen oder öffnen

## Was bewusst nicht Teil des MVP ist
- Keine Registrierung für normale Nutzer
- Kein Teilen oder Freigeben von Dateien
- Keine Suche
- Keine Versionierung oder Dateihistorie
- Keine Echtzeit-Zusammenarbeit
- Keine Desktop-App oder Mobile-App
- Keine komplizierte Rechteverwaltung
- Keine JWT-, OAuth- oder SSO-Lösung

## Gewünschter Stil der Anwendung
Die Oberfläche soll sich eher an Google Drive orientieren als an Notion oder Obsidian. Wichtig sind Übersicht, einfache Navigation und ein klarer Fokus auf Dateien, Ordner, Vorschau und Bearbeitung. Die App soll schlicht, pragmatisch und gut allein umsetzbar sein.

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

## Wie die App später wirken soll
Die Anwendung soll wie eine einfache Dateiverwaltung im Browser wirken. Man meldet sich an, sieht seine Ordner und Dateien, kann sich durch die Struktur klicken, PDFs und Bilder direkt ansehen und Markdown-Dateien öffnen und bearbeiten. Der Fokus liegt auf Einfachheit statt auf vielen Sonderfunktionen.

## Technische Leitidee
Das Projekt soll möglichst einfach aufgebaut werden. Dateimetadaten liegen in PostgreSQL, die eigentlichen Dateien in MinIO. Das Backend verwaltet Login, Benutzer, Ordner, Dateien und Vorschau-Informationen. Das Frontend bildet hauptsächlich die Dateiverwaltung, Vorschau und Markdown-Bearbeitung ab. Die gesamte Architektur soll bewusst schlank bleiben, damit sie für ein Solo-Projekt realistisch ist.

## Projektbeschreibung für eine KI
Ich baue alleine neben meiner Ausbildung eine einfache self-hosted Web-App für mehrere Benutzer. Die App kombiniert eine Google-Drive-artige Dateiverwaltung mit einfacher Markdown-Bearbeitung. Benutzer sollen durch Ordner und Dateien navigieren können, Bilder und PDFs in einer Vorschau sehen und Markdown-Dateien direkt im Browser bearbeiten. Es gibt keine öffentliche Registrierung, kein Teilen, keine Suche und keine Versionierung. Benutzerkonten werden manuell angelegt, beginnend mit einem initialen Admin-Account. Der Tech-Stack besteht aus Vue 3 im Frontend, md-editor-v3 als Markdown-Editor, ASP.NET Core mit C# im Backend, PostgreSQL für Metadaten, MinIO als S3-kompatiblen Dateispeicher und Cookie-basierter Authentifizierung.

## Frontend-Designquelle (Style Guide)
- Es gibt einen zentralen Design-Guide unter `GUI/style.md`.
- Dieser Guide definiert die visuelle Richtung für Hoard: light-first, dateiorientiert, ruhige Flächen, gezielte Verwendung von Grün als Markenfarbe.
- Enthalten sind Farbpalette, Typografie, Spacing, Border-Radien, Schatten, Komponentenregeln und Interaktionsprinzipien.

## Angelegte globale CSS-Basis
- Statt `app.css` wurde eine zentrale globale Datei `GUI/src/global.css` angelegt und verwendet.
- Diese Datei wird in `GUI/src/main.ts` über `import './global.css'` eingebunden.
- Zusätzlich wurden modulare globale CSS-Dateien angelegt: `GUI/src/styles/global/page-layouts.css` und `GUI/src/styles/global/surface-patterns.css`.
- Beide Module werden ebenfalls zentral in `GUI/src/main.ts` eingebunden und bündeln wiederkehrende Layout-/Surface-Patterns.
- Inhaltlich stellt `global.css` bereit:
  - Design-Tokens als CSS-Variablen (`:root`) für Farben, Spacing, Radius, Schatten, Typografie und Statusfarben.
  - Globale Basisstile für `html`, `body`, Links, Überschriften, Fokuszustände und Scrollbars.
  - Vuetify-nahe globale Anpassungen für App-Shell und Standardkomponenten (Topbar, Sidebar, Cards, Buttons, Inputs, Tabellen).
  - Wiederverwendbare Utility-/Pattern-Klassen für Hoard-Seiten, z. B. `hoard-panel`, `hoard-toolbar`, `hoard-list-row`, `hoard-empty-state`, `hoard-status`.
  - Responsive Verhalten für kleinere Viewports per Media Query.

## 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` nutzen, Varianten bei Bedarf mit `hoard-kicker--wide` oder `hoard-kicker--xs`.
- Button-/Link-Aktionszeilen mit `hoard-action-row` bauen statt pro Seite eigene Flex-Definitionen zu duplizieren.
- Gradient-Flächen über `hoard-panel-gradient` + Variablen steuern (`--hoard-gradient-angle`, `--hoard-gradient-start`, `--hoard-gradient-end`, `--hoard-gradient-end-stop`), nicht pro Seite komplett neu definieren.
- Lokales `scoped` CSS nur für wirklich seitenspezifische Styles verwenden; alles Wiederverwendbare zuerst in `GUI/src/styles/global/page-layouts.css` oder `GUI/src/styles/global/surface-patterns.css` ergänzen.

## Aktueller Stand
- `GUI/src/Layout.vue` bildet die zentrale App-Shell mit Topbar, Sidebar, Footer, Routen-Kontext und responsivem Drawer-Verhalten.
- Darkmode (`light`/`dark`) ist global integriert (Toggle in der Topbar, Persistenz in `localStorage`, Theme-Tokens in CSS/Vuetify).
- Öffentliche Kernseiten sind im einheitlichen Hoard-Stil umgesetzt: `Home.vue` (Landingpage), `Login.vue`, `404NotFound.vue`, `Impressum.vue`.
- Das Topbar-Branding nutzt das App-Icon aus `GUI/src/assets/images/icon.svg`.
- Globale CSS-Struktur ist aktiv: `GUI/src/global.css` (Tokens/Basis) sowie `GUI/src/styles/global/page-layouts.css` und `GUI/src/styles/global/surface-patterns.css` für wiederverwendbare Patterns.
- Sidebar-Sichtbarkeit unterstützt `Visibility.Route` mit optionalem `visibilityRoute` in `GUI/src/plugins/routesLayout.ts`.
- Mobile-Touch-Optimierung ist für alle aktuellen öffentlichen Oberflächen aktiv (Shell, Home, Login, Impressum, 404), inklusive Safe-Area-Unterstützung.
- Desktop-Ansicht bleibt unverändert, da alle neuen Anpassungen ausschließlich in mobilen Breakpoints (`<= 960px`, Feinschliff `<= 600px`) umgesetzt sind.
- Backend-API enthält aktuell Basis-Endpunkte für Health (`GET /api/health`) und Auth (`POST /auth/login`, `POST /auth/logout`, `GET /auth/me`).
- Swagger/OpenAPI ist im Backend nur im Development-Modus aktiv (`/swagger`).
- Frontend-Build (`npm run build` im `GUI`-Projekt) schreibt direkt nach `API/wwwroot`; das Backend liefert die SPA und statische Assets aus.
- Backend nutzt jetzt PostgreSQL über `ConnectionStrings:Postgres` mit EF Core (`ApplicationDbContext`) und führt Migrationen beim Start automatisch aus.
- Backend nutzt ASP.NET Identity mit `AppUser` (Guid-Key, `IsActive`, `MustChangePassword`, `CreatedAt`, `UpdatedAt`) über PostgreSQL; Admin-Rechte laufen über Rollen (`admin`) statt User-Flag.
- `ApplicationDbContext` basiert auf `IdentityDbContext`; Identity-Tabellen sind auf `Users`, `Roles`, `UserRoles`, `UserClaims`, `UserLogins`, `RoleClaims` und `UserTokens` gemappt.
- Migration `InitIdentity` (`API/Migrations/20260418192723_InitIdentity.cs`) erstellt das Identity-Schema und wird beim Start automatisch angewendet.
- Temporäre Test-Entity und Test-CRUD-Endpunkt (`api/test-items`) wurden wieder entfernt.
- Nach den Migrationen wird per `IdentitySeedService` die Rolle `admin` sichergestellt und einem initialen Admin-Account zugewiesen, falls noch kein Admin in dieser Rolle existiert.
- Für lokale Entwicklung liegt unter `API/Dev/docker-compose.yml` ein Stack mit PostgreSQL (`localhost:5432`) und pgAdmin (`localhost:5050`).
- API lädt optional `API/appsettings.custom.json`; wenn vorhanden, überschreibt sie Werte aus `appsettings.json`.
- `API/appsettings.custom.json` ist in `.gitignore` hinterlegt, damit lokale Konfigurationswerte nicht versehentlich committed werden.
- Backend-Logging ist aktiviert mit strukturierter Console-Ausgabe (inkl. Zeitstempel) sowie HTTP-Request-Logging.
- Beim Identity-Seeding wird explizit geloggt, wenn ein Admin-Account neu angelegt wurde.
- Frontend-Auth ist jetzt aktiv: Login-Form (`GUI/src/routes/authentication/Login.vue`) sendet an `POST /auth/login` und zeigt API-Fehler als sichtbare Meldung.
- Dashboard ist als geschützte Route auf `/` umgesetzt (`GUI/src/routes/dashboard/Dashboard.vue`) und zeigt die Antwort von `GET /auth/me`.
- Router-Guards in `GUI/src/router/index.ts` leiten nicht eingeloggte Nutzer von geschützten Routen auf `/login` um und leiten eingeloggte Nutzer von `/login` zurück aufs Dashboard.
- Öffentliche Landingpage wurde auf `/welcome` verschoben; `404`- und Impressum-Links zur Startseite zeigen entsprechend auf `/welcome`.
- Sidebar-Navigation berücksichtigt Auth-Status differenziert: `Startseite` wird nur unangemeldet angezeigt (inkl. unterem Drawer-Link), `Dash` nur angemeldet.
- Topbar zeigt bei aktiver Anmeldung den Benutzernamen; die Abmelden-Aktion erscheint im Hover-Menü unter dem Benutzernamen (Desktop) bzw. im Account-Menü (Mobile).
- Fehler werden jetzt global über einen Banner-Stack am unteren Seitenrand angezeigt (routeübergreifend, stapelbar, manuell schließbar).
- Der globale Banner-Stack im Layout nutzt einen kontrollierten `z-index` und opake Hintergründe, damit Fehlermeldungen im Vordergrund bleiben und kaum durchscheinende Inhalte zeigen.
- Klick auf Logo/Branding in der Topbar führt abhängig vom Auth-Status: angemeldet auf `Dashboard`, unangemeldet auf `Welcome`.
- 404-Seite löst den Auth-Status auf und leitet automatisch weiter: angemeldet zu `Dashboard`, unangemeldet zu `Welcome`; primärer CTA ist entsprechend dynamisch.
- Brand-Klick ist gegen Auth-Timing abgesichert: bei vorhandener Session führt Logo/Titel auch bei noch nicht synchronisiertem Layout-Status zuverlässig auf `Dashboard`.
- Admin-Benutzerverwaltung zeigt jetzt echte Kontodaten: `/admin/users` lädt die Benutzerliste aus `GET /auth/user`, `/admin/users/:userId` zeigt read-only Details aus `GET /auth/user/{id}`.
- Der Router erzwingt Passwortwechsel global: bei `mustChangePassword=true` erfolgt vor normaler Navigation ein Redirect auf `/password/change`; nach erfolgreicher Änderung führt der Flow auf Login zurück.
- Im Account-Menü der Topbar gibt es jetzt zusätzlich zur Abmeldung einen direkten Einstieg auf `Passwort ändern` (Desktop und Mobile).
- Sidebar-Navigation trennt adminpflichtige Seiten jetzt in einem eigenen Abschnitt `Admin` (gleicher grüner Kicker-Stil wie `Navigation`), sodass z. B. `Benutzer` nicht mehr direkt neben dem Dashboard steht.
- Frontend-Modernisierung ist aktiv: globale Surface-/Motion-Tokens, kurze Route-/Page-Animationen mit `prefers-reduced-motion`, Dark-/Light-taugliche Farbmischungen sowie responsive Dashboard-/Admin-Übersichten ohne neue API-Calls.
- Topbar-Branding nutzt das App-Icon jetzt größer und ohne gerahmten Icon-Container.
- Mobile Auth-Ansichten wurden nachgeschärft: Dashboard bricht JSON-/Statusinhalte ohne horizontales Überlaufen um, Benutzerverwaltung nutzt mobil Karten statt breiter Tabelle; Desktop bleibt unverändert.

## Änderungen durch Codex
- Frontend/UI: App-Shell, globale Design-Patterns und öffentliche Seiten wurden konsolidiert; Auth-Routing mit Guard-Logik, Banner-Stack sowie rollenbasierte Navigation inkl. Dashboard-, 403- und Admin-User-Oberflächen ist umgesetzt.
- Backend/API: Basis-Endpunkte für Health und Auth wurden auf ASP.NET Identity mit Rollenmodell (admin), `/auth/me` mit `roles`, Admin-User-Listen/Details sowie Passwortwechsel mit Session-Invalidierung erweitert.
- Infrastruktur/Build: Frontend-Build liefert nach `API/wwwroot` mit sauberem SPA-Fallback, PostgreSQL läuft über EF-Core-Migrationen beim Start (inkl. Dev-Docker-Stack), und lokale Overrides via `appsettings.custom.json` plus strukturiertes Logging/Swagger (Development) sind integriert.
- Frontend/UI-Review: Layout, globale Styles, öffentliche Seiten und Admin-/Dashboard-Ansichten wurden optisch modernisiert; `GUI/style.md` dokumentiert die neuen Modernisierungs-, Motion- und Dark-/Light-Regeln.