docs: vollständige README mit Architektur, Tech-Stack und Tag-Konzept

README.md

@@ -1,3 +1,161 @@
-# gitea-projekt-dashboard
+# 🗂️ Gitea Projekt-Dashboard
 
-Gitea-Projektverwaltung mit Dashboard-Integration – zeigt alle Repos mit einem bestimmten Tag
+Ein selbst gehostetes Dashboard, das automatisch alle Gitea-Repositories anzeigt, die mit einem bestimmten **Topic-Tag** versehen sind.
+
+---
+
+## 🏷️ Funktionsprinzip: Tag-basierte Projektanzeige
+
+Jedes Repository, das auf dieser Gitea-Instanz mit dem Topic-Tag `dashboard` versehen ist, wird automatisch im Dashboard angezeigt.
+
+### So funktioniert es:
+
+1. Du setzt in einem Gitea-Repository unter **Settings → Topics** das Tag `dashboard`
+2. Der Backend-Service pollt regelmäßig (oder per Webhook) die Gitea API nach allen Repos mit diesem Tag
+3. Die gefundenen Repos werden in der PostgreSQL-Datenbank gespeichert und gecacht
+4. Das Frontend zeigt alle getaggten Repos als Projektkarten mit Live-Daten an
+
+> **Beispiel:** Repo `mein-projekt` bekommt das Topic `dashboard` → erscheint sofort im Dashboard mit Issues, letztem Commit, Status und Beschreibung.
+
+---
+
+## 🧱 Architektur
+
+```
+┌─────────────────┐     Gitea REST API v1     ┌──────────────────────┐
+│   Gitea Server  │ ◄────────────────────────► │   Backend Service    │
+│ (Repos + Topics)│                            │  (Bun + Hono)        │
+└─────────────────┘                            └──────────┬───────────┘
+                                                          │
+                                               ┌──────────▼───────────┐
+                                               │   PostgreSQL DB       │
+                                               │ (Repos, Issues,       │
+                                               │  Milestones, Cache)   │
+                                               └──────────┬───────────┘
+                                                          │
+                                               ┌──────────▼───────────┐
+                                               │   Frontend           │
+                                               │   (SvelteKit)        │
+                                               └──────────────────────┘
+```
+
+---
+
+## 🖥️ Frontend: **SvelteKit**
+
+**Warum SvelteKit?**
+- Leichtgewichtig und schnell – ideal für ein internes Dashboard
+- Server-Side Rendering (SSR) out of the box – kein Flackern beim Laden
+- Einfache Reaktivität ohne overhead
+- Perfekt für datengetriebene Dashboards mit Echtzeit-Updates via SSE oder WebSocket
+
+**Features im Frontend:**
+- Projektkarten mit Repo-Name, Beschreibung, letztem Commit, offenen Issues
+- Filterfunktion nach Topics, Sprache, Aktivität
+- Detailansicht: Issues & Milestones direkt im Dashboard bearbeiten (bi-direktional)
+- Live-Updates via Webhook-Events (Server-Sent Events)
+- Dark Mode, responsive Design
+
+---
+
+## ⚙️ Backend: **Bun + Hono**
+
+**Warum Bun + Hono?**
+- Bun ist deutlich schneller als Node.js – geringere Latenz bei API-Polling
+- Hono ist ein ultraleichtes Web-Framework, ideal für REST APIs
+- Nativer TypeScript-Support ohne Konfigurationsaufwand
+- Eingebauter Cron-Job-Support für regelmäßiges Gitea-Polling
+
+**Backend-Aufgaben:**
+- `GET /api/projects` – alle getaggten Repos aus der DB zurückgeben
+- `POST /api/webhook` – Gitea Webhook-Listener für Push, Issue, Tag-Events
+- `GET /api/projects/:id/issues` – Issues eines Repos live aus Gitea holen
+- Hintergrund-Job: alle 5 Minuten Gitea API nach Repos mit Tag `dashboard` abfragen
+- Repo-Daten in PostgreSQL cachen (inkl. Topics, letzter Aktivität, Issue-Count)
+
+---
+
+## 🗄️ Datenbank: **PostgreSQL**
+
+**Schema-Übersicht:**
+
+```sql
+-- Gecachte Repo-Informationen
+CREATE TABLE projects (
+  id           SERIAL PRIMARY KEY,
+  gitea_id     INTEGER UNIQUE NOT NULL,
+  name         VARCHAR(255) NOT NULL,
+  full_name    VARCHAR(255) NOT NULL,
+  description  TEXT,
+  html_url     TEXT,
+  topics       TEXT[],           -- z.B. ["dashboard", "freelancer"]
+  language     VARCHAR(100),
+  open_issues  INTEGER DEFAULT 0,
+  last_push    TIMESTAMPTZ,
+  is_private   BOOLEAN DEFAULT false,
+  synced_at    TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- Gemanagte Issues / Aufgaben
+CREATE TABLE issues (
+  id           SERIAL PRIMARY KEY,
+  gitea_id     INTEGER NOT NULL,
+  project_id   INTEGER REFERENCES projects(id),
+  title        TEXT NOT NULL,
+  state        VARCHAR(20),      -- open / closed
+  assignee     VARCHAR(100),
+  milestone    TEXT,
+  updated_at   TIMESTAMPTZ
+);
+
+-- Webhook-Event-Log
+CREATE TABLE webhook_events (
+  id           SERIAL PRIMARY KEY,
+  event_type   VARCHAR(50),
+  payload      JSONB,
+  received_at  TIMESTAMPTZ DEFAULT NOW()
+);
+```
+
+---
+
+## 🚀 Roadmap
+
+- [ ] **v0.1** – Repo-Listing via Tag `dashboard`, Polling alle 5 min
+- [ ] **v0.2** – Webhook-Listener für Echtzeit-Updates
+- [ ] **v0.3** – Issues & Milestones im Dashboard anzeigen
+- [ ] **v0.4** – Issues direkt aus dem Dashboard erstellen/schließen (bi-direktional)
+- [ ] **v0.5** – Verknüpfung mit Freelancer-Dashboard (Repos = Projekte)
+- [ ] **v1.0** – Auth, Multi-User, öffentliche Projektsseiten
+
+---
+
+## 🔧 Tech Stack
+
+| Schicht    | Technologie              |
+|------------|--------------------------|
+| Frontend   | SvelteKit + TailwindCSS  |
+| Backend    | Bun + Hono (TypeScript)  |
+| Datenbank  | PostgreSQL + Drizzle ORM |
+| API        | Gitea REST API v1        |
+| Deployment | Docker Compose           |
+
+---
+
+## 📦 Getting Started
+
+```bash
+# Repo klonen
+git clone https://gitea.starfour.de/Jannis/gitea-projekt-dashboard
+
+# Umgebungsvariablen setzen
+cp .env.example .env
+# GITEA_URL, GITEA_TOKEN, DATABASE_URL, DASHBOARD_TAG eintragen
+
+# Mit Docker starten
+docker compose up -d
+```
+
+---
+
+*Dieses Projekt ist Teil der persönlichen Projekt-Ideen-Sammlung. Zugehöriges Übersichts-Repo: [projekt-ideen](https://gitea.starfour.de/Jannis/projekt-ideen)*