Ai/gitpusher/PROJECT_STRUCTURE.md

Projektstruktur

Übersicht

/gitpusher/
│
├── 📄 README.md                    # Hauptdokumentation
├── 📄 INSTALL.md                   # Schnellstart-Installation
├── 📄 PROJECT_STRUCTURE.md         # Diese Datei
├── 🔒 .htaccess                    # Hauptsicherheitskonfiguration
├── 📝 .gitignore                   # Git-Ignore-Regeln
│
├── 📁 public/                      # Web-Root (Apache DocumentRoot)
│   ├── 🌐 index.php               # Dashboard (Frontend)
│   ├── 🔗 webhook.php             # Webhook-Endpoint für GitHub
│   │
│   ├── 📁 api/                    # REST API Endpunkte
│   │   ├── repos.php              # Repository-CRUD-Operationen
│   │   ├── sync.php               # Manueller Sync-Trigger
│   │   ├── rollback.php           # Rollback zu älterem Commit
│   │   └── log.php                # Log-Abfrage
│   │
│   ├── 📁 css/
│   │   └── style.css              # Komplettes Dashboard-Styling
│   │
│   └── 📁 js/
│       └── app.js                 # Frontend-Logik & AJAX
│
├── 📁 data/                        # Datenspeicher (NICHT web-zugänglich!)
│   ├── 🔒 .htaccess               # Zugriff komplett verweigern
│   ├── 📊 config.json             # Repository-Konfigurationen
│   ├── 📜 log.json                # Alle Log-Einträge
│   └── 🔐 secrets.json            # GitHub PAT & Webhook Secrets
│
└── 📁 src/                         # PHP Backend-Klassen
    ├── 🔒 .htaccess               # Zugriff komplett verweigern
    ├── ConfigManager.php          # JSON-Dateiverwaltung
    ├── Logger.php                 # Logging-System
    └── GitHandler.php             # Git-Operationen (clone, pull, revert)

📂 Detaillierte Beschreibung

/public/ - Web-Root

Apache DocumentRoot - Einziger Ordner, der über HTTP erreichbar ist.

index.php - Dashboard

• Haupt-Frontend der Anwendung
• Zeigt alle Repositories mit Status
• Statistiken (Anzahl Repos, Sync-Status, etc.)
• Log-Anzeige der letzten Ereignisse
• Modals für: Repository hinzufügen, Rollback, Webhook-Info

webhook.php - GitHub Webhook Endpoint

• Empfängt POST-Requests von GitHub
• Verifiziert Webhook-Signatur (HMAC SHA-256)
• Prüft, ob Push zum konfigurierten Branch gehört
• Triggert automatischen git pull
• Loggt alle Ereignisse

/api/ - REST API

repos.php

• GET: Liste aller Repositories oder einzelnes Repository
• POST: Neues Repository hinzufügen (+ initial clone)
• PUT: Repository-Einstellungen aktualisieren
• DELETE: Repository aus Config entfernen (optional: Dateien löschen)

sync.php

• POST: Manuellen Sync durchführen
• Führt git pull für angegebenes Repository aus
• Gibt Anzahl geänderter Dateien zurück

rollback.php

• GET: Liste der letzten Commits (für Rollback-Auswahl)
• POST: Rollback zu bestimmtem Commit durchführen
• Nutzt git revert (sicher, keine Commits gelöscht)

log.php

• GET: Log-Einträge abrufen
• Filter: Repository-ID, Log-Type, Limit, Offset
• Gibt Statistiken zurück (Erfolg/Fehler/Warnung)

/css/style.css

• Modernes, responsives Design
• CSS Custom Properties (CSS Variables)
• Mobile-First Ansatz
• Animationen für Toasts, Modals, Cards

/js/app.js

• Frontend-State-Management
• AJAX-Calls zu allen API-Endpunkten
• Modal-Handling
• Toast-Notifications
• Auto-Refresh (alle 30 Sekunden)

---

/data/ - Datenspeicher

Sicherheit: .htaccess verweigert jeden Web-Zugriff!

config.json

{
  "repositories": [
    {
      "id": "repo_uniqueid123",
      "name": "Meine Website",
      "repo_url": "https://github.com/user/repo.git",
      "branch": "main",
      "target_path": "/var/www/website",
      "auto_sync": true,
      "status": "synced",
      "created_at": "2025-12-06 10:00:00",
      "last_sync": "2025-12-06 14:30:00",
      "last_commit": "abc123def456..."
    }
  ]
}

log.json

{
  "entries": [
    {
      "id": "log_uniqueid456",
      "timestamp": "2025-12-06 14:30:00",
      "repo_id": "repo_uniqueid123",
      "type": "success",
      "message": "Pull completed successfully",
      "details": {
        "files_changed": 3,
        "old_commit": "abc123d",
        "new_commit": "def456a"
      }
    }
  ]
}

secrets.json

{
  "github_pat": "ghp_YourPersonalAccessTokenHere",
  "webhook_secrets": {
    "repo_uniqueid123": "generatedWebhookSecretHere"
  }
}

Berechtigungen: chmod 600 (nur Owner kann lesen/schreiben)

---

/src/ - Backend-Klassen

Sicherheit: .htaccess verweigert jeden Web-Zugriff!

ConfigManager.php

Verantwortlichkeiten:

• JSON-Dateien lesen/schreiben
• Repository-CRUD-Operationen
• Webhook-Secret-Verwaltung
• GitHub PAT verwalten

Wichtige Methoden:

getRepositories()           // Alle Repos
getRepository($id)          // Einzelnes Repo
addRepository($data)        // Neues Repo
updateRepository($id, $updates)  // Repo aktualisieren
deleteRepository($id)       // Repo löschen
getGitHubToken()           // PAT abrufen
setWebhookSecret($id, $secret)  // Webhook Secret speichern

Logger.php

Verantwortlichkeiten:

• Log-Einträge erstellen
• Logs nach Typ/Repo filtern
• Statistiken generieren
• Auto-Bereinigung (max. 1000 Einträge)

Wichtige Methoden:

success($repoId, $message, $details)  // ✅ Erfolg loggen
error($repoId, $message, $details)    // ❌ Fehler loggen
warning($repoId, $message, $details)  // ⚠️ Warnung loggen
info($repoId, $message, $details)     // ℹ️ Info loggen
getAll($limit, $offset)               // Alle Logs
getByRepository($repoId)              // Logs für Repo
getStats()                            // Statistiken

GitHandler.php

Verantwortlichkeiten:

• Git-Befehle ausführen
• Repository klonen
• Pull durchführen
• Revert zu älterem Commit
• Commit-Historie abrufen
• Merge-Konflikte erkennen

Wichtige Methoden:

cloneRepository($repoId, $url, $path, $branch)  // Initial clone
pull($repoId, $path, $branch)                   // git pull
revert($repoId, $path, $commitHash)            // git revert
getCurrentCommit($path)                         // Aktueller Commit
getCommitHistory($path, $limit)                 // Commit-Liste
getStatus($path)                                // git status
getRemoteBranches($url)                         // Verfügbare Branches

Sicherheit:

• Alle Shell-Befehle mit escapeshellarg() escaped
• GitHub PAT wird in URL eingebettet für Auth
• Fehlerbehandlung mit Try-Catch

---

🔐 Sicherheitskonzept

1. Zugriffskontrolle

Web-zugänglich: Nur /public/

Blockiert:

• /data/ (enthält Secrets & Konfiguration)
• /src/ (PHP-Klassen)
• Alle .json Dateien
• .git Verzeichnisse

2. Webhook-Sicherheit

• HMAC SHA-256 Signatur-Verifizierung
• Unique Secret pro Repository
• Timing-Safe Vergleich (hash_equals())

3. Datei-Berechtigungen

/gitpusher/                 755 (www-data:www-data)
/gitpusher/public/          755
/gitpusher/data/            755
/gitpusher/data/*.json      600 (nur Owner lesen/schreiben)
/gitpusher/src/             755

4. Input-Validierung

• Alle User-Inputs werden validiert
• JSON-Parsing mit Fehlerbehandlung
• Repository-URLs werden geprüft
• SQL-Injection nicht möglich (keine DB)
• XSS-Prevention durch escapeHtml() im Frontend

5. Git-Sicherheit

• Alle Git-Befehle laufen als www-data User
• Shell-Injection-Prevention durch escapeshellarg()
• GitHub PAT mit minimalen Berechtigungen (nur repo)

---

🔄 Datenfluss

Automatischer Sync (Webhook)

GitHub Push Event
       ↓
   webhook.php
       ↓
1. Payload empfangen
2. JSON dekodieren
3. Signature verifizieren (HMAC SHA-256)
4. Repository in Config finden
5. Branch prüfen
       ↓
   GitHandler::pull()
       ↓
1. Aktuellen Commit speichern
2. git pull ausführen
3. Auf Merge-Konflikte prüfen
4. Geänderte Dateien zählen
       ↓
   Logger::success/error()
       ↓
   ConfigManager::updateRepository()
       ↓
Status aktualisiert in config.json

Manueller Sync

User klickt "Sync"-Button
       ↓
JavaScript: syncRepository(repoId)
       ↓
AJAX POST → api/sync.php
       ↓
GitHandler::pull()
       ↓
Logger::log()
       ↓
Response → JavaScript
       ↓
Dashboard-Refresh

Repository hinzufügen

User füllt Formular aus
       ↓
JavaScript: addRepository(event)
       ↓
AJAX POST → api/repos.php
       ↓
1. Input validieren
2. ConfigManager::addRepository()
3. Webhook Secret generieren
4. GitHandler::cloneRepository()
       ↓
5. Logger::success()
6. Webhook-Info zurückgeben
       ↓
Modal mit Webhook-Daten anzeigen

---

📊 Abhängigkeiten

PHP-Klassen

webhook.php
├── ConfigManager
├── Logger
└── GitHandler
    └── Logger
    └── ConfigManager

api/repos.php
├── ConfigManager
├── Logger
└── GitHandler

api/sync.php
├── ConfigManager
├── Logger
└── GitHandler

api/rollback.php
├── ConfigManager
├── Logger
└── GitHandler

api/log.php
├── ConfigManager
└── Logger

Frontend

index.php (HTML)
├── css/style.css
└── js/app.js
    ├── Fetch API (AJAX)
    └── REST API Endpoints
        ├── api/repos.php
        ├── api/sync.php
        ├── api/rollback.php
        └── api/log.php

---

🧪 Test-Checklist

• Repository hinzufügen funktioniert
• Initial Clone erfolgreich
• Webhook empfängt Push-Events
• Signatur-Verifizierung funktioniert
• Manueller Sync funktioniert
• Merge-Konflikte werden erkannt
• Rollback erstellt Revert-Commit
• Logs werden korrekt geschrieben
• Dashboard zeigt Status korrekt
• Repository löschen funktioniert
• .htaccess blockiert /data/ Zugriff
• .htaccess blockiert /src/ Zugriff

---

📚 Erweiterungsmöglichkeiten

Mögliche Features

1. Multi-User Support

   • User-Login
   • Rollen-System (Admin, User)
   • Repository-Berechtigungen pro User

2. E-Mail Benachrichtigungen

   • Bei erfolgreicher Sync
   • Bei Fehlern/Konflikten
   • Tägliche Zusammenfassung

3. Deployment Scripts

   • Post-Sync Hooks (z.B. npm install, composer install)
   • Custom Shell-Befehle
   • Build-Prozesse

4. Advanced Git Features

   • Submodules Support
   • Tag/Release Tracking
   • Multi-Branch Sync

5. Monitoring & Alerts

   • Prometheus Metrics
   • Grafana Dashboard
   • Slack/Discord Webhooks

6. API Authentication

   • API Keys
   • JWT Tokens
   • Rate Limiting

7. Backup System

   • Automatische Backups vor Sync
   • Snapshot-Verwaltung
   • Restore-Funktion

---

Version: 1.0.0 Erstellt: 2025-12-06 Autor: Claude Code