docs: vollständige README mit Architektur, Tech-Stack und Tag-Konzept
This commit is contained in:
162
README.md
162
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)*
|
||||
Reference in New Issue
Block a user