From 500a655f201066e75c5f11b4449e1a7320ee65e0 Mon Sep 17 00:00:00 2001 From: Jannis Date: Tue, 28 Apr 2026 09:37:51 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20vollst=C3=A4ndige=20README=20mit=20Arch?= =?UTF-8?q?itektur,=20Tech-Stack=20und=20Tag-Konzept?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 162 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 160 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 65c3886..8ff87eb 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,161 @@ -# gitea-projekt-dashboard +# πŸ—‚οΈ Gitea Projekt-Dashboard -Gitea-Projektverwaltung mit Dashboard-Integration – zeigt alle Repos mit einem bestimmten Tag \ No newline at end of file +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)* \ No newline at end of file