Update

.gitignore

@@ -34,4 +34,7 @@ dist-ssr
 *.ntvs*
 *.njsproj
 *.sln
-*.sw?
+*.sw?
+/site/
+__pycache__/
+*.pyc

README.md

@@ -3,7 +3,7 @@
 # 📦 StackPulse ![Release](https://img.shields.io/badge/release-v0.5-blue.svg) 
 
 **StackPulse** ist eine kleine Web-App, die über die Portainer-API deine Docker-Stacks verwaltet und aktualisiert.  
-Aktuell funktioniert StackPulse nur mit der Business-Edition von Portainer. Die Communitiy-Edition wird in einem späteren Release implementiert!
+StackPulse funktioniert nur mit der Business-Edition von Portainer. Die Communitiy-Edition wird nicht unterstützt!
 Sie besteht aus einem **Backend (Node.js/Express)** und einem **Frontend (React/Tailwind)**.  
 
 Ziel:  
@@ -124,9 +124,8 @@ Ziel:
 - Notifications (z. B. via Webhooks oder Mail)  
 - Monitoring (Status, CPU/RAM)  
 - Verbesserte UI/UX  
-- Erweiterte Filterungen udn Sortierungen
+- Erweiterte Filterungen und Sortierungen
 - Multi-Server Verwaltung
-- Integration Community Edition
 </details>
 
 ---

backend/db/dbs

@@ -69,6 +69,21 @@ CREATE TABLE user_group_memberships (
   FOREIGN KEY (group_id) REFERENCES user_groups(id) ON DELETE CASCADE
 );
 
+CREATE TABLE user_server_assignments (
+  user_id INTEGER NOT NULL,
+  server_id INTEGER NOT NULL,
+  group_id INTEGER,
+  use_global_group INTEGER NOT NULL DEFAULT 0,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (user_id, server_id),
+  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
+  FOREIGN KEY (server_id) REFERENCES servers(id) ON DELETE CASCADE,
+  FOREIGN KEY (group_id) REFERENCES user_groups(id) ON DELETE SET NULL
+);
+CREATE INDEX idx_user_server_assignments_user ON user_server_assignments (user_id);
+CREATE INDEX idx_user_server_assignments_server ON user_server_assignments (server_id);
+
 CREATE TABLE permissions (
   id INTEGER PRIMARY KEY AUTOINCREMENT,
   key TEXT NOT NULL UNIQUE,
@@ -100,13 +115,15 @@ CREATE TABLE permission_sections (
 CREATE TABLE permission_groups (
   id INTEGER PRIMARY KEY AUTOINCREMENT,
   section_id INTEGER NOT NULL,
+  parent_group_id INTEGER,
   key TEXT NOT NULL,
   title TEXT NOT NULL,
   sort_order INTEGER NOT NULL DEFAULT 0,
   created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
   updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
   UNIQUE(section_id, key),
-  FOREIGN KEY (section_id) REFERENCES permission_sections(id) ON DELETE CASCADE
+  FOREIGN KEY (section_id) REFERENCES permission_sections(id) ON DELETE CASCADE,
+  FOREIGN KEY (parent_group_id) REFERENCES permission_groups(id) ON DELETE CASCADE
 );
 
 CREATE TABLE permission_items (
@@ -118,6 +135,7 @@ CREATE TABLE permission_items (
   sort_order INTEGER NOT NULL DEFAULT 0,
   default_level TEXT NOT NULL,
   available_levels TEXT NOT NULL,
+  is_global_scope INTEGER NOT NULL DEFAULT 1,
   is_required INTEGER NOT NULL DEFAULT 0,
   created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
   updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
@@ -185,6 +203,33 @@ CREATE TABLE server_api_keys (
   FOREIGN KEY (server_id) REFERENCES servers(id) ON DELETE CASCADE
 );
 
+CREATE TABLE server_ssh_configs (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  server_id INTEGER NOT NULL UNIQUE,
+  host TEXT NOT NULL,
+  port INTEGER NOT NULL DEFAULT 22,
+  username TEXT NOT NULL,
+  password_cipher TEXT,
+  password_iv TEXT,
+  password_tag TEXT,
+  extra_args TEXT,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (server_id) REFERENCES servers(id) ON DELETE CASCADE
+);
+CREATE INDEX idx_server_ssh_configs_server ON server_ssh_configs (server_id);
+
+CREATE TABLE server_update_scripts (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  server_id INTEGER NOT NULL UNIQUE,
+  custom_script TEXT,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (server_id) REFERENCES servers(id) ON DELETE CASCADE
+);
+
+CREATE INDEX idx_server_update_scripts_server ON server_update_scripts (server_id);
+
 CREATE TABLE user_settings (
   user_id INTEGER NOT NULL,
   setting_key TEXT NOT NULL,

backend/db/schemaEnsure.js

@@ -15,6 +15,7 @@ const PERMISSION_BLUEPRINT = [
         key: 'stacks-redeploy-single',
         label: 'Redeploy einzeln',
         sortOrder: 0,
+        global: false,
         defaultLevel: 'none',
         levels: ['full', 'none'],
         dependencies: []
@@ -23,6 +24,7 @@ const PERMISSION_BLUEPRINT = [
         key: 'stacks-redeploy-selection',
         label: 'Redeploy Auswahl',
         sortOrder: 1,
+        global: false,
         defaultLevel: 'none',
         levels: ['full', 'none'],
         dependencies: []
@@ -31,6 +33,7 @@ const PERMISSION_BLUEPRINT = [
         key: 'stacks-redeploy-all',
         label: 'Redeploy Alle',
         sortOrder: 2,
+        global: false,
         defaultLevel: 'none',
         levels: ['full', 'none'],
         dependencies: []
@@ -47,6 +50,7 @@ const PERMISSION_BLUEPRINT = [
         key: 'logs-access',
         label: 'Bereich & Navigation',
         sortOrder: 0,
+        global: true,
         defaultLevel: 'none',
         levels: ['full', 'none'],
         isRequired: 1,
@@ -56,6 +60,7 @@ const PERMISSION_BLUEPRINT = [
         key: 'logs-export',
         label: 'Logs Exportieren',
         sortOrder: 1,
+        global: true,
         defaultLevel: 'none',
         levels: ['full', 'none'],
         dependencies: [
@@ -66,6 +71,7 @@ const PERMISSION_BLUEPRINT = [
         key: 'logs-delete',
         label: 'Logs löschen',
         sortOrder: 2,
+        global: true,
         defaultLevel: 'none',
         levels: ['full', 'none'],
         dependencies: [
@@ -84,6 +90,7 @@ const PERMISSION_BLUEPRINT = [
         key: 'users-access',
         label: 'Bereich & Navigation',
         sortOrder: 0,
+        global: true,
         defaultLevel: 'none',
         levels: ['full', 'none'],
         isRequired: 1,
@@ -93,6 +100,7 @@ const PERMISSION_BLUEPRINT = [
         key: 'users-edit',
         label: 'Benutzer bearbeiten',
         sortOrder: 1,
+        global: true,
         defaultLevel: 'read',
         levels: ['full', 'read'],
         dependencies: [
@@ -103,6 +111,7 @@ const PERMISSION_BLUEPRINT = [
         key: 'users-delete',
         label: 'Benutzer löschen',
         sortOrder: 2,
+        global: true,
         defaultLevel: 'none',
         levels: ['full', 'none'],
         dependencies: [
@@ -113,6 +122,7 @@ const PERMISSION_BLUEPRINT = [
         key: 'users-security-phrase',
         label: 'Sicherheitsschlüssel',
         sortOrder: 3,
+        global: true,
         defaultLevel: 'none',
         levels: ['full', 'none'],
         dependencies: [
@@ -131,6 +141,7 @@ const PERMISSION_BLUEPRINT = [
         key: 'user-groups-access',
         label: 'Bereich & Navigation',
         sortOrder: 0,
+        global: true,
         defaultLevel: 'none',
         levels: ['full', 'none'],
         isRequired: 1,
@@ -140,6 +151,7 @@ const PERMISSION_BLUEPRINT = [
         key: 'user-groups-edit',
         label: 'Benutzergruppen bearbeiten',
         sortOrder: 1,
+        global: true,
         defaultLevel: 'read',
         levels: ['full', 'read'],
         dependencies: [
@@ -150,6 +162,7 @@ const PERMISSION_BLUEPRINT = [
         key: 'user-groups-delete',
         label: 'Benutzergruppen löschen',
         sortOrder: 2,
+        global: true,
         defaultLevel: 'none',
         levels: ['full', 'none'],
         dependencies: [
@@ -168,6 +181,7 @@ const PERMISSION_BLUEPRINT = [
         key: 'maintenance-access',
         label: 'Bereich & Navigation',
         sortOrder: 0,
+        global: true,
         defaultLevel: 'none',
         levels: ['full', 'none'],
         isRequired: 1,
@@ -184,21 +198,88 @@ const PERMISSION_BLUEPRINT = [
             key: 'maintenance-server-manage',
             label: 'Server-Sektion',
             sortOrder: 0,
+            global: true,
             defaultLevel: 'none',
-            levels: ['full', 'read', 'none'],
+            levels: ['full', 'none'],
             dependencies: [
               { dependsOnKey: 'maintenance-access', requiredLevel: '!=none' }
             ]
           },
+          {
+            key: 'maintenance-server-edit',
+            label: 'Server bearbeiten',
+            sortOrder: 1,
+            global: false,
+            defaultLevel: 'none',
+            levels: ['full', 'read', 'none'],
+            dependencies: [
+              { dependsOnKey: 'maintenance-access', requiredLevel: '!=none' },
+              { dependsOnKey: 'maintenance-server-manage', requiredLevel: '!=none' }
+            ]
+          },
           {
             key: 'maintenance-server-delete',
             label: 'Server löschen',
-            sortOrder: 1,
+            sortOrder: 2,
+            global: false,
             defaultLevel: 'none',
             levels: ['full', 'none'],
             dependencies: [
               { dependsOnKey: 'maintenance-access', requiredLevel: '!=none' },
-              { dependsOnKey: 'maintenance-server-manage', requiredLevel: '!=none' }
+              { dependsOnKey: 'maintenance-server-manage', requiredLevel: 'full' },
+              { dependsOnKey: 'maintenance-server-edit', requiredLevel: '=full' }
+            ]
+          }
+        ],
+        groups: [
+          {
+            key: 'maintenance-portainer-group',
+            title: 'Portainer',
+            sortOrder: 1,
+            items: [
+              {
+                key: 'maintenance-ssh-update',
+                label: 'SSH/Update-Skript',
+                sortOrder: 0,
+                global: false,
+                defaultLevel: 'none',
+                levels: ['full', 'read', 'none'],
+                dependencies: [
+                  { dependsOnKey: 'maintenance-access', requiredLevel: '!=none' },
+                  { dependsOnKey: 'maintenance-server-edit', requiredLevel: '!=none' }
+                ]
+              },
+              {
+                key: 'maintenance-update',
+                label: 'Update durchführen',
+                sortOrder: 1,
+                global: false,
+                defaultLevel: 'none',
+                levels: ['full', 'none'],
+                dependencies: [
+                  { dependsOnKey: 'maintenance-access', requiredLevel: '!=none' },
+                  { dependsOnKey: 'maintenance-server-edit', requiredLevel: '!=none' }
+                ]
+              }
+            ]
+          },
+          {
+            key: 'maintenance-duplicates-group',
+            title: 'Doppelte Stacks',
+            sortOrder: 2,
+            items: [
+              {
+                key: 'maintenance-duplicates',
+                label: 'Doppelte Stacks',
+                sortOrder: 0,
+                global: false,
+                defaultLevel: 'none',
+                levels: ['full', 'read', 'none'],
+                dependencies: [
+                  { dependsOnKey: 'maintenance-access', requiredLevel: '!=none' },
+                  { dependsOnKey: 'maintenance-server-edit', requiredLevel: '!=none' }
+                ]
+              }
             ]
           }
         ]
@@ -212,6 +293,7 @@ const PERMISSION_BLUEPRINT = [
             key: 'maintenance-superuser-delete',
             label: 'Superuser löschen',
             sortOrder: 0,
+            global: true,
             defaultLevel: 'none',
             levels: ['full', 'none'],
             dependencies: [
@@ -221,58 +303,20 @@ const PERMISSION_BLUEPRINT = [
         ]
       },
       {
-        key: 'maintenance-portainer-group',
-        title: 'Portainer',
+        key: 'maintenance-mtls-group',
+        title: 'mTLS',
         sortOrder: 2,
         items: [
           {
-            key: 'maintenance-portainer',
-            label: 'Portainer-Sektion',
+            key: 'maintenance-mtls',
+            label: 'mTLS Sektion',
             sortOrder: 0,
+            global: true,
             defaultLevel: 'none',
             levels: ['full', 'none'],
             dependencies: [
               { dependsOnKey: 'maintenance-access', requiredLevel: '!=none' }
             ]
-          },
-          {
-            key: 'maintenance-ssh-update',
-            label: 'SSH/Update-Skript',
-            sortOrder: 1,
-            defaultLevel: 'none',
-            levels: ['full', 'read', 'none'],
-            dependencies: [
-              { dependsOnKey: 'maintenance-access', requiredLevel: '!=none' },
-              { dependsOnKey: 'maintenance-portainer', requiredLevel: '!=none' }
-            ]
-          },
-          {
-            key: 'maintenance-update',
-            label: 'Update durchführen',
-            sortOrder: 2,
-            defaultLevel: 'none',
-            levels: ['full', 'none'],
-            dependencies: [
-              { dependsOnKey: 'maintenance-access', requiredLevel: '!=none' },
-              { dependsOnKey: 'maintenance-portainer', requiredLevel: '!=none' }
-            ]
-          }
-        ]
-      },
-      {
-        key: 'maintenance-duplicates-group',
-        title: 'Doppelte Stacks',
-        sortOrder: 3,
-        items: [
-          {
-            key: 'maintenance-duplicates',
-            label: 'Doppelte Stacks',
-            sortOrder: 0,
-            defaultLevel: 'none',
-            levels: ['full', 'read', 'none'],
-            dependencies: [
-              { dependsOnKey: 'maintenance-access', requiredLevel: '!=none' }
-            ]
           }
         ]
       }
@@ -368,7 +412,13 @@ const tableExists = (tableName) => {
 };
 
 const dropDeprecatedArtifacts = () => {
-  const deprecatedTables = ['user_endpoint_permission_overrides', 'endpoints'];
+  const deprecatedTables = [
+    'user_endpoint_permission_overrides',
+    'endpoints',
+    'server_agents',
+    'agent_tls_material',
+    'agent_bootstrap_tokens'
+  ];
   deprecatedTables.forEach((table) => {
     if (tableExists(table)) {
       db.exec(`DROP TABLE IF EXISTS ${table}`);
@@ -440,20 +490,24 @@ const ensurePermissionSeeds = () => {
   `);
 
   const selectGroup = db.prepare(`
-    SELECT id, title, sort_order
+    SELECT id, title, sort_order, parent_group_id
     FROM permission_groups
     WHERE section_id = ? AND key = ?
     LIMIT 1
   `);
   const insertGroup = db.prepare(`
-    INSERT INTO permission_groups (section_id, key, title, sort_order, created_at, updated_at)
-    VALUES (?, ?, ?, ?, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
+    INSERT INTO permission_groups (section_id, parent_group_id, key, title, sort_order, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
   `);
   const updateGroup = db.prepare(`
     UPDATE permission_groups
-    SET title = ?, sort_order = ?, updated_at = CURRENT_TIMESTAMP
+    SET title = ?, sort_order = ?, parent_group_id = ?, updated_at = CURRENT_TIMESTAMP
     WHERE id = ?
   `);
+  const deleteUnusedGroups = db.prepare(`
+    DELETE FROM permission_groups
+    WHERE key NOT IN (SELECT value FROM json_each(?))
+  `);
 
   const selectItem = db.prepare(`
     SELECT
@@ -464,6 +518,7 @@ const ensurePermissionSeeds = () => {
       sort_order,
       default_level,
       available_levels,
+      is_global_scope,
       is_required
     FROM permission_items
     WHERE key = ?
@@ -478,11 +533,12 @@ const ensurePermissionSeeds = () => {
       sort_order,
       default_level,
       available_levels,
+      is_global_scope,
       is_required,
       created_at,
       updated_at
     ) VALUES (
-      ?, ?, ?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP
+      ?, ?, ?, ?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP
     )
   `);
   const updateItem = db.prepare(`
@@ -494,10 +550,24 @@ const ensurePermissionSeeds = () => {
       sort_order = ?,
       default_level = ?,
       available_levels = ?,
+      is_global_scope = ?,
       is_required = ?,
       updated_at = CURRENT_TIMESTAMP
     WHERE id = ?
   `);
+  const deleteUnusedItems = db.prepare(`
+    DELETE FROM permission_items
+    WHERE key NOT IN (SELECT value FROM json_each(?))
+  `);
+  const deleteOrphanDependencies = db.prepare(`
+    DELETE FROM permission_dependencies
+    WHERE permission_id NOT IN (SELECT id FROM permission_items)
+       OR depends_on_permission_id NOT IN (SELECT id FROM permission_items)
+  `);
+  const deleteOrphanPermissionValues = db.prepare(`
+    DELETE FROM group_permission_values
+    WHERE permission_id NOT IN (SELECT id FROM permission_items)
+  `);
 
   const selectDependency = db.prepare(`
     SELECT id, required_level
@@ -523,6 +593,100 @@ const ensurePermissionSeeds = () => {
   `);
 
   const itemKeyToId = new Map();
+  const dependencyQueue = [];
+  const itemKeys = new Set();
+  const groupKeys = new Set();
+
+  const upsertItem = ({ item, sectionId, groupId = null, sortOrder }) => {
+    const existingItem = selectItem.get(item.key);
+    const itemSortOrder = typeof sortOrder === 'number' ? sortOrder : 0;
+    const levelOptions = Array.isArray(item.levels) && item.levels.length
+      ? item.levels
+      : ['full', 'read', 'none'];
+    const availableLevels = JSON.stringify(levelOptions);
+    const isRequired = item.isRequired ? 1 : 0;
+    const isGlobal = item.global === false ? 0 : 1;
+    const label = item.label || item.key || '';
+
+    if (!existingItem) {
+      const result = insertItem.run(
+        sectionId,
+        groupId,
+        item.key,
+        label,
+        itemSortOrder,
+        item.defaultLevel || 'none',
+        availableLevels,
+        isGlobal,
+        isRequired
+      );
+      itemKeyToId.set(item.key, Number(result.lastInsertRowid));
+      console.log(`ℹ️ Berechtigung ${item.key} ${groupId ? `in Gruppe ${groupId}` : ''} angelegt`);
+    } else {
+      const hasChanges =
+        existingItem.section_id !== sectionId ||
+        existingItem.group_id !== groupId ||
+        existingItem.label !== label ||
+        (existingItem.sort_order ?? itemSortOrder) !== itemSortOrder ||
+        existingItem.default_level !== (item.defaultLevel || 'none') ||
+        existingItem.available_levels !== availableLevels ||
+        Number(existingItem.is_global_scope ?? 1) !== isGlobal ||
+        Number(existingItem.is_required) !== isRequired;
+      updateItem.run(
+        sectionId,
+        groupId,
+        label,
+        itemSortOrder,
+        item.defaultLevel || 'none',
+        availableLevels,
+        isGlobal,
+        isRequired,
+        existingItem.id
+      );
+      itemKeyToId.set(item.key, existingItem.id);
+      if (hasChanges) {
+        console.log(`ℹ️ Berechtigung ${item.key} aktualisiert`);
+      }
+    }
+
+    itemKeys.add(item.key);
+    dependencyQueue.push({ itemKey: item.key, dependencies: item.dependencies || [] });
+  };
+
+  const processGroups = (groups, sectionId, parentGroupId = null) => {
+    const list = Array.isArray(groups) ? groups : [];
+    list.forEach((group, groupIdx) => {
+      const sortOrder = typeof group.sortOrder === 'number' ? group.sortOrder : groupIdx;
+      const existingGroup = selectGroup.get(sectionId, group.key);
+      let groupId;
+      if (!existingGroup) {
+        const result = insertGroup.run(sectionId, parentGroupId, group.key, group.title, sortOrder);
+        groupId = Number(result.lastInsertRowid);
+        console.log(`ℹ️ Berechtigungs-Gruppe ${group.key} in Sektion ${sectionId} angelegt`);
+      } else {
+        const hasGroupChanges =
+          existingGroup.title !== group.title ||
+          (existingGroup.sort_order ?? sortOrder) !== sortOrder ||
+          existingGroup.parent_group_id !== parentGroupId;
+        updateGroup.run(group.title, sortOrder, parentGroupId, existingGroup.id);
+        groupId = existingGroup.id;
+        if (hasGroupChanges) {
+          console.log(`ℹ️ Berechtigungs-Gruppe ${group.key} in Sektion ${sectionId} aktualisiert`);
+        }
+      }
+
+      groupKeys.add(group.key);
+
+      const groupItems = Array.isArray(group.items) ? group.items : [];
+      groupItems.forEach((item, itemIdx) => {
+        upsertItem({ item, sectionId, groupId, sortOrder: typeof item.sortOrder === 'number' ? item.sortOrder : itemIdx });
+      });
+
+      if (group.groups) {
+        processGroups(group.groups, sectionId, groupId);
+      }
+    });
+  };
 
   PERMISSION_BLUEPRINT.forEach((section, sectionIndex) => {
     const existingSection = selectSection.get(section.key);
@@ -555,171 +719,41 @@ const ensurePermissionSeeds = () => {
 
     const sectionItems = Array.isArray(section.items) ? section.items : [];
     sectionItems.forEach((item, itemIdx) => {
-      const existingItem = selectItem.get(item.key);
-      const sortOrder = typeof item.sortOrder === 'number' ? item.sortOrder : itemIdx;
-      const levelOptions = Array.isArray(item.levels) && item.levels.length
-        ? item.levels
-        : ['full', 'read', 'none'];
-      const availableLevels = JSON.stringify(levelOptions);
-      const isRequired = item.isRequired ? 1 : 0;
-      if (!existingItem) {
-        const result = insertItem.run(
-          sectionId,
-          null,
-          item.key,
-          item.label,
-          sortOrder,
-          item.defaultLevel || 'none',
-          availableLevels,
-          isRequired
-        );
-        itemKeyToId.set(item.key, Number(result.lastInsertRowid));
-        console.log(`ℹ️ Berechtigung ${item.key} angelegt`);
-      } else {
-        const hasChanges =
-          existingItem.section_id !== sectionId ||
-          existingItem.group_id !== null ||
-          existingItem.label !== item.label ||
-          (existingItem.sort_order ?? sortOrder) !== sortOrder ||
-          existingItem.default_level !== (item.defaultLevel || 'none') ||
-          existingItem.available_levels !== availableLevels ||
-          Number(existingItem.is_required) !== isRequired;
-        updateItem.run(
-          sectionId,
-          null,
-          item.label,
-          sortOrder,
-          item.defaultLevel || 'none',
-          availableLevels,
-          isRequired,
-          existingItem.id
-        );
-        itemKeyToId.set(item.key, existingItem.id);
-        if (hasChanges) {
-          console.log(`ℹ️ Berechtigung ${item.key} aktualisiert`);
-        }
-      }
+      upsertItem({ item, sectionId, groupId: null, sortOrder: typeof item.sortOrder === 'number' ? item.sortOrder : itemIdx });
     });
 
-    const sectionGroups = Array.isArray(section.groups) ? section.groups : [];
-    sectionGroups.forEach((group, groupIdx) => {
-      const existingGroup = selectGroup.get(sectionId, group.key);
-      const sortOrder = typeof group.sortOrder === 'number' ? group.sortOrder : groupIdx;
-      let groupId;
-      if (!existingGroup) {
-        const result = insertGroup.run(sectionId, group.key, group.title, sortOrder);
-        groupId = Number(result.lastInsertRowid);
-        console.log(`ℹ️ Berechtigungs-Gruppe ${group.key} in Sektion ${section.key} angelegt`);
-      } else {
-        const hasGroupChanges =
-          existingGroup.title !== group.title ||
-          (existingGroup.sort_order ?? sortOrder) !== sortOrder;
-        updateGroup.run(group.title, sortOrder, existingGroup.id);
-        groupId = existingGroup.id;
-        if (hasGroupChanges) {
-          console.log(`ℹ️ Berechtigungs-Gruppe ${group.key} in Sektion ${section.key} aktualisiert`);
-        }
+    processGroups(section.groups, sectionId, null);
+  });
+
+  dependencyQueue.forEach(({ itemKey, dependencies }) => {
+    const permissionId = itemKeyToId.get(itemKey);
+    if (!permissionId) return;
+    dependencies.forEach((dependency) => {
+      const dependsId = itemKeyToId.get(dependency.dependsOnKey);
+      if (!dependsId) return;
+      const existing = selectDependency.get(permissionId, dependsId);
+      const requiredLevel = dependency.requiredLevel ?? null;
+      if (!existing) {
+        insertDependency.run(permissionId, dependsId, requiredLevel);
+        console.log(`ℹ️ Abhängigkeit ${itemKey} -> ${dependency.dependsOnKey} angelegt`);
+      } else if (existing.required_level !== requiredLevel) {
+        updateDependency.run(requiredLevel, existing.id);
+        console.log(`ℹ️ Abhängigkeit ${itemKey} -> ${dependency.dependsOnKey} aktualisiert`);
       }
-      const groupItems = Array.isArray(group.items) ? group.items : [];
-      groupItems.forEach((item, itemIdx) => {
-        const existingItem = selectItem.get(item.key);
-        const itemSortOrder = typeof item.sortOrder === 'number' ? item.sortOrder : itemIdx;
-        const levelOptions = Array.isArray(item.levels) && item.levels.length
-          ? item.levels
-          : ['full', 'read', 'none'];
-        const availableLevels = JSON.stringify(levelOptions);
-        const isRequired = item.isRequired ? 1 : 0;
-        if (!existingItem) {
-          const result = insertItem.run(
-            sectionId,
-            groupId,
-            item.key,
-            item.label,
-            itemSortOrder,
-            item.defaultLevel || 'none',
-            availableLevels,
-            isRequired
-          );
-          itemKeyToId.set(item.key, Number(result.lastInsertRowid));
-           console.log(`ℹ️ Berechtigung ${item.key} in Gruppe ${group.key} angelegt`);
-        } else {
-          const hasChanges =
-            existingItem.section_id !== sectionId ||
-            existingItem.group_id !== groupId ||
-            existingItem.label !== item.label ||
-            (existingItem.sort_order ?? itemSortOrder) !== itemSortOrder ||
-            existingItem.default_level !== (item.defaultLevel || 'none') ||
-            existingItem.available_levels !== availableLevels ||
-            Number(existingItem.is_required) !== isRequired;
-          updateItem.run(
-            sectionId,
-            groupId,
-            item.label,
-            itemSortOrder,
-            item.defaultLevel || 'none',
-            availableLevels,
-            isRequired,
-            existingItem.id
-          );
-          itemKeyToId.set(item.key, existingItem.id);
-          if (hasChanges) {
-            console.log(`ℹ️ Berechtigung ${item.key} in Gruppe ${group.key} aktualisiert`);
-          }
-        }
-      });
     });
   });
 
-  PERMISSION_BLUEPRINT.forEach((section) => {
-    const sectionItems = Array.isArray(section.items) ? section.items : [];
-    sectionItems.forEach((item) => {
-      const permissionId = itemKeyToId.get(item.key);
-      if (!permissionId) return;
-      (item.dependencies || []).forEach((dependency) => {
-        const dependsId = itemKeyToId.get(dependency.dependsOnKey);
-        if (!dependsId) return;
-        const existing = selectDependency.get(permissionId, dependsId);
-        const requiredLevel = dependency.requiredLevel ?? null;
-        if (!existing) {
-          insertDependency.run(permissionId, dependsId, requiredLevel);
-          console.log(
-            `ℹ️ Abhängigkeit ${item.key} -> ${dependency.dependsOnKey} angelegt`
-          );
-        } else if (existing.required_level !== requiredLevel) {
-          updateDependency.run(requiredLevel, existing.id);
-          console.log(
-            `ℹ️ Abhängigkeit ${item.key} -> ${dependency.dependsOnKey} aktualisiert`
-          );
-        }
-      });
-    });
-
-    const sectionGroups = Array.isArray(section.groups) ? section.groups : [];
-    sectionGroups.forEach((group) => {
-      const groupItems = Array.isArray(group.items) ? group.items : [];
-      groupItems.forEach((item) => {
-        const permissionId = itemKeyToId.get(item.key);
-        if (!permissionId) return;
-        (item.dependencies || []).forEach((dependency) => {
-          const dependsId = itemKeyToId.get(dependency.dependsOnKey);
-          if (!dependsId) return;
-          const requiredLevel = dependency.requiredLevel ?? null;
-          const existing = selectDependency.get(permissionId, dependsId);
-        if (!existing) {
-          insertDependency.run(permissionId, dependsId, requiredLevel);
-          console.log(
-            `ℹ️ Abhängigkeit ${item.key} -> ${dependency.dependsOnKey} angelegt`
-          );
-        } else if (existing.required_level !== requiredLevel) {
-          updateDependency.run(requiredLevel, existing.id);
-          console.log(
-            `ℹ️ Abhängigkeit ${item.key} -> ${dependency.dependsOnKey} aktualisiert`
-          );
-        }
-      });
-    });
-    });
-  });
+  // Cleanup obsolete entries
+  if (itemKeys.size > 0) {
+    const itemKeyJson = JSON.stringify(Array.from(itemKeys));
+    deleteOrphanDependencies.run();
+    deleteOrphanPermissionValues.run();
+    deleteUnusedItems.run(itemKeyJson);
+  }
+  if (groupKeys.size > 0) {
+    const groupKeyJson = JSON.stringify(Array.from(groupKeys));
+    deleteUnusedGroups.run(groupKeyJson);
+  }
 };
 
 export const ensureDatabaseSchema = () => {

backend/permissions/index.js

@@ -13,7 +13,7 @@ const selectSections = db.prepare(`
 `);
 
 const selectGroups = db.prepare(`
-  SELECT id, section_id, key, title, sort_order
+  SELECT id, section_id, parent_group_id, key, title, sort_order
   FROM permission_groups
   ORDER BY section_id ASC, sort_order ASC, id ASC
 `);
@@ -28,6 +28,7 @@ const selectItems = db.prepare(`
     sort_order,
     default_level,
     available_levels,
+    is_global_scope,
     is_required
   FROM permission_items
   ORDER BY section_id ASC, COALESCE(group_id, 0) ASC, sort_order ASC, id ASC
@@ -39,7 +40,7 @@ const selectDependencies = db.prepare(`
 `);
 
 const selectPermissionItemsForMap = db.prepare(`
-  SELECT id, key, available_levels, default_level
+  SELECT id, key, available_levels, default_level, is_global_scope
   FROM permission_items
 `);
 
@@ -81,6 +82,8 @@ const getLevelPriority = (level) => {
 };
 
 let cachedPermissionItems = null;
+let cachedServerScopedKeys = null;
+let cachedScopeByKey = null;
 
 const getPermissionItems = () => {
   if (!cachedPermissionItems) {
@@ -91,6 +94,24 @@ const getPermissionItems = () => {
 
 const resetPermissionItemsCache = () => {
   cachedPermissionItems = null;
+  cachedServerScopedKeys = null;
+  cachedScopeByKey = null;
+};
+
+const getScopeCache = () => {
+  if (!cachedScopeByKey || !cachedServerScopedKeys) {
+    const items = getPermissionItems();
+    cachedScopeByKey = new Map();
+    cachedServerScopedKeys = new Set();
+    items.forEach((item) => {
+      const isGlobal = item.is_global_scope !== 0;
+      cachedScopeByKey.set(item.key, { isGlobal });
+      if (!isGlobal) {
+        cachedServerScopedKeys.add(item.key);
+      }
+    });
+  }
+  return { scopeByKey: cachedScopeByKey, serverScopedKeys: cachedServerScopedKeys };
 };
 
 export function getPermissionStructure() {
@@ -109,10 +130,23 @@ export function getPermissionStructure() {
   });
 
   const groupsBySectionId = new Map();
-  groups.forEach((group) => {
-    const list = groupsBySectionId.get(group.section_id) || [];
-    list.push(group);
-    groupsBySectionId.set(group.section_id, list);
+  const groupsByParentId = new Map();
+  const sortedGroups = [...groups].sort((a, b) => {
+    const sortDiff = (a.sort_order ?? 0) - (b.sort_order ?? 0);
+    if (sortDiff !== 0) return sortDiff;
+    return a.id - b.id;
+  });
+
+  sortedGroups.forEach((group) => {
+    if (group.parent_group_id) {
+      const list = groupsByParentId.get(group.parent_group_id) || [];
+      list.push(group);
+      groupsByParentId.set(group.parent_group_id, list);
+    } else {
+      const list = groupsBySectionId.get(group.section_id) || [];
+      list.push(group);
+      groupsBySectionId.set(group.section_id, list);
+    }
   });
 
   const itemsBySectionId = new Map();
@@ -154,18 +188,26 @@ export function getPermissionStructure() {
       defaultLevel: item.default_level || 'none',
       availableLevels,
       isRequired: Boolean(item.is_required),
+      isGlobal: item.is_global_scope !== 0,
       dependencies: formattedDependencies
     };
   };
 
+  const buildGroupTree = (group) => {
+    const children = groupsByParentId.get(group.id) || [];
+    return {
+      key: group.key,
+      title: group.title,
+      sortOrder: group.sort_order ?? 0,
+      items: (itemsByGroupId.get(group.id) || []).map(formatItem),
+      groups: children.map(buildGroupTree)
+    };
+  };
+
   const formattedSections = sections.map((section) => {
     const sectionItems = (itemsBySectionId.get(section.id) || []).map(formatItem);
-    const sectionGroups = (groupsBySectionId.get(section.id) || []).map((group) => ({
-      key: group.key,
-      title: group.title,
-      sortOrder: group.sort_order ?? 0,
-      items: (itemsByGroupId.get(group.id) || []).map(formatItem)
-    }));
+    const rootGroups = groupsBySectionId.get(section.id) || [];
+    const sectionGroups = rootGroups.map(buildGroupTree);
 
     return {
       key: section.key,
@@ -267,14 +309,27 @@ export function saveGroupPermissionValues(groupId, values = {}) {
   };
 
   const serverManageLevel = getSubmittedLevel('maintenance-server-manage');
+  const serverEditLevel = getSubmittedLevel('maintenance-server-edit');
   const serverDeleteLevel = getSubmittedLevel('maintenance-server-delete');
 
-  if (getLevelPriority(serverDeleteLevel) >= getLevelPriority('full') &&
-    getLevelPriority(serverManageLevel) < getLevelPriority('full')) {
-    const error = new Error('PERMISSION_DEPENDENCY_LEVEL');
-    error.code = 'PERMISSION_DEPENDENCY_LEVEL';
-    error.permissionKey = 'maintenance-server-delete';
-    throw error;
+  // Enforce dependency: "server löschen" darf maximal so hoch sein wie manage/edit.
+  const deletePriority = getLevelPriority(serverDeleteLevel);
+  const allowedDeletePriority = Math.min(
+    getLevelPriority(serverManageLevel),
+    getLevelPriority(serverEditLevel)
+  );
+  if (deletePriority > allowedDeletePriority) {
+    const allowedLevelEntry = Object.entries(LEVEL_PRIORITY).find(([, priority]) => priority === allowedDeletePriority);
+    const allowedLevel = allowedLevelEntry ? allowedLevelEntry[0] : 'none';
+    const deleteEntry = normalizedEntries.find((entry) => entry.item.key === 'maintenance-server-delete');
+    if (deleteEntry) {
+      deleteEntry.level = allowedLevel;
+    } else {
+      normalizedEntries.push({
+        item: itemMap.get('maintenance-server-delete'),
+        level: allowedLevel
+      });
+    }
   }
 
   const runSave = db.transaction(() => {
@@ -322,6 +377,32 @@ export function getSuperuserPermissionMap() {
   return result;
 }
 
+export function getServerScopedPermissionKeys() {
+  const { serverScopedKeys } = getScopeCache();
+  return Array.from(serverScopedKeys);
+}
+
+export function isServerScopedPermission(permissionKey) {
+  if (!permissionKey) return false;
+  const { serverScopedKeys, scopeByKey } = getScopeCache();
+  if (serverScopedKeys.has(permissionKey)) {
+    return true;
+  }
+  const scope = scopeByKey.get(permissionKey);
+  return scope ? scope.isGlobal === false : false;
+}
+
+export function applyServerScopedOverride(basePermissions = {}, overridePermissions = {}) {
+  const merged = { ...basePermissions };
+  const { serverScopedKeys } = getScopeCache();
+  serverScopedKeys.forEach((key) => {
+    if (Object.prototype.hasOwnProperty.call(overridePermissions, key)) {
+      merged[key] = overridePermissions[key];
+    }
+  });
+  return merged;
+}
+
 export function getEffectivePermissionsForGroup(groupId) {
   const defaults = getDefaultPermissionMap();
   const numericId = Number(groupId);

backend/public/index.html

@@ -34,8 +34,8 @@
     <script defer data-site="YOUR_DOMAIN_HERE" src="https://api.nepcha.com/js/nepcha-analytics.js"></script>
         
 
-    <script type="module" crossorigin src="/assets/index-71db1823.js"></script>
-    <link rel="stylesheet" href="/assets/index-dad5f6fa.css">
+    <script type="module" crossorigin src="/assets/index-c3010de9.js"></script>
+    <link rel="stylesheet" href="/assets/index-c7ee792b.css">
   </head>
   <body>
     <div id="root"></div>

backend/setup/index.js

@@ -14,7 +14,6 @@ const updateServer = db.prepare(`
   SET name = ?, url = ?, updated_at = CURRENT_TIMESTAMP
   WHERE id = ?
 `);
-
 const deleteServerStmt = db.prepare('DELETE FROM servers WHERE id = ?');
 
 const selectApiKeyByServerId = db.prepare('SELECT * FROM server_api_keys WHERE server_id = ?');
@@ -34,6 +33,10 @@ const deleteApiKeyByServerId = db.prepare('DELETE FROM server_api_keys WHERE ser
 const countServersStmt = db.prepare('SELECT COUNT(*) as count FROM servers');
 const selectFirstServerStmt = db.prepare('SELECT * FROM servers ORDER BY id ASC LIMIT 1');
 
+function listServers() {
+  return selectAllServers.all();
+}
+
 const API_KEY_SECRET = crypto.createHash('sha256')
   .update(process.env.PORTAINER_API_SECRET || process.env.PORTAINER_API_KEY || 'stackpulse-portainer-api-key')
   .digest();
@@ -126,6 +129,53 @@ function ensureServer({ name, url }) {
   return created;
 }
 
+function getServerById(serverId) {
+  const id = Number(serverId);
+  if (!Number.isFinite(id)) {
+    const error = new Error('SERVER_ID_INVALID');
+    error.code = 'SERVER_ID_INVALID';
+    throw error;
+  }
+
+  const server = selectServerById.get(id);
+  if (!server) {
+    const error = new Error('SERVER_NOT_FOUND');
+    error.code = 'SERVER_NOT_FOUND';
+    throw error;
+  }
+
+  return server;
+}
+
+function updateServerDetails(serverId, { name, url }) {
+  const existing = getServerById(serverId);
+  const normalizedUrl = normalizeUrl(url || existing.url);
+  if (!normalizedUrl) {
+    const error = new Error('SERVER_URL_REQUIRED');
+    error.code = 'SERVER_URL_REQUIRED';
+    throw error;
+  }
+
+  const normalizedName = (name || deriveServerName(normalizedUrl)).trim();
+  if (!normalizedName) {
+    const error = new Error('SERVER_NAME_REQUIRED');
+    error.code = 'SERVER_NAME_REQUIRED';
+    throw error;
+  }
+
+  const other = selectServerByUrl.get(normalizedUrl);
+  if (other && other.id !== existing.id) {
+    const error = new Error('SERVER_URL_TAKEN');
+    error.code = 'SERVER_URL_TAKEN';
+    throw error;
+  }
+
+  updateServer.run(normalizedName, normalizedUrl, existing.id);
+  const updated = selectServerById.get(existing.id);
+  console.log(`ℹ️ [Setup] Server aktualisiert: ${updated.name} (${updated.id})`);
+  return updated;
+}
+
 function setServerApiKey({ serverId, apiKey }) {
   const id = Number(serverId);
   if (!Number.isFinite(id)) {
@@ -165,6 +215,13 @@ function setServerApiKey({ serverId, apiKey }) {
   };
 }
 
+function getServerConnection(serverId) {
+  const server = getServerById(serverId);
+  const apiKeyRow = selectApiKeyByServerId.get(server.id);
+  const apiKey = decryptApiKey(apiKeyRow);
+  return { server, apiKey };
+}
+
 function getActiveApiKey() {
   const firstServer = selectFirstServerStmt.get();
   if (firstServer) {
@@ -261,6 +318,18 @@ function ensureDefaultsFromEnv() {
   }
 }
 
+function getServerStatus(serverId) {
+  const server = getServerById(serverId);
+  const apiKeyMeta = selectApiKeyByServerId.get(server.id) || null;
+  return {
+    server,
+    apiKey: {
+      hasKey: Boolean(apiKeyMeta),
+      updatedAt: apiKeyMeta?.updated_at ?? null
+    }
+  };
+}
+
 function getSetupStatus() {
   const servers = selectAllServers.all();
   const apiKeyRecords = selectAllApiKeys.all();
@@ -361,7 +430,12 @@ function completeSetup({ server: serverInput }) {
 export {
   ensureDefaultsFromEnv,
   ensureServer,
+  getServerById,
+  listServers,
   setServerApiKey,
+  getServerConnection,
+  updateServerDetails,
+  getServerStatus,
   getActiveApiKey,
   getActiveServerUrl,
   hasServer,

backend/users/index.js

@@ -75,6 +75,48 @@ const insertMembershipForUser = db.prepare(`
   VALUES (?, ?)
 `);
 
+const selectServerByIdForAssignment = db.prepare('SELECT id, name, url FROM servers WHERE id = ?');
+
+const selectAssignmentsByUser = db.prepare(`
+  SELECT
+    usa.user_id,
+    usa.server_id,
+    usa.group_id,
+    usa.use_global_group,
+    usa.created_at,
+    usa.updated_at,
+    s.name AS server_name,
+    s.url AS server_url,
+    g.name AS group_name
+  FROM user_server_assignments usa
+  JOIN servers s ON s.id = usa.server_id
+  LEFT JOIN user_groups g ON g.id = usa.group_id
+  WHERE usa.user_id = ?
+  ORDER BY s.name ASC, usa.server_id ASC
+`);
+
+const upsertUserServerAssignment = db.prepare(`
+  INSERT INTO user_server_assignments (
+    user_id,
+    server_id,
+    group_id,
+    use_global_group,
+    created_at,
+    updated_at
+  ) VALUES (
+    ?, ?, ?, ?, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP
+  )
+  ON CONFLICT(user_id, server_id) DO UPDATE SET
+    group_id = excluded.group_id,
+    use_global_group = excluded.use_global_group,
+    updated_at = CURRENT_TIMESTAMP
+`);
+
+const deleteUserServerAssignments = db.prepare(`
+  DELETE FROM user_server_assignments
+  WHERE user_id = ?
+`);
+
 const selectSecurityPhraseByUsername = db.prepare(`
   SELECT
     id,
@@ -883,6 +925,176 @@ export function updateUserDetails(userId, { username, email, password, avatarCol
   return updatedUser;
 }
 
+const sanitizeAssignment = (row) => ({
+  userId: row.user_id,
+  serverId: row.server_id,
+  groupId: row.group_id ?? null,
+  groupName: row.group_name || null,
+  serverName: row.server_name || null,
+  serverUrl: row.server_url || null,
+  useGlobalGroup: Boolean(row.use_global_group),
+  createdAt: row.created_at || null,
+  updatedAt: row.updated_at || null
+});
+
+export function getUserServerAssignments(userId) {
+  const numericUserId = Number(userId);
+  if (!Number.isFinite(numericUserId) || numericUserId <= 0) {
+    const error = new Error('INVALID_USER_ID');
+    error.code = 'INVALID_USER_ID';
+    throw error;
+  }
+
+  const existingUser = selectUserCredentialsById.get(numericUserId);
+  if (!existingUser) {
+    const error = new Error('USER_NOT_FOUND');
+    error.code = 'USER_NOT_FOUND';
+    throw error;
+  }
+
+  const superuserMembership = isUserInGroupStatement.get(numericUserId, SUPERUSER_GROUP_NAME);
+  if (superuserMembership?.has_membership) {
+    return [];
+  }
+
+  const rows = selectAssignmentsByUser.all(numericUserId);
+  return rows.map(sanitizeAssignment);
+}
+
+export function setUserServerAssignments(userId, assignments = [], options = {}) {
+  const actor = options.actor || null;
+  const numericUserId = Number(userId);
+  if (!Number.isFinite(numericUserId) || numericUserId <= 0) {
+    const error = new Error('INVALID_USER_ID');
+    error.code = 'INVALID_USER_ID';
+    throw error;
+  }
+
+  const userRecord = selectUserCredentialsById.get(numericUserId);
+  if (!userRecord) {
+    const error = new Error('USER_NOT_FOUND');
+    error.code = 'USER_NOT_FOUND';
+    throw error;
+  }
+
+  const superuserMembership = isUserInGroupStatement.get(numericUserId, SUPERUSER_GROUP_NAME);
+  if (superuserMembership?.has_membership) {
+    const error = new Error('USER_SUPERUSER_PROTECTED');
+    error.code = 'USER_SUPERUSER_PROTECTED';
+    throw error;
+  }
+
+  const normalizedList = Array.isArray(assignments) ? assignments : [];
+  const missingServers = [];
+  const missingGroups = [];
+  const normalizedAssignments = new Map();
+
+  normalizedList.forEach((entry) => {
+    const rawServerId = entry?.serverId ?? entry?.server_id ?? entry?.id;
+    const serverId = Number(rawServerId);
+    if (!Number.isFinite(serverId) || serverId <= 0) {
+      return;
+    }
+
+    const serverRow = selectServerByIdForAssignment.get(serverId);
+    if (!serverRow) {
+      missingServers.push(serverId);
+      return;
+    }
+
+    const useGlobalGroup =
+      entry?.useGlobalGroup === true ||
+      entry?.use_global_group === 1 ||
+      entry?.use_global_group === true;
+
+    const rawGroupId = entry?.groupId ?? entry?.group_id;
+    const groupId = Number(rawGroupId);
+    const normalizedGroupId = Number.isFinite(groupId) && groupId > 0 ? groupId : null;
+
+    if (!useGlobalGroup && normalizedGroupId === null) {
+      missingGroups.push(serverId);
+      return;
+    }
+
+    if (normalizedGroupId !== null) {
+      const groupRow = selectGroupById.get(normalizedGroupId);
+      if (!groupRow) {
+        missingGroups.push(serverId);
+        return;
+      }
+    }
+
+    normalizedAssignments.set(serverId, {
+      serverId,
+      groupId: normalizedGroupId,
+      useGlobalGroup
+    });
+  });
+
+  if (missingServers.length > 0) {
+    const error = new Error('SERVER_NOT_FOUND');
+    error.code = 'SERVER_NOT_FOUND';
+    error.missingServerIds = missingServers;
+    throw error;
+  }
+
+  if (missingGroups.length > 0) {
+    const error = new Error('GROUP_NOT_FOUND');
+    error.code = 'GROUP_NOT_FOUND';
+    error.missingServerIds = missingGroups;
+    throw error;
+  }
+
+  const previousAssignments = selectAssignmentsByUser.all(numericUserId);
+
+  const applyAssignments = db.transaction(() => {
+    deleteUserServerAssignments.run(numericUserId);
+    Array.from(normalizedAssignments.values()).forEach((assignment) => {
+      upsertUserServerAssignment.run(
+        numericUserId,
+        assignment.serverId,
+        assignment.groupId,
+        assignment.useGlobalGroup ? 1 : 0
+      );
+    });
+  });
+
+  applyAssignments();
+
+  const updatedAssignments = selectAssignmentsByUser.all(numericUserId);
+  const sanitizedUpdated = updatedAssignments.map(sanitizeAssignment);
+
+  logEvent({
+    category: 'benutzer',
+    eventType: 'benutzer-server-zuordnung-aktualisiert',
+    action: 'aktualisieren',
+    status: 'erfolgreich',
+    entityType: 'benutzer',
+    entityId: String(numericUserId),
+    entityName: userRecord?.username ?? `ID ${numericUserId}`,
+    message: `Serverzuordnungen für Benutzer "${userRecord?.username ?? numericUserId}" aktualisiert`,
+    metadata: {
+      assignments: sanitizedUpdated.map((entry) => ({
+        serverId: entry.serverId,
+        serverName: entry.serverName,
+        useGlobalGroup: entry.useGlobalGroup,
+        groupId: entry.groupId,
+        groupName: entry.groupName
+      })),
+      previousAssignments: previousAssignments.map((entry) => ({
+        serverId: entry.server_id,
+        serverName: entry.server_name,
+        useGlobalGroup: Boolean(entry.use_global_group),
+        groupId: entry.group_id,
+        groupName: entry.group_name || null
+      }))
+    },
+    ...resolveActorFields(actor)
+  });
+
+  return sanitizedUpdated;
+}
+
 const deleteMembershipsStatement = db.prepare(`
   DELETE FROM user_group_memberships
   WHERE user_id = ?

docs/architecture.md

@@ -0,0 +1,57 @@
+# Architektur
+
+StackPulse folgt einer klassischen Client/Server-Architektur, bei der das Backend den Single-Source-of-Truth darstellt und das Frontend ausschließlich über wohldefinierte REST- und Socket.IO-Schnittstellen kommuniziert.
+
+```text
+┌────────────┐      HTTPS + WebSocket      ┌───────────────┐      HTTPS       ┌────────────────┐
+│  Frontend  │ ─────────────────────────▶  │   Backend     │ ───────────────▶ │ Portainer API │
+│ (React)    │ ◀───── Auth-Cookie + JSON ─ │ (Express)     │ ◀─────────────── │  Business Ed.  │
+└────────────┘      Redeploy Events       └───────────────┘   (Axios Proxy)   └────────────────┘
+                                             │
+                              mTLS (optional)│
+                                             ▼
+                                   StackPulse Agent
+                                             │
+                                             ▼
+                                     SQLite Datenbank
+```
+
+## Hauptschichten
+- **Frontend** (Vite + Material Tailwind): stellt Views, Tabellen, Setup-Wizard und Echtzeit-Widgets bereit. `AuthProvider` verwaltet Session, Permissions und Socket-Verbindungen.
+- **Backend** (Express + better-sqlite3): aggregiert Daten aus Portainer, persistiert Benutzer/Gruppen/Logs, verwaltet Sessions, Redeploy-Queue und Maintenance/Agent-Funktionen.
+- **Agent (optional)**: kleiner Node-Dienst, der lokal auf dem Portainer-Host läuft. Liefert Stack-/Portainer-Metadaten per REST, authentifiziert via `X-Agent-Token` und kann mTLS-Zertifikate aus dem Backend beziehen.
+- **Persistenz** (SQLite): Datei `backend/data/stackpulse.db`, WAL-Modus aktiviert. Tabellen umfassen u. a. `users`, `groups`, `permissions`, `servers`, `server_api_keys`, `event_logs`, `settings` sowie Hilfstabellen für Tokens und Sicherheitspassphrasen.
+
+## Datenflüsse
+1. **Setup-Phase**: `/api/setup/*` nimmt Serverdaten entgegen, verschlüsselt API-Keys (`aes-256-gcm` via `PORTAINER_API_SECRET`) und erstellt Einträge in `servers`/`server_api_keys`.
+2. **Authentication**: `/api/auth/login` erstellt Sessions (JWT-ähnliche Tokens in Cookies), `AuthProvider` ruft `/api/auth/session` zyklisch ab und speichert Berechtigungen.
+3. **Stack-Übersicht**: Frontend ruft `/api/stacks` auf. Das Backend proxyt `Portainer /api/endpoints/:id/docker/stacks`, ergänzt Caching, interne Metadaten und liefert Redeploy-Status.
+4. **Redeploy**: UI stößt `/api/stacks/:id/redeploy`, `/api/stacks/redeploy-selection` oder `/api/stacks/redeploy-all` an. Das Backend ruft Portainer-Endpoints, protokolliert Events und broadcastet Fortschritt via Socket.IO `redeployStatus`.
+5. **Logging**: Jeder relevante Vorgang erzeugt Einträge in `event_logs` (siehe `logging/eventLogs.js`). Frontend filtert/paginiert über `/api/logs` und kann Exporte `/api/logs/export` herunterladen.
+6. **Wartung**: `/api/maintenance/*` verwaltet Maintenance-Mode, SSH-Zugänge, Update-Skripte sowie weitere Wartungsfunktionen.
+
+## Verzeichnis-Referenz
+| Pfad | Inhalt |
+|------|--------|
+| `backend/index.js` | Herzstück der API inkl. Routing, Socket.IO, Redeploy, Setup, Auth. |
+| `backend/auth/` | Superuser-Verwaltung, Passwort- und Tokenfunktionen, Sicherheitsphrasen. |
+| `backend/db/` | SQLite-Initialisierung (`ensure.js`/`schemaEnsure.js`), Settings-Layer, DB-Blueprints. |
+| `backend/logging/` | Event-Log Modellierung, Filter/Export/Delete. |
+| `backend/groups/`, `backend/users/`, `backend/permissions/` | Domain-Logik für Benutzer- & Rechteverwaltung. |
+| `backend/maintenance/` | Maintenance-Mode sowie SSH-/Update-Konfiguration. |
+| `frontend/src/` | React-App (Layouts, Pages, Widgets, Provider). `routes.jsx` definiert Navigation & Permissions. |
+| `scripts/` | Hilfsskripte (z. B. `start-dev.sh`). |
+| `Dockerfile`, `docker-compose*.yml` | Build- & Deployment-Spezifikation. |
+
+## Konfiguration & Secrets
+- API-Keys und Passwörter werden verschlüsselt in SQLite abgelegt (`server_api_keys`, `settings`).
+- Settings (Maintenance, Update-Skripte, SSH) nutzen `db/settings.js` mit JSON-Serialisierung.
+- Das Backend erzwingt HTTPS-Requests Richtung Portainer (`https.Agent` mit deaktivierter Zertifikatsprüfung für interne Netze).
+- Socket.IO lauscht auf demselben Port wie Express (`/socket.io`). CORS ist aktuell für alle Origins offen – für produktive Deployments empfiehlt sich ein Reverse Proxy mit Authentifizierung.
+
+## Skalierung & Grenzen
+- SQLite eignet sich für Einzelinstanzen. Für höhere Last empfiehlt sich eine Umstellung auf Postgres/MySQL (der Code kapselt Zugriffe weitgehend in `db/*`).
+- Redeploy-Operationen werden seriell behandelt (`redeployingStacks` + Status-Caching). Parallele Ausführung ist möglich, solange Portainer dies unterstützt.
+- Logging wird ausschließlich serverseitig betrieben; Client-seitige Filterung erfolgt über Query-Parameter.
+
+Die weiteren Kapitel vertiefen Backend- und Frontend-spezifische Details.

docs/backend.md

@@ -0,0 +1,113 @@
+# Backend & API
+
+Das Backend implementiert alle Anwendungsfälle über Express-Routen, Socket.IO für Echtzeit-Events und eine SQLite-Datenbank als Persistenzschicht. Dieser Abschnitt fasst die wichtigsten Module, Entitäten und Endpunkte zusammen.
+
+## Laufzeit & Einstiegspunkte
+- `backend/index.js` initialisiert Express, Socket.IO, lädt `.env`, sorgt für Schema-Validierung (`ensureDatabaseSchema`) und Default-Daten (`ensureSuperuserFromEnv`, `ensureDefaultsFromEnv`).
+- Start via `npm start` (siehe `package.json`); Migrationen über `npm run migrate`.
+- Datenbankdatei: `backend/data/stackpulse.db`, WAL-Modus aktiv.
+
+## Module
+| Modul | Pfad | Aufgabe |
+|-------|------|---------|
+| Auth/Superuser | `auth/superuser.js` | Registrieren/Verifizieren von Superusern, Login, Passwortvalidierung, Sicherheitsphrasen. |
+| Users & Groups | `users/*`, `groups/*`, `permissions/*` | CRUD für Benutzer, Gruppen, Rechtezuweisung, Ableitung effektiver Berechtigungen. Rechte-Labels z. B. `Bereich & Navigation`, `Benutzergruppen bearbeiten`, `Benutzer löschen`. |
+| Setup | `setup/index.js` | Verwaltung registrierter Portainer-Server, sichere Ablage der API-Keys, Setup-Status. |
+| Logging | `logging/eventLogs.js` | Einheitliches Ereignislogging (Insert, Filter, Delete, Export). |
+| Maintenance | `maintenance/state.js` + Helper in `index.js` | Wartungsmodus, SSH-Konfiguration, Update-Skripte und Ausführung. |
+| Portainer Proxy | Funktionen in `index.js` | Kommunikation mit Portainer (`axiosInstance` + dynamische `baseURL`), Environment-Erkennung und Redeploy-Strecke. |
+
+## API-Überblick (Auszug)
+### Setup & Server
+| Methode | Route | Beschreibung |
+|---------|-------|--------------|
+| GET | `/api/setup/status` | Gibt zurück, ob Server/API-Key/Superuser vorhanden sind. |
+| POST | `/api/setup/test-portainer` | Verifiziert URL + API-Key gegen Portainer. |
+| POST | `/api/setup/portainer-stacks` | Listet Stacks (für Preview im Wizard). |
+| POST | `/api/setup/complete` | Markiert Setup als abgeschlossen und hinterlegt Server/API-Key. |
+| DELETE | `/api/setup/servers/:id` | Entfernt einen registrierten Portainer-Server. |
+| PUT | `/api/setup/servers/:id/api-key` | Überschreibt API-Key. |
+| PUT | `/api/setup/self-stack` | Speichert die ID des StackPulse-Stacks, damit dieser nicht redeployed wird.
+
+### Authentifizierung
+| Methode | Route | Beschreibung |
+|---------|-------|--------------|
+| POST | `/api/auth/login` | Username/Passwort-Login, setzt HTTP-only Cookie. |
+| POST | `/api/auth/logout` | Session beenden & Cookie löschen. |
+| GET | `/api/auth/session` | Liefert eingeloggten Benutzer + Permissions. |
+| POST | `/api/auth/recover/verify` & `/reset` | Passwortreset über Sicherheitsphrase. |
+| GET/POST/DELETE | `/api/auth/superuser/*` | Abfrage, Registrierung oder Entfernen des Superusers.
+
+### Benutzer & Gruppen
+| Methode | Route | Beschreibung |
+|---------|-------|--------------|
+| GET/POST | `/api/users` | Liste anlegen, neue Benutzer erstellen. |
+| GET/PUT/DELETE | `/api/users/:id` | Details lesen, bearbeiten oder löschen. |
+| PUT | `/api/users/:id/groups` | Gruppenmitgliedschaften aktualisieren. |
+| PUT | `/api/users/:id/active` | Benutzer aktivieren/deaktivieren. |
+| GET/POST | `/api/users/:id/security-phrase`, `/renew` | Sicherheitsphrase anzeigen bzw. neu generieren. |
+| GET/POST | `/api/groups` | Gruppen auflisten oder neu anlegen. |
+| PUT/DELETE | `/api/groups/:id` | Gruppe editieren oder entfernen. |
+| GET/PUT | `/api/groups/:id/permissions` | Berechtigungen lesen/setzen.
+
+### Stacks & Redeploy
+| Methode | Route | Beschreibung |
+|---------|-------|--------------|
+| GET | `/api/stacks` | Aggregierte Liste inkl. Filter, Self-Stack-Blockade und Redeploy-Status. |
+| PUT | `/api/stacks/:id/redeploy` | Redeploy eines einzelnen Stacks. |
+| PUT | `/api/stacks/redeploy-selection` | Redeploy einer Liste übermittelter `stackIds`. |
+| PUT | `/api/stacks/redeploy-all` | Redeploy aller Stacks (Recht `Redeploy Alle`). |
+
+Das Backend veröffentlicht den Redeploy-Fortschritt parallel über Socket.IO (`redeployStatus` Event) und unterscheidet die Phasen `queued`, `started`, `success`, `error`, `info`.
+
+### Logging & Wartung
+| Methode | Route | Beschreibung |
+|---------|-------|--------------|
+| GET | `/api/logs` | Filterbare/Paginierbare Event-Logs. |
+| DELETE | `/api/logs/:id` oder `/api/logs` | Einzelne oder gefilterte Logs löschen. |
+| GET | `/api/logs/export` | CSV-Export anhand der Query-Filter. |
+| GET/POST | `/api/maintenance/mode` | Status abfragen oder toggeln. |
+| GET | `/api/maintenance/config` | Liefert Maintenance-Status, Update-Skript & SSH-Config. |
+| PUT/DELETE | `/api/maintenance/ssh-config` | SSH-Credentials speichern/entfernen. |
+| POST | `/api/maintenance/test-ssh` | Verbindungstest mit optionalem Override. |
+| PUT/DELETE | `/api/maintenance/update-script` | Custom Update-Skript pflegen. |
+| POST | `/api/maintenance/portainer-update` | Update-Kommando per SSH ausführen (mit Custom/Default-Skript). |
+
+## Datenbank & Schema
+- `ensureDatabaseSchema()` erzeugt Tabellen bei jedem Start, inklusive Default-Gruppen, Permissions, Settings, Server-Einträge und Trigger.
+- Permissions werden anhand der Blueprint-Datei `backend/db/dbs` eingelesen. Jede Permission definiert Key, Label (z. B. `Bereich & Navigation`, `Server bearbeiten`, `SSH/Update-Skript`, `Update durchführen`, `Doppelte Stacks`), Level (`full`, `read`, `none`) und Abhängigkeiten.
+- Events werden in `event_logs` gespeichert. Relevante Felder:
+  - `category`, `event_type`, `action`, `status`, `severity`
+  - `entity_type`, `entity_id`, `entity_name`
+  - `actor_type`, `actor_id`, `actor_name`
+  - `context_type`, `context_id`, `context_label`
+  - `message`, `metadata (JSON)`
+- Filter-Parameter (`ids`, `categories`, `eventTypes`, `status`, `stackIds`, Zeitfenster) werden in `buildEventLogFilter` zentral verarbeitet.
+
+## Berechtigungssystem
+- Jeder Benutzer gehört zu beliebig vielen Gruppen; die effektiven Rechte ergeben sich aus der höchsten Ausprägung pro Permission (Labels wie `Bereich & Navigation`, `Server bearbeiten`, `SSH/Update-Skript`, `Update durchführen`, `Doppelte Stacks`).
+- Superuser erhalten alle Berechtigungen und können nicht über das UI entzogen werden.
+- `PermissionGate` im Frontend spiegelt die gleichen Keys. Wichtigste Bereiche:
+  - `Redeploy einzeln/Auswahl/Alle`
+  - `Bereich & Navigation (Logs)`, `Logs Exportieren`, `Logs löschen`
+  - `Bereich & Navigation (Benutzer)`, `Benutzer bearbeiten/löschen`, `Sicherheitsschlüssel`
+  - `Bereich & Navigation (Benutzergruppen)`, `Benutzergruppen bearbeiten/löschen`
+  - Wartung: `Bereich & Navigation (Wartung)`, `Server-Sektion`, `Server bearbeiten/löschen`, `SSH/Update-Skript`, `Update durchführen`, `Doppelte Stacks`
+
+## Redeploy-Workflow
+1. Eingehender Request wird mit `maintenanceGuard` geprüft (Maintenance-Modus blockiert optional Redeploys).
+2. Das Backend ermittelt den zugehörigen Portainer-Endpoint (`resolvePortainerEnvironmentId`).
+3. Der Redeploy wird über Portainer ausgeführt (`/api/stacks/:id/redeploy`), Log-Einträge werden erstellt.
+4. `broadcastRedeployStatus()` aktualisiert das In-Memory-Tracking (`redeployingStacks`) und sendet Socket.IO Events.
+5. Fehler führen zu `event_logs`-Einträgen mit `severity=error`, UI zeigt Toasts via `ToastProvider`.
+
+## Wartungs- und Updatepfad
+- `maintenance/state.js` persistiert Aktivierung & Nachricht im Setting `maintenance_mode`.
+- SSH-Konfigurationen (Host, Port, User, Passwort, extra args) werden verschlüsselt gespeichert (`getPortainerSshConfig`).
+- Update-Skripte lassen sich überschreiben, Standard-Skript liegt in `DEFAULT_PORTAINER_UPDATE_SCRIPT` (Bash-Befehle).
+- Update-Status hält Laufzeiten, letzte Ergebnisse und Logauszüge in-memory & Settings bereit.
+
+## Erweiterungstipps
+- Neue API-Routen sollten `requirePermission(..)` nutzen, Logging via `logEvent()` hinzufügen und – falls Portainer-Aufrufe stattfinden – das `axiosInstance` verwenden.
+- Einstellungen stets über `db/settings.js` verwalten, damit UI & CLI konsistent bleiben.
+- Für breaking DB-Änderungen existiert kein Migrations-Framework – erweitere `ensureDatabaseSchema` inkl. Versionsflag, um Idempotenz sicherzustellen.

docs/environment.md

@@ -0,0 +1,59 @@
+# Umgebungsvariablen
+
+Diese Seite sammelt alle relevanten Umgebungsvariablen für StackPulse (Backend) und den optionalen StackPulse Agent. Werte ohne Default sind in der Regel optional, sofern sie nicht explizit als „erforderlich“ markiert sind.
+
+## StackPulse Backend
+| Variable | Default | Erforderlich | Beschreibung |
+|----------|---------|--------------|--------------|
+| `PORTAINER_URL` | – | Nein | Basis-URL zu Portainer. Kann im Setup-UI hinterlegt werden; ohne Wert schlägt Portainer-Zugriff fehl, bis ein Server gespeichert ist. |
+| `PORTAINER_API_KEY` | – | Nein | API-Key für Portainer. Kann im Setup-UI gespeichert (verschlüsselt) werden; ohne Wert keine API-Aufrufe. |
+| `PORTAINER_SERVER_NAME` | – | Nein | Anzeigename für den initialen Servereintrag (nur kosmetisch). |
+| `PORTAINER_API_SECRET` | `stackpulse-portainer-api-key` | Nein | AES-Schlüssel für gespeicherte API-Keys. Stabil halten, sonst müssen Keys neu eingetragen werden. |
+| `SUPERUSER_USERNAME` | – | Nein | Legt beim Start einen Superuser an, falls noch keiner existiert; alternativ im Setup-UI anlegen. |
+| `SUPERUSER_EMAIL` | – | Nein | E-Mail des initialen Superusers. |
+| `SUPERUSER_PASSWORD` | – | Nein | Passwort des initialen Superusers. |
+| `SELF_STACK_ID` | – | Nein | ID des StackPulse-Stacks; verhindert Self-Redeploy im UI. |
+| `AUTH_COOKIE_NAME` | `sp_auth_token` | Nein | Name des Auth-Cookies. |
+| `AUTH_SESSION_TTL_MS` | `43200000` (12h) | Nein | Session-Lebensdauer in Millisekunden. |
+| `AUTH_COOKIE_SECURE` | `false` | Nein | Setzt Cookie nur über HTTPS, wenn `true`. |
+| `SECURITY_PHRASE_SECRET` | `stackpulse-security-phrase-secret` | Nein | Secret für verschlüsselte Sicherheitsphrasen; stabil halten, sonst Phrasen neu verteilen. |
+| `PORTAINER_SSH_SECRET` | – (Fallback API-Key/Default) | Nein | Secret für verschlüsselte SSH-Passwörter; stabil halten, sonst Passwort neu setzen. |
+| `AGENT_MTLS_KEY` | generiert | Nein | Optional: eigenes PEM-Key für internen mTLS-Server, falls nicht automatisch erzeugt. |
+| `AGENT_MTLS_CERT` | generiert | Nein | Optional: eigenes PEM-Zertifikat für internen mTLS-Server. |
+| `AGENT_MTLS_PORT` | `4441` | Nein | Port des internen mTLS-Endpunkts (Agent). |
+| `DISPLAY` | `:9999` | Nein | Wird an Child-Prozesse (Update-Skript) weitergereicht. |
+
+## StackPulse Agent
+| Variable | Default | Erforderlich | Beschreibung |
+|----------|---------|--------------|--------------|
+| `AGENT_PORT` | `7070` | Nein | Listenport des Agents (HTTPS mit mTLS). |
+| `AGENT_TOKEN` | – | Ja | Shared Secret für Auth (`X-Agent-Token`) bei allen Agent-Endpoints. |
+| `DOCKER_SOCKET` | `/var/run/docker.sock` | Nein | Pfad zum Docker-Socket; nötig für Stack-/Image-Infos. |
+| `CONTROL_PLANE_URL` | – | Ja (für Bootstrap/Restore) | Basis-URL des StackPulse-Backends für Zertifikatsabruf ohne mTLS (z. B. `https://stackpulse:4001`). |
+| `CONTROL_PLANE_MTLS_URL` | – | Nein (empfohlen) | Bevorzugte mTLS-URL des Backends (z. B. `https://stackpulse:4441`). Wird für alle Agent→Backend-Calls genutzt, sobald Zertifikate vorliegen; fehlt sie, wird aus `CONTROL_PLANE_URL` + `AGENT_MTLS_PORT` abgeleitet. |
+| `AGENT_BOOTSTRAP_TOKEN` | – | Nein (für Erstbootstrap) | Einmal-Token aus dem Wartungsbereich, um mTLS-Zertifikate zu ziehen. Pflicht, wenn keine Zertifikate vorliegen und das Backend noch kein Material für den Agent gespeichert hat. |
+| `AGENT_MTLS_PORT` | `4441` | Nein | Fallback-Port, falls `CONTROL_PLANE_MTLS_URL` keinen Port enthält. |
+| `AGENT_SERVER_KEY` / `AGENT_SERVER_CERT` | – | Nein | PEM-Material für den Agent-Server; nur nötig bei eigenen Zertifikaten statt Backend-CA. |
+| `AGENT_CLIENT_KEY` / `AGENT_CLIENT_CERT` / `AGENT_CA_CERT` | – | Nein | PEM-Material für Client/CA; nur bei eigener PKI nötig. |
+| `REGISTRY_TOKEN` | – | Nein | Bearer-Token für Registry-Abfragen (Digest-Vergleich). |
+| `REGISTRY_USERNAME` / `REGISTRY_PASSWORD` | – | Nein | Basic-Auth-Creds für Registries. |
+| `GITHUB_USERNAME` / `GITHUB_TOKEN` / `GITHUB_PAT` | – | Nein | Alternative Credential-Quellen für GitHub Packages. |
+
+
+Agent-Betrieb (wähle eine Variante):
+
+  - **Dynamisch über Backend (empfohlen)**  
+    - Pflicht: `AGENT_TOKEN` + `CONTROL_PLANE_URL` (optional `CONTROL_PLANE_MTLS_URL`).  
+    - Falls keine Zertifikate existieren: einmaliges `AGENT_BOOTSTRAP_TOKEN` setzen.  
+    - Der Agent zieht Zertifikate vom Backend, schaltet auf mTLS um und braucht danach kein Bootstrap-Token mehr.
+  - **Statisch per ENV**  
+    - Liefere PEMs: `AGENT_SERVER_KEY`/`AGENT_SERVER_CERT` + `AGENT_CLIENT_KEY`/`AGENT_CLIENT_CERT`/`AGENT_CA_CERT`.  
+    - Dann kein `CONTROL_PLANE_URL`/Bootstrap nötig, da mTLS-Material bereits vorhanden ist.  
+    - `AGENT_TOKEN` bleibt erforderlich.
+    
+Hinweise:
+
+  - Server-URL und API-Key kannst du im Setup-UI pflegen; Umgebungsvariablen setzen nur den Initialzustand.
+  - Secrets (`SECURITY_PHRASE_SECRET`, `PORTAINER_SSH_SECRET`, `PORTAINER_API_SECRET`) in Produktion einmalig setzen und stabil halten – sonst werden bestehende verschlüsselte Werte unlesbar.
+
+  - `CONTROL_PLANE_MTLS_URL`: bevorzugte mTLS-Zieladresse. Fehlt sie, leitet der Agent sie aus `CONTROL_PLANE_URL` + `AGENT_MTLS_PORT` ab und nutzt sie für alle Aufrufe, sobald Zertifikate vorliegen.

docs/frontend.md

@@ -0,0 +1,63 @@
+# Frontend
+
+Das Frontend basiert auf React 18, Vite und dem Material Tailwind Dashboard. Es nutzt Context Provider für Authentifizierung, Seitenstatus, Toaster und Wartungsinformationen.
+
+## Build & Skripte
+| Befehl | Beschreibung |
+|--------|--------------|
+| `npm run dev` | Startet den Vite Dev-Server (Port 5173, HMR aktiviert). |
+| `npm run build` | Erstellt ein Production-Bundle (`frontend/dist`). Das Dockerfile kopiert dieses Paket ins Backend (`backend/public`). |
+| `npm run preview` | Vorschau auf das gebaute Bundle.
+
+## Projektstruktur
+```
+frontend/src
+├── App.jsx                # Entry-Point, registriert Layouts & Provider
+├── components/           # AuthProvider, PermissionGate, Toast/Maintenance/PageProvider
+├── layouts/              # Dashboard-Layout (Sidebar, Navbar) & Auth-Layout
+├── pages/
+│   ├── auth/             # SignIn, SignUp, ForgotPassword, SignOut
+│   ├── dashboard/        # Stacks, Logs, Maintenance, Users, Usergroups, Detailseiten
+│   └── setup/            # Setup-Wizard & Helper Screens
+├── routes.jsx            # zentrale Navigationsdefinition inkl. Permissions
+├── widgets/, data/, configs/, assets/
+└── tailwind.css          # Tailwind Layer & Custom Styles
+```
+
+## Routing & Navigation
+- `routes.jsx` beschreibt sowohl Dashboard- als auch Auth-Routen. Jede Dashboard-Seite besitzt optional ein `permission`-Objekt, das vom `PermissionGate` ausgewertet wird.
+- Der Layout-Switch erfolgt über `layouts/index.jsx`, das wiederum Sidebar/Topbar-Komponenten aus dem Material Tailwind Dashboard nutzt.
+- Auth-Routen (`/sign-in`, `/sign-up`, `/forgot-password`, `/logout`) werden im Auth-Layout ohne Sidebar dargestellt.
+
+## State-Management & Contexts
+| Provider | Aufgabe |
+|----------|---------|
+| `AuthProvider` | Speichert User, Permissions, Session-Status. Stellt `refreshSession`, `logout`, `hasPermission` bereit. |
+| `PageProvider` | Zentrale UI-Zustände (z. B. Ladeanzeigen, modale Dialoge) für Dashboard-Komponenten. |
+| `ToastProvider` | Globale Notifications (z. B. Redeploy-Erfolg/Fehler). |
+| `MaintenanceProvider` | Cached Maintenance-Status, erkennt aktive Maintenance Modes und zeigt Hinweise. |
+
+## Wichtige Seiten
+- **Stacks (`pages/dashboard/stacks.jsx`)**: Hauptübersicht mit Tabellen, Suche, Filtern, Bulk- und Einzelredeploy. Bindet `socket.io-client` für Live-Updates (`redeployStatus`).
+- **Logs (`pages/dashboard/logs.jsx`)**: Tabellenansicht mit Statusfarben, Filterchips, Export-/Delete-Aktionen. Nutzt axios-Queries gegen `/api/logs`.
+- **Maintenance (`pages/dashboard/maintenance.jsx`)**: Formulare zur Verwaltung von Update-Skript, SSH-Konfiguration, Maintenance-Mode-Toggle und Portainer-Statusprüfung.
+- **Users / Usergroups**: CRUD-Oberfläche für Benutzer, Gruppen, Berechtigungszuweisung inkl. Sicherheitsphrasen-Handling.
+- **Setup (`pages/setup`)**: Schrittweiser Wizard (Server -> API-Key -> Superuser). Wird solange angezeigt, bis `/api/setup/status` vollständig ist.
+
+## Datenzugriff
+- HTTP-Anfragen erfolgen via `axios` (global konfiguriert in `frontend/src/components/AuthProvider` bzw. direkt in den Seiten). Cookies werden automatisch vom Browser beigesteuert (`credentials: 'include'`).
+- Socket.IO wird nur im Stack-Dashboard verwendet; Verbindungsaufbau erfolgt in `stacks.jsx` (`io('/', { path: '/socket.io' })`).
+- Fehlerbehandlung: Jede Seite zeigt Toasts und/oder Inline-Warnungen. Auth-Fehler leiten zur Loginseite um.
+
+## Styling & Komponenten
+- Tailwind Utility-Klassen liefert Material Tailwind bereits vordefiniert (Theme in `configs`).
+- Custom-Komponenten wie Tabellen, Filterchips oder Formulare sind überwiegend in `widgets/` ausgelagert.
+- Icons stammen aus `@heroicons/react`. Farben/Typografie folgen Creative Tim Vorgaben, können aber zentral in `frontend/src/configs` angepasst werden.
+
+## Erweiterungshinweise
+1. **Neue Seiten**: Route in `routes.jsx` ergänzen, optional `PermissionGate` konfigurieren und Seite unter `pages/dashboard` oder `pages/auth` anlegen.
+2. **API-Anbindungen**: Verwende `axios` und achte auf `try/catch`, damit 401/403 sauber abgefangen werden. Bei kritischen Anforderungen `refreshSession` aufrufen.
+3. **State teilen**: Nutze bestehende Provider bzw. erzeuge einen eigenen Context in `components/`.
+4. **Deployment**: `npm run build` liefert ein Self-Contained Bundle. Das Backend dient anschließend als Static Host (`express.static`).
+
+Damit bietet das Frontend eine anpassbare, klar strukturierte Oberfläche, die eng mit den Backend-Permissions verzahnt ist.

docs/getting-started.md

@@ -0,0 +1,79 @@
+# Getting Started
+
+Dieser Leitfaden beschreibt ausschließlich den Docker-Deploy über die bereitgestellten GHCR-Images und die anschließende Einrichtung im UI.
+
+## Voraussetzungen
+- Docker & Docker Compose
+- Portainer-Instanz (Business Edition empfohlen; bei Community/Edge zusätzlich Agent einsetzen)
+
+## Zentrale Umgebungsvariablen (Kurzfassung)
+| Variable | Erforderlich | Beschreibung |
+|----------|--------------|--------------|
+| `PORTAINER_URL` | Nein | Basis-URL zu Portainer; kann im Setup-UI hinterlegt werden, falls nicht gesetzt. |
+| `PORTAINER_API_KEY` | Nein | API-Key; kann im Setup gespeichert werden (wird verschlüsselt). |
+| `PORTAINER_SERVER_NAME` | Nein | Anzeige-Name für den initialen Servereintrag. |
+| `PORTAINER_API_SECRET` | Nein | AES-Schlüssel für gespeicherte API-Keys; setze stabilen Wert, sonst muss der Key neu eingegeben werden. |
+| `SUPERUSER_USERNAME`, `SUPERUSER_EMAIL`, `SUPERUSER_PASSWORD` | Nein | Legt automatisch einen Superuser an, falls noch keiner existiert; sonst im Setup-UI anlegen. |
+| `SELF_STACK_ID` | Nein | ID des StackPulse-Stacks; schützt vor Self-Redeploy. |
+| `AUTH_COOKIE_NAME`, `AUTH_SESSION_TTL_MS`, `AUTH_COOKIE_SECURE` | Nein | Session/Cookie-Tuning (Name, Dauer, Secure-Flag). |
+| `SECURITY_PHRASE_SECRET` | Nein | Secret für verschlüsselte Sicherheitsphrasen; stabil halten, sonst Phrasen neu verteilen. |
+| `PORTAINER_SSH_SECRET` | Nein | Secret für verschlüsselte SSH-Passwörter; stabil halten, sonst Passwort neu setzen. |
+| `DISPLAY` | Nein | Wird an Update-Childprozesse weitergereicht (Default `:9999`). |
+
+Weitere Variablen (Agent, Registry, mTLS) findest du im Detail unter [Umgebungsvariablen](environment.md). Einstellungen wie Server-URL/API-Key, SSH-Config oder Update-Skript kannst du alternativ im UI (Setup/Wartung) verwalten.
+
+**Hinweis zu Secrets:**  
+- `SECURITY_PHRASE_SECRET` und `PORTAINER_SSH_SECRET` steuern die AES-256-GCM-Verschlüsselung von Sicherheitsphrasen bzw. hinterlegten SSH-Passwörtern.  
+- Wenn sie nicht gesetzt sind, nutzt StackPulse fixe Fallbacks (`stackpulse-security-phrase-secret` bzw. `stackpulse-portainer-ssh-secret` / API-Key). Setze in Produktion eigene, stabile Werte – ein späterer Secret-Wechsel macht zuvor gespeicherte Phrasen/Passwörter unlesbar.  
+- Eine vollständige Übersicht aller Variablen (inkl. Agent) findest du unter „Technik → Umgebungsvariablen“.
+
+## Ersteinrichtung im UI
+1. Öffne das Frontend.
+2. Lege den Portainer-Server und den zugehörigen API-Key an (der Wizard führt durch den Test).
+3. Registriere einen Superuser oder verwende den per Umgebungsvariablen automatisch angelegten Account.
+4. Nach erfolgreicher Einrichtung kannst du dich anmelden und erhältst Zugriff auf Dashboard, Logs, Benutzer & Wartung.
+
+## Docker Run (Single Container)
+```bash
+docker run -d \
+  -p 4001:4001 \
+  -e PORTAINER_URL=https://portainer.example.com \
+  -e PORTAINER_API_KEY=xxxx \
+  -e SUPERUSER_USERNAME=admin \
+  -e SUPERUSER_EMAIL=admin@example.com \
+  -e SUPERUSER_PASSWORD=changeme \
+  -e SELF_STACK_ID=123 \
+  -e SECURITY_PHRASE_SECRET=$(openssl rand -hex 32) \
+  -e PORTAINER_SSH_SECRET=$(openssl rand -hex 32) \
+  -v stackpulse_data:/app/backend/data \
+  ghcr.io/mboehmlaender/stackpulse:latest
+```
+Das Volume `stackpulse_data` persistiert die SQLite-Datenbank. Passen Sie Secrets und Ports an Ihre Umgebung an; weitere Variablen siehe Kapitel „Umgebungsvariablen“.
+
+## Docker-Deployment (Compose)
+```yaml
+# docker-compose.yml (Auszug)
+services:
+  app:
+    image: ghcr.io/mboehmlaender/stackpulse:latest
+    ports:
+      - "4001:4001"
+    volumes:
+      - stackpulse_data:/app/backend/data
+    restart: unless-stopped
+    environment:
+      - PORTAINER_URL=https://portainer.example.com
+      - PORTAINER_API_KEY=xxxx
+      - SUPERUSER_USERNAME=admin
+      - SUPERUSER_EMAIL=admin@example.com
+      - SUPERUSER_PASSWORD=changeme
+      - SELF_STACK_ID=123
+volumes:
+  stackpulse_data:
+```
+
+1. `docker compose up -d`
+2. Das Frontend ist anschließend unter Port 4001 erreichbar.
+3. Datenbank & Einstellungen liegen im benannten Volume `stackpulse_data`.
+
+Damit bist du bereit für die tieferen Kapitel zu Architektur sowie Backend- und Frontend-Details.

docs/index.md

@@ -0,0 +1,36 @@
+# StackPulse
+
+StackPulse ist eine eigenständige Web-Anwendung, die die Portainer Business Edition über deren API steuert und dadurch Redeploys, Wartungsskripte sowie das Berechtigungs- und Logging-Konzept zentralisiert. Die Lösung besteht aus einem Node.js/Express Backend, einem React-Frontend auf Basis von Material Tailwind sowie einer eingebetteten SQLite-Datenbank, die ohne zusätzliche Infrastruktur betrieben werden kann.
+
+## Warum StackPulse?
+- **Schneller Überblick** über sämtliche Stacks einer Portainer-Instanz inkl. Status, Filter und Suche
+- **Redeploy-Orchestrierung** aus einem UI heraus – einzelne Stacks, Auswahlen oder komplette Umgebungen
+- **Auditierbare Historie** durch strukturierte Event-Logs mit Export-, Lösch- und Filterfunktionen
+- **Feingranulare Rechteverwaltung** mit Gruppenrechten, Superuser-Handling und Sicherheitsphrasen
+- **Wartungsautomatisierung** (SSH Update-Skripte, Maintenance-Mode) ohne direkten Portainer-Zugang
+- **Agent-Integration** (mTLS) für Portainer Community/Edge, um Stacks & Versionen auch ohne Business-API auszulesen
+- **Bereitstellung als Docker-Image** sowie als lokale Dev-Umgebung via `scripts/start-dev.sh`
+
+## Technische Eckdaten
+| Baustein    | Technologie | Beschreibung |
+|-------------|-------------|--------------|
+| Backend     | Node.js 20, Express, Axios, Socket.IO, better-sqlite3 | Stellt REST-API, Authentifizierung, Rechte, Logging, Redeploy-Queue und Portainer-Proxy bereit. |
+| Datenhaltung| SQLite (Datei `backend/data/stackpulse.db`) | Persistente Speicherung von Benutzern, Gruppen, Servern, API-Keys, Logs und Einstellungen. |
+| Frontend    | React 18, Vite, Material Tailwind Dashboard | Dashboard mit Auth-Flow, Stacks, Logs, Benutzer- und Wartungsansichten. |
+| Container   | Dockerfile + Compose | Multi-Stage Build für Frontend + Backend, Datenvolumen für SQLite. |
+
+## Release-Status
+- **v0.5 (aktuell)** – vollständiges Auth/Berechtigungssystem, Benutzer- & Gruppenverwaltung, erweiterte Logs
+- **v0.4** – neues UI auf Basis des Material Tailwind Dashboards
+- **v0.3** – Such- & Filterfunktionen, Konfliktbehandlung für Stack-IDs, UI-Benachrichtigungen
+- **v0.2** – SQLite-Logging inkl. Export/Pagination, Redeploy-Selektor
+- **v0.1** – Grundstruktur, API-Anbindung, erstes Redeploy
+
+Weitere geplante Features (Notifications, Monitoring, Multi-Server, Portainer CE) findest du in der [Roadmap im README](../README.md).
+
+## Wie geht es weiter?
+- [Getting Started](getting-started.md) erläutert Installation, Konfiguration und erste Schritte.
+- [Architektur](architecture.md) beschreibt Aufbau, Verzeichnisse und Datenflüsse.
+- [Backend](backend.md) fasst API, Datenbank und Sicherheitsschichten zusammen.
+- [Frontend](frontend.md) dokumentiert Layout, Routen und Komponenten.
+- [Operations & Wartung](operations.md) enthält Betriebshinweise und Troubleshooting.

docs/local-dev.md

@@ -0,0 +1,53 @@
+# Lokale Entwicklung & Migration
+
+Dieser Abschnitt richtet sich an Contributor:innen, die StackPulse lokal bauen oder erweitern möchten. Für produktive Deployments nutze die GHCR-Images wie im Getting Started beschrieben.
+
+## Voraussetzungen
+- Node.js **>= 20** und npm
+- Shell-Zugang zum Host
+- Docker (optional) für lokale Tests
+
+## Repository vorbereiten
+```bash
+# Repository klonen
+# git clone <repo-url>
+cd stackpulse
+
+# Startskript ausführbar machen
+chmod +x scripts/start-dev.sh
+```
+
+## Schnellstart (Dev-Skript)
+Das Skript `scripts/start-dev.sh` richtet Backend und Frontend ein und startet beide im Dev-Modus:
+1. Backend: `npm install`, `npm run migrate`, `npm start`
+2. Frontend: `npm install`, `npm run dev` (Port 5173) und einmalig `npm run build` für statische Assets
+
+Nach dem Start:
+- Frontend Dev Server: http://localhost:5173
+- Backend API & statische Assets: http://localhost:4001
+
+Stoppen mit `STRG+C` in der Shell, in der das Skript läuft.
+
+## Manuelles Starten
+```bash
+# Backend
+cd backend
+npm install
+npm run migrate
+PORTAINER_URL=https://portainer.local npm start
+
+# Frontend (zweite Shell)
+cd frontend
+npm install
+npm run dev
+```
+Das Backend liest Umgebungsvariablen beim Start. Alternativ kannst du eine `.env` neben `backend/index.js` anlegen.
+
+## Datenbank & Migration
+- Datei: `backend/data/stackpulse.db` (SQLite, WAL aktiviert)
+- Migration: `npm run migrate` (führt `backend/db/ensure.js` aus, erzeugt/aktualisiert Schema & Defaults)
+- Backup: Datei oder Volume regelmäßig sichern; enthält Benutzer, Logs und gespeicherte Secrets
+
+## Hinweise
+- Die lokalen Builds sind für Entwicklung gedacht. Für Deployments verwende `ghcr.io/mboehmlaender/stackpulse`.
+- Einige Einstellungen (z. B. Server-URL, API-Key, SSH-Config) kannst du im UI setzen; für lokale Tests reichen die ENV-Defaults und das Setup-UI.

docs/operations.md

@@ -0,0 +1,50 @@
+# Operations & Wartung
+
+Dieser Abschnitt deckt typische Aufgaben für Betriebsteams ab – von Backups über Wartungsmodus bis zu Störungssuche.
+
+**Relevante Rechte**
+- `Superuser löschen`
+- `Bereich & Navigation (Wartung)`
+
+## Laufender Betrieb
+- **Services überwachen**: StackPulse stellt nur einen Prozess bereit (Node.js/Express). Nutze Systemd/Docker Healthchecks, indem du regelmäßig `/api/auth/session` (für Auth) oder `/api/maintenance/update-status` (für Backend + DB) abfragst.
+- **Ports**: Standardmäßig lauscht nur Port 4001 (HTTP + Socket.IO). Hinter einem Reverse Proxy sollte TLS terminiert werden.
+- **Protokolle**: Das Backend loggt ausführlich auf STDOUT/STDERR (`console.log`). Sammle diese via Docker-Logs oder Journal.
+
+## Backups & Wiederherstellung
+1. **Container-Setup**: Mount `backend/data` via benanntem Volume (siehe `docker-compose.yml`).
+2. **Backup**: Stoppe kurz den Container oder nutze `sqlite3 stackpulse.db ".backup 'stackpulse.db.bak'"` innerhalb der laufenden Instanz.
+3. **Restore**: Ersetze die Datei im Volume und starte die App neu. Beim ersten Start führt `ensureDatabaseSchema` automatisch eventuelle Nachmigrationen aus.
+
+## Benutzer- & Rechteverwaltung
+- Superuser können über `/api/auth/superuser/*` oder im UI registriert werden. Entfernen ist nur mit `Superuser löschen` möglich.
+- Benutzerkonten lassen sich temporär deaktivieren (`/api/users/:id/active`). Die Historie bleibt erhalten.
+- Sicherheitsphrasen sind notwendig für Passwort-Reset. Admins können neue Phrasen erzeugen (`/api/users/:id/security-phrase/renew`), müssen diese aber dem Benutzer sicher zustellen.
+
+## Wartungsmodus & Updates
+- Maintenance Mode aktivieren: `curl -X POST http://host:4001/api/maintenance/mode -H 'Content-Type: application/json' -d '{"active":true,"message":"Cluster Upgrade"}'` (Recht `Bereich & Navigation (Wartung)`). Das UI informiert alle Nutzer und blockiert Redeploys.
+- SSH-/Update-Setup: Hinterlege Host, Port, Benutzer, Passwort (optional) und zusätzliche SSH-Argumente. Passwörter werden verschlüsselt gespeichert (`PORTAINER_SSH_SECRET`).
+- Update-Skript: Das Default-Skript (`DEFAULT_PORTAINER_UPDATE_SCRIPT`) führt `docker stop`, `docker run` etc. aus. Du kannst im UI oder via API ein eigenes Skript setzen – wird erst aktualisiert, wenn kein Update läuft.
+- Update anstoßen: `POST /api/maintenance/portainer-update` triggert die SSH-Kommandos. Status & Logausgaben können über `/api/maintenance/update-status` überwacht werden.
+
+## Logs & Compliance
+- Ereignislogs enthalten jede Redeploy-, Auth- und Verwaltungsaktion. Export über `GET /api/logs/export` (CSV) oder automatisiert mittels Cron (Query-Parameter übernehmen Filter).
+- Datenbereinigung: Nutze `DELETE /api/logs/:id` oder `DELETE /api/logs?before=<ISO>` um alte Einträge zu entfernen. Achtung: Aktionen sind nicht reversibel.
+- Für Offload kannst du per Script regelmäßig Exporte ziehen und anschließend löschen.
+
+## Troubleshooting
+| Symptom | Prüfschritte |
+|---------|--------------|
+| **Setup schlägt fehl (PORTAINER_URL_NOT_CONFIGURED)** | Stelle sicher, dass entweder `PORTAINER_URL` gesetzt ist oder im Setup-UI ein Server gespeichert wurde (`servers`-Tabelle prüfen). |
+| **Redeploy hängt in `queued`** | `/api/maintenance/update-status` auf laufende Updates prüfen, `redeployingStacks` im Log verfolgen; ggf. Portainer-API erreichbar? |
+| **Login nicht möglich** | Über `backend/logs` nach Auth-Fehlern suchen, Cookie-Konfiguration prüfen (`AUTH_COOKIE_SECURE` bei HTTP?). |
+| **SSH-Test fehlgeschlagen** | `POST /api/maintenance/test-ssh` mit temporären Credentials testen, Container-Logs auf `SSH Test fehlgeschlagen` untersuchen. |
+| **SQLite Locked** | Stelle sicher, dass kein paralleler Backup-Prozess läuft. WAL-Modus erlaubt mehrere Leser, blockiert aber bei langen Schreibtransaktionen (Check Logs auf `SQLITE_BUSY`). |
+
+## Sicherheitsempfehlungen
+- Setze `AUTH_COOKIE_SECURE=true` hinter TLS und konfiguriere einen Reverse Proxy (z. B. Traefik, Nginx).
+- Isoliere das Admin-Interface durch VPN oder IP-Filter.
+- Drehe API-Keys regelmäßig: `/api/setup/servers/:id/api-key` aktualisiert Schlüssel ohne Neuinstallation.
+- Nutze dedizierte StackPulse-Benutzer in Portainer, damit Berechtigungen klar getrennt bleiben.
+
+Mit diesen Richtlinien lässt sich StackPulse sicher betreiben und warten.

docs/user-guide/groups.md

@@ -0,0 +1,46 @@
+# Benutzergruppen & Rechte
+
+Dieser Bereich verwaltet Rollenmodelle und bestimmt, welche Aktionen Benutzer:innen durchführen dürfen.
+
+**Relevante Rechte**
+- `Bereich & Navigation (Benutzergruppen)`
+- `Benutzergruppen bearbeiten`
+- `Benutzergruppen löschen`
+
+## Gruppen anlegen
+1. Button **Gruppe erstellen** wählen.
+2. Pflichtfelder:
+   - **Name** (z. B. „Ops Team“)
+   - **Beschreibung** (Hilfestellung für Kolleg:innen)
+3. Optional Tag-Farbe oder Icon setzen (für bessere Übersicht in der Benutzerliste).
+4. Speichern – die Gruppe erscheint sofort in der Übersicht.
+
+## Gruppen bearbeiten
+- Zeile anklicken, um das Detailpanel zu öffnen.
+- Du kannst Name, Beschreibung und Zugehörige Benutzer (nur Anzeige) sehen.
+- Zum Bearbeiten der Rechte klicke auf **Berechtigungen bearbeiten**.
+
+## Rechte vergeben
+Der Rechte-Dialog zeigt die gesamte Permissionstruktur in Kategorien (Stacks, Logs, Benutzer, Wartung etc.).
+
+1. Wähle die gewünschte Kategorie aus.
+2. Setze für jede Permission einen Level:
+   - **none** – kein Zugriff
+   - **read** – Zugriff auf Ansicht/Lesen
+   - **full** – volle Bearbeitungsrechte
+3. Abhängigkeiten werden automatisch hervorgehoben. Beispiel: Um `Logs löschen` nutzen zu dürfen, muss `Bereich & Navigation (Logs)` mindestens `Vollzugriff` sein.
+4. Speichern bestätigt die Anpassungen. StackPulse aktualisiert sofort die effektiven Rechte aller Benutzer in dieser Gruppe.
+
+## Benutzer zu Gruppen hinzufügen
+- Dies geschieht im Benutzer-Detailpanel (siehe [Benutzerverwaltung](users.md)).
+- Die Liste zeigt alle vorhandenen Gruppen; ein Benutzer kann mehreren Gruppen angehören.
+- Die effektiven Rechte sind die jeweils höchsten Levels aller Gruppen.
+
+## Gruppen löschen
+- Nur möglich, wenn keine Benutzer ausschließlich von dieser Gruppe abhängen (es erfolgt ein Warnhinweis).
+- Löschen entfernt keine Benutzer, aber deren effektive Rechte können sich dadurch verringern.
+
+## Best Practices
+- Erstelle zunächst eine Basisgruppe (z. B. „Viewer“) mit Leserechten für Stacks und Logs.
+- Verwende separate Gruppen für sensible Aktionen wie Wartung oder Superuser-Verwaltung.
+- Nutze sprechende Beschreibungen, damit Kolleg:innen sofort erkennen, wofür eine Gruppe gedacht ist.

docs/user-guide/index.md

@@ -0,0 +1,13 @@
+# Benutzerhandbuch
+
+Dieses Kapitel beschreibt die Bedienung von StackPulse aus Sicht von Administrator:innen und Operators. Es orientiert sich an den Seiten im Dashboard und erklärt für jeden Bereich typische Abläufe sowie die notwendigen Berechtigungen. Screenshots kannst du später ergänzen; die Texte nennen bereits alle Buttons, Eingabefelder und Statusanzeigen.
+
+**Reihenfolge**
+1. [Setup](setup.md) – richtet Portainer-Anbindung und Superuser ein.
+2. [Stacks](stacks.md) – zeigt alle Stacks, Redeploy-Aktionen und Filter.
+3. [Logs](logs.md) – Nachvollziehbarkeit, Filter & Export.
+4. [Wartung](maintenance.md) – Maintenance-Mode, Updates und SSH-Konfiguration.
+5. [Benutzer](users.md) – Konten verwalten, Phrasen ausgeben, Passwörter setzen.
+6. [Benutzergruppen & Rechte](groups.md) – Rollen modellieren und Berechtigungen zuweisen.
+
+Jede Seite nennt die erforderlichen Permissions. Sobald du dich anmeldest, führt dich StackPulse zunächst automatisch durch den Setup-Assistenten; danach landet man auf der Stacks-Übersicht.

docs/user-guide/logs.md

@@ -0,0 +1,27 @@
+# Logs-Seite
+
+Die Logs-Seite dient der Nachvollziehbarkeit aller Aktionen (Redeploy, Login, Wartung, Benutzerverwaltung). Sie steht Benutzer:innen mit der Permission `logs-access` zur Verfügung.
+
+## Überblick
+- Filterleiste mit Suchfeld, Zeitspanne, Kategorie und Status.
+- Tabelle mit Severity-Farben, Nachricht, Zeitstempel und Kontextinformationen.
+- Aktionen oberhalb der Tabelle: **Exportieren** und **Löschen**.
+
+## Filtern
+1. **Zeitfenster:** Datumsfelder „Von“ und „Bis“ setzen. Standardmäßig zeigt StackPulse die letzten 24 Stunden.
+2. **Kategorie/Status:** Dropdowns nutzen, um z. B. `redeploy` oder `wartung` auszuwählen.
+3. **Freitext:** Suchfeld durchsucht `message`, `entity_name` und `metadata`.
+4. **Erweiterte Filter:** Klick auf „Weitere Filter“ öffnet zusätzliche Optionen (Actor, Stack-ID, Severity).
+
+## Export
+- Button **CSV exportieren** klickst du erst, nachdem die Filter stehen. StackPulse erstellt eine CSV-Datei mit denselben Parametern.
+- Der Download startet im Browser; in containerisierten Umgebungen kannst du denselben Endpoint (`/api/logs/export`) auch automatisiert aufrufen.
+
+## Löschen
+- Einzelne Logs: Papierkorb in der Zeile (Permission `logs-delete`).
+- Batch-Löschung: Button **Gefilterte Einträge löschen**; es erscheint ein Sicherheitsdialog mit Zusammenfassung der aktiven Filter.
+- Beachte, dass gelöschte Logs nicht wiederhergestellt werden können.
+
+## Detailansicht
+- Klick auf eine Tabellenzeile, um ein Seitenpanel mit vollständigem JSON (`metadata`), Kontext (Stack, Benutzer, Quelle) und ggf. Redeploy-Timings zu öffnen.
+- Über **Stack öffnen** gelangst du direkt zur Stacks-Seite mit gesetztem Filter.

docs/user-guide/maintenance.md

@@ -0,0 +1,62 @@
+# Wartungsbereich
+
+Der Wartungsbereich bündelt Maintenance-Mode, Serververwaltung (inkl. Agent-Integration), Update-Skripte und SSH-Konfiguration. Sichtbar für Benutzer:innen mit `Bereich & Navigation (Wartung)`; Unterbereiche haben eigene Rechte:
+
+**Relevante Rechte**
+- `Bereich & Navigation (Wartung)`
+- `Server-Sektion`
+- `Server bearbeiten` / `Server löschen`
+- `SSH/Update-Skript`
+- `Update durchführen`
+- `Agent`
+- `Doppelte Stacks`
+- `mTLS Sektion`
+- `Superuser löschen`
+
+- `Server-Sektion` (lesen) zeigt die Serverübersicht.
+- `Server bearbeiten` (lesen) zeigt Server-Details inkl. Portainer-Status; Felder bleiben schreibgeschützt. Vollzugriff erlaubt Bearbeiten/Speichern.
+- `Server löschen` löscht Server (nur bei Vollzugriff).
+- `SSH/Update-Skript` und `Update durchführen` hängen am Unterpunkt Portainer/SSH und erfordern Vollzugriff auf Server-Edit.
+- `Agent` (lesen/voll) steuert die Agent-Sektion im Server-Detail.
+
+## Maintenance-Mode
+1. Schalter **Wartungsmodus aktivieren** umlegen.
+2. Jede Aktivierung/Deaktivierung wird in den Logs protokolliert.
+
+## Serververwaltung & API-Key
+- Liste zeigt alle eingetragenen Portainer-Server.
+  - **Server hinzufügen**/**bearbeiten**/**löschen** nur mit `Server bearbeiten` (Vollzugriff); löschen zusätzlich `Server löschen`.
+- Im Server-Detail:
+  - **Server-URL/Name** und **Portainer API-Key**: editierbar nur mit `Server bearbeiten` Vollzugriff; bei Leserecht sichtbar, aber gesperrt.
+  - **Self-Stack-ID**: Stack-ID von StackPulse selbst; blockiert Redeploys dieses Stacks.
+- **Status prüfen**: Live-Check gegen Portainer (Version, Edition, Update vorhanden). Sichtbar ab `Server bearbeiten` (lesen).
+
+## Agent-Integration (Portainer CE / Edge)
+Für die Community Edition von Stackpulse kannst du je Server einen StackPulse Agent hinterlegen. Er liefert Stack- und Portainer-Metadaten, wenn die Business-API fehlt. Hierzu muss auch der Agent auf dem Server der Portainer Instanz laufen. Der Agent wird für die Business Edition nicht benötigt.
+
+1. Im Server-Detail **Agent konfigurieren** öffnen.
+2. **Agent URL** eintragen, der **Agent Token** wird automatisch generiert und kann nicht geändert werden (Token = `AGENT_TOKEN` des Agents).
+StackPulse prüft Erreichbarkeit und zeigt Online-/Fehlerstatus. Sichtbar mit `Agent` lesen, Bearbeitung mit `Agent` voll.
+3. mTLS-Zertifikate verwalten:
+   - **Bootstrap-Token erzeugen** (Einmal-Token) und im Agent als `AGENT_BOOTSTRAP_TOKEN` setzen.
+   - Agent holt Zertifikate automatisch ab; Status im Zertifikate-Abschnitt.
+   - **Zertifikate anzeigen** (PEM) (nur bei entsprechenden Rechten)
+4. Portainer-Version kann gelesen werden, wenn der Agent online ist.
+
+## SSH-Konfiguration
+Erfordert `SSH/Update-Skript` (sichtbar/bearbeitbar nur bei Vollzugriff auf Server-Edit).
+1. Host, Port, Benutzername und Passwort sowie eventuell notwendige Extra-Argumente eintragen.
+2. Passwort wird verschlüsselt gespeichert.
+3. **Verbindung testen** prüft Erreichbarkeit und meldet Ergebnis direkt.
+
+## Update-Skript & Portainer-Update
+- Standard-Skript ist sichtbar und kann überschrieben werden (Recht `SSH/Update-Skript` + Server-Edit Vollzugriff). **Zurücksetzen** stellt den Standard wieder her.
+- Start eines Updates (`Update durchführen` + Server-Edit Vollzugriff):
+  1) Wartungsmodus wird automatisch aktiviert.
+  2) SSH-Konfiguration und Skript prüfen.
+  3) **Update starten** klicken. Der Fortschritt und die Logausgaben erscheinen im Fenster.
+  4) Während ein Update läuft, sind Änderungen am System gesperrt.
+
+## Fehlerbehandlung
+- SSH-/Update-Fehler werden mit Klartextausgabe angezeigt. Bei Bedarf Host/Port/User, Passwort oder Skript anpassen.
+- Agent offline: URL/Token prüfen, Bootstrap-Token ggf. neu erzeugen und den Agent neu starten.

docs/user-guide/setup.md

@@ -0,0 +1,35 @@
+# Setup-Assistent
+
+Beim ersten Start erscheint automatisch der Setup-Bereich und führt dich durch alle Schritte, bis die Einrichtung abgeschlossen ist.
+
+## Voraussetzungen
+- Portainer Business Edition mit gültigem API-Key
+- Superuser-Zugangsdaten (entweder schon per Umgebungsvariablen gesetzt oder über diesen Assistenten festlegen)
+
+## Schritt 1: Portainer-Server anlegen
+1. Formularfelder **Server-URL** und optional **Name** ausfüllen.
+   - URL inkl. Protokoll (z. B. `https://portainer.example.com`).
+   - Bezeichnung dient ausschließlich als Anzeige im Dashboard.
+2. Auf **Verbindung testen** klicken.
+   - Erfolgreich: grüner Hinweis, die Endpoints werden erkannt.
+   - Fehlgeschlagen: Fehlermeldung prüfen (häufig Zertifikats-/Firewall-Themen).
+3. Mit **Speichern & Weiter** bestätigst du den Servereintrag. StackPulse legt ihn verschlüsselt in SQLite ab.
+
+## Schritt 2: API-Key hinterlegen
+1. API-Key im Feld **Portainer API Key** einfügen.
+2. Optional kannst du über **Stacks laden** kontrollieren, ob Portainer Stacks zurückliefert.
+3. Mit **Speichern** wird der Schlüssel verschlüsselt gespeichert. Du kannst ihn später im Maintenance-Bereich austauschen.
+
+## Schritt 3: Superuser registrieren
+1. Falls du `SUPERUSER_*` Variablen gesetzt hast, zeigt StackPulse an, dass bereits ein Superuser existiert – du kannst direkt weiter.
+2. Ansonsten Benutzername, E-Mail und Passwort vergeben. Das Passwort dient nur für diesen Account; weitere Benutzer folgen später.
+3. Auf **Superuser anlegen** klicken. Nach Erfolg wird der Login-Button eingeblendet.
+
+## Abschluss & Login
+- Sobald alle drei Schritte abgeschlossen sind, erscheint die Schaltfläche **Zum Login**.
+- Melde dich mit dem Superuser an. StackPulse legt im Hintergrund initiale Berechtigungen, Default-Gruppen und Sicherheitspassphrasen an.
+
+## Setup wiederholen oder ändern
+- Über das Dashboard → **Wartung** → Abschnitt *Serververwaltung* kannst du zusätzliche Portainer-Server hinzufügen oder entfernen.
+- Superuser lässt sich im Bereich **Benutzer** löschen, sofern du das Recht `Superuser löschen` besitzt.
+- Der Self-Stack (StackPulse-eigener Stack) kann in der Wartung gepflegt werden, damit er nicht versehentlich redeployed wird.

docs/user-guide/stacks.md

@@ -0,0 +1,41 @@
+# Stacks-Seite
+
+Die Stacks-Ansicht ist der Startpunkt nach dem Login und liefert einen Überblick über alle Stacks der angebundenen Portainer-Instanz.
+
+**Relevante Rechte**
+- `Redeploy einzeln`
+- `Redeploy Auswahl`
+- `Redeploy Alle`
+
+## Aufbau
+- **Header** mit Suchfeld, Filterchips für Status sowie Buttons für Redeploy-Aktionen.
+- **Tabelle** mit Name, Endpoint, Status, letzte Aktion, Redeploy-Status und verfügbaren Buttons.
+- **Live-Status**: Über Socket.IO wird jede Veränderung (queued/started/success/error) sofort eingeblendet.
+
+## Filter & Suche
+1. Verwende das Suchfeld oben rechts, um nach Namen oder IDs zu filtern.
+2. Statuschips (z. B. „running“, „warning“) toggeln per Klick und lassen sich kombinieren.
+3. Über die Spaltenköpfe kannst du sortieren; ein erneuter Klick kehrt die Reihenfolge um.
+
+## Redeploy-Aktionen
+| Aktion | Voraussetzung | Vorgehen |
+|--------|---------------|----------|
+| **Einzelner Stack** | Recht `Redeploy einzeln` | Button **Redeploy** in der jeweiligen Zeile klicken und bestätigen. |
+| **Mehrere Stacks** | Recht `Redeploy Auswahl` | Checkboxen der gewünschten Stacks aktivieren, anschließend **Redeploy Auswahl**. |
+| **Alle Stacks** | Recht `Redeploy Alle` | Button **Redeploy alle** auslösen. Nutze vorher Filter, um sicherzugehen, dass alle Stacks korrekt angezeigt werden. |
+
+Während eines Redeploys erscheint pro Stack ein Fortschrittsbadge. Du kannst das Panel schließen; beim nächsten Besuch wird der aktuelle Status aus dem Backend gelesen.
+
+## Redeploy-Status verstehen
+- **Queued** – Auftrag ist vorgemerkt.
+- **Started** – Portainer verarbeitet Redeploy.
+- **Success** – Vorgang erfolgreich abgeschlossen.
+- **Error** – Fehlerdetails findest du in der Logs-Seite.
+- **Info** – Informative Hinweise, etwa wenn Portainer einen Stack überspringt.
+
+## Selbstschutz
+- Falls du die Variable `SELF_STACK_ID` gesetzt hast, markiert StackPulse den eigenen Stack als „geschützt“. Redeploy-Buttons werden deaktiviert und mit einem Info-Tooltip versehen.
+
+## Troubleshooting aus der Ansicht
+- Klicke auf das Warnsymbol in der Tabellenzeile, um Fehlerdetails einzublenden.
+- Nutze den Link „Zu Logs springen“, der direkt eine gefilterte Ansicht in der Log-Seite öffnet (Stack-ID ist vorausgewählt).

docs/user-guide/users.md

@@ -0,0 +1,39 @@
+# Benutzerverwaltung
+
+Die Benutzerseite ermöglicht das Anlegen, Bearbeiten und Deaktivieren von Konten. Du benötigst mindestens die Permission `users-access` (lesen) bzw. `users-edit`/`users-delete` für Änderungen.
+
+## Benutzer anlegen
+1. Button **Benutzer anlegen** klicken.
+2. Formularfelder ausfüllen:
+   - Benutzername (eindeutig, wird für Login genutzt)
+   - Anzeigename (optional)
+   - E-Mail-Adresse
+   - Passwort (kann später geändert werden)
+   - Gruppen auswählen (siehe Abschnitt „Benutzergruppen“)
+3. Optional: Benutzer sofort aktivieren/deaktivieren.
+4. Mit **Speichern** bestätigen. Der Benutzer erscheint in der Tabelle und erhält automatisch eine Sicherheitspassphrase.
+
+## Benutzer bearbeiten
+- In der Tabelle auf eine Zeile klicken, um das Detailpanel zu öffnen.
+- Du kannst Anzeigename, E-Mail, Passwort und Gruppen ändern.
+- Änderungen an Gruppen erfordern `users-edit` sowie Gruppenrechte (`user-groups-access`).
+
+## Konto deaktivieren/reaktivieren
+- Toggle **Aktiv** im Detailpanel.
+- Deaktivierte Konten können sich nicht mehr anmelden, bleiben aber in der Historie.
+
+## Sicherheitspassphrase
+1. Button **Sicherheitspassphrase anzeigen** im Detailpanel.
+2. StackPulse zeigt einen QR-Code und den alphanumerischen Code. Dieser wird nur einmal angezeigt, bis du bestätigst, dass er heruntergeladen wurde.
+3. Über **Neu generieren** kannst du eine neue Phrase erstellen (Permission `users-security-phrase`). Informiere den Benutzer über die neue Phrase und markiere anschließend „heruntergeladen“.
+
+## Passwort zurücksetzen
+- Admins können direkt im Detailpanel ein neues Passwort setzen.
+- Benutzer:innen selbst nutzen die Auth-Seite „Passwort vergessen“: Sie geben Username + Sicherheitsphrase ein und definieren anschließend ein neues Passwort.
+
+## Suche & Filter
+- Nutze das Suchfeld, um nach Benutzername oder E-Mail zu suchen.
+- Filterchips für Status (aktiv/inaktiv) erleichtern das Auffinden gesperrter Accounts.
+
+## Massenaktionen
+- Mehrfachauswahl (Checkboxen) erlaubt das gleichzeitige Aktivieren/Deaktivieren oder Löschen mehrerer Benutzer. Vorsicht: Löschen entfernt auch Audit-Verweise.

frontend/src/components/AuthProvider.jsx

@@ -23,10 +23,52 @@ const normalizePermissions = (raw) => {
   }, {});
 };
 
+const normalizeServerPermissions = (raw) => {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return {};
+  }
+  return Object.entries(raw).reduce((acc, [serverId, value]) => {
+    const numericId = Number(serverId);
+    if (!Number.isFinite(numericId)) {
+      return acc;
+    }
+    const permissionMap = value?.permissions && typeof value.permissions === "object"
+      ? value.permissions
+      : value;
+    acc[numericId] = {
+      permissions: normalizePermissions(permissionMap),
+      groupId: Number.isFinite(Number(value?.groupId)) ? Number(value.groupId) : null,
+      useGlobalGroup: Boolean(value?.useGlobalGroup)
+    };
+    return acc;
+  }, {});
+};
+
+const normalizeServerAssignments = (raw) => {
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  return raw
+    .map((entry) => {
+      const serverId = Number(entry?.serverId ?? entry?.server_id ?? entry?.id);
+      if (!Number.isFinite(serverId)) return null;
+      return {
+        serverId,
+        groupId: Number.isFinite(Number(entry?.groupId ?? entry?.group_id)) ? Number(entry?.groupId ?? entry?.group_id) : null,
+        useGlobalGroup: Boolean(entry?.useGlobalGroup ?? entry?.use_global_group),
+        serverName: entry?.serverName || entry?.server_name || null,
+        serverUrl: entry?.serverUrl || entry?.server_url || null
+      };
+    })
+    .filter(Boolean);
+};
+
 export function AuthProvider({ children }) {
   const [state, setState] = useState({
     user: null,
     permissions: {},
+    serverPermissions: {},
+    serverAssignments: [],
     loading: false,
     error: null,
     lastErrorCode: null,
@@ -36,9 +78,13 @@ export function AuthProvider({ children }) {
   const setSession = useCallback((payload) => {
     const user = payload?.user ?? null;
     const permissions = normalizePermissions(payload?.permissions);
+    const serverPermissions = normalizeServerPermissions(payload?.serverPermissions);
+    const serverAssignments = normalizeServerAssignments(payload?.serverAssignments ?? user?.serverAssignments);
     setState({
       user,
       permissions,
+      serverPermissions,
+      serverAssignments,
       loading: false,
       error: null,
       lastErrorCode: null,
@@ -50,6 +96,8 @@ export function AuthProvider({ children }) {
     setState((prev) => ({
       user: null,
       permissions: {},
+      serverPermissions: {},
+      serverAssignments: [],
       loading: false,
       error: null,
       lastErrorCode: null,
@@ -80,6 +128,8 @@ export function AuthProvider({ children }) {
           error: payload?.error ?? null,
           lastErrorCode: payload?.error ?? null,
           initialized: true,
+          serverPermissions: {},
+          serverAssignments: []
         });
         return { ok: false, status: response.status, error: payload?.error ?? null };
       }
@@ -89,9 +139,11 @@ export function AuthProvider({ children }) {
     } catch (err) {
       const message = err?.message || "NETWORK_ERROR";
       setState({
-        user: null,
-        permissions: {},
-        loading: false,
+      user: null,
+      permissions: {},
+      serverPermissions: {},
+      serverAssignments: [],
+      loading: false,
         error: message,
         lastErrorCode: "NETWORK_ERROR",
         initialized: true,
@@ -140,10 +192,36 @@ export function AuthProvider({ children }) {
     [state.permissions, state.user]
   );
 
+  const hasServerPermission = useCallback(
+    (serverId, permissionKey, requiredLevel = "full") => {
+      if (!permissionKey) {
+        return true;
+      }
+      if (state.user?.isSuperuser) {
+        return true;
+      }
+      const numericServerId = Number(serverId);
+      let permissionMap = null;
+      if (Number.isFinite(numericServerId)) {
+        const entry = state.serverPermissions?.[numericServerId] || state.serverPermissions?.[String(numericServerId)];
+        if (entry?.permissions && typeof entry.permissions === "object") {
+          permissionMap = entry.permissions;
+        }
+      }
+      const basePermissions = permissionMap || state.permissions || {};
+      const current = basePermissions[permissionKey] ?? "none";
+      const currentPriority = LEVEL_PRIORITY[current] ?? 0;
+      const requiredPriority = LEVEL_PRIORITY[requiredLevel] ?? LEVEL_PRIORITY.full;
+      return currentPriority >= requiredPriority;
+    },
+    [state.serverPermissions, state.permissions, state.user]
+  );
+
   const value = useMemo(
     () => ({
       user: state.user,
       permissions: state.permissions,
+      serverPermissions: state.serverPermissions,
       loading: state.loading,
       error: state.error,
       lastErrorCode: state.lastErrorCode,
@@ -154,8 +232,10 @@ export function AuthProvider({ children }) {
       clearSession,
       logout,
       hasPermission,
+      hasServerPermission,
+      serverAssignments: state.serverAssignments,
     }),
-    [state, refreshSession, setSession, clearSession, logout, hasPermission]
+    [state, refreshSession, setSession, clearSession, logout, hasPermission, hasServerPermission]
   );
 
   return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;

frontend/src/layouts/dashboard.jsx

@@ -12,6 +12,7 @@ import routes from "@/routes";
 import { UserDetails } from "@/pages/dashboard/userDetails.jsx";
 import { UserGroupDetail } from "@/pages/dashboard/userGroupDetail.jsx";
 import { SecurityPhrase } from "@/pages/dashboard/securityPhrase.jsx";
+import { ServerDetail } from "@/pages/dashboard/serverDetail.jsx";
 import { useMaterialTailwindController, setOpenConfigurator } from "@/components";
 import { useAuth } from "@/components/AuthProvider.jsx";
 import PermissionGate from "@/components/PermissionGate.jsx";
@@ -210,6 +211,14 @@ export function Dashboard() {
               </PermissionGate>
             }
           />
+          <Route
+            path="maintenance/servers/:serverId"
+            element={
+              <PermissionGate permission="maintenance-server-manage" requiredLevel="read">
+                <ServerDetail />
+              </PermissionGate>
+            }
+          />
         </Routes>
         {!isSecurityPhraseRoute && (
           <div className="text-blue-gray-600">

frontend/src/pages/dashboard/index.js

@@ -6,3 +6,4 @@ export * from "@/pages/dashboard/usergroups";
 export * from "@/pages/dashboard/userDetails";
 export * from "@/pages/dashboard/userGroupDetail";
 export * from "@/pages/dashboard/securityPhrase";
+export * from "@/pages/dashboard/serverDetail";

frontend/src/pages/dashboard/userDetails.jsx

@@ -14,7 +14,6 @@ import {
 } from "@material-tailwind/react";
 
 import { useToast } from "@/components/ToastProvider.jsx";
-import { platformSettingsData } from "@/data";
 import { AVATAR_COLORS } from "@/data/avatarColors.js";
 import { useMaintenance } from "@/components/MaintenanceProvider.jsx";
 import { useAuth } from "@/components/AuthProvider.jsx";
@@ -69,6 +68,47 @@ const mapUser = (item) => ({
     securityPhraseDownloadedAt: item?.securityPhraseDownloadedAt || null
 });
 
+const normalizeServer = (item) => {
+    if (!item || typeof item !== "object") {
+        return null;
+    }
+    const id = Number(item.id ?? item.serverId ?? item.server_id);
+    if (!Number.isFinite(id)) {
+        return null;
+    }
+    const name = item.name || item.serverName || item.server_name || `Server ${id}`;
+    return {
+        id,
+        name,
+        url: item.url || item.serverUrl || item.server_url || ""
+    };
+};
+
+const normalizeAssignmentsList = (list, servers = []) => {
+    const serverMap = new Map(servers.map((server) => [server.id, server]));
+    if (!Array.isArray(list)) {
+        return [];
+    }
+    return list
+        .map((entry) => {
+            const serverId = Number(entry?.serverId ?? entry?.server_id);
+            if (!Number.isFinite(serverId)) {
+                return null;
+            }
+            const groupId = Number(entry?.groupId ?? entry?.group_id);
+            const serverFallback = serverMap.get(serverId);
+            return {
+                serverId,
+                serverName: entry?.serverName || entry?.server_name || serverFallback?.name || "",
+                serverUrl: entry?.serverUrl || entry?.server_url || serverFallback?.url || "",
+                groupId: Number.isFinite(groupId) ? groupId : null,
+                groupName: entry?.groupName || entry?.group_name || "",
+                useGlobalGroup: Boolean(entry?.useGlobalGroup ?? entry?.use_global_group)
+            };
+        })
+        .filter(Boolean);
+};
+
 const extractPrimaryGroupId = (user) => {
     if (!user || !Array.isArray(user.groups) || user.groups.length === 0) {
         return null;
@@ -123,6 +163,11 @@ export function UserDetails() {
     const [securityPhraseLoading, setSecurityPhraseLoading] = useState(false);
     const [securityPhraseError, setSecurityPhraseError] = useState("");
     const [renewingSecurityPhrase, setRenewingSecurityPhrase] = useState(false);
+    const [serverAssignments, setServerAssignments] = useState([]);
+    const [availableServers, setAvailableServers] = useState([]);
+    const [assignmentsError, setAssignmentsError] = useState("");
+    const [savingAssignments, setSavingAssignments] = useState(false);
+    const initialAssignmentsRef = useRef([]);
 
     const maintenanceActive = Boolean(maintenanceMeta?.active);
     const maintenanceMessage = maintenanceMeta?.message;
@@ -172,11 +217,22 @@ export function UserDetails() {
             if (!item.id) {
                 throw new Error("USER_NOT_FOUND");
             }
+            const normalizedServers = Array.isArray(response.data?.servers)
+                ? response.data.servers.map(normalizeServer).filter(Boolean)
+                : [];
+            setAvailableServers(normalizedServers);
+            const normalizedAssignments = normalizeAssignmentsList(
+                response.data?.item?.serverAssignments ?? response.data?.serverAssignments ?? [],
+                normalizedServers
+            );
+            initialAssignmentsRef.current = normalizedAssignments;
+            setServerAssignments(normalizedAssignments);
+            setAssignmentsError("");
             setUser(item);
             setSecurityPhraseWords([]);
             setSecurityPhraseDownloadedAt(item.securityPhraseDownloadedAt || null);
             setSecurityPhraseError("");
-        const initialValues = buildInitialFormValues(item);
+            const initialValues = buildInitialFormValues(item);
             initialFormValuesRef.current = { ...initialValues };
             setFormValues(initialValues);
             setSaveError("");
@@ -195,6 +251,9 @@ export function UserDetails() {
             setUser(null);
             initialFormValuesRef.current = buildInitialFormValues(null);
             setFormValues(buildInitialFormValues(null));
+            setServerAssignments([]);
+            setAvailableServers([]);
+            setAssignmentsError("");
             setError(message);
             showToast({
                 variant: "error",
@@ -341,6 +400,208 @@ export function UserDetails() {
         }));
     }, [canEditUsers]);
 
+    const assignmentsChanged = useMemo(() => {
+        const serialize = (list) =>
+            JSON.stringify(
+                list
+                    .map((entry) => ({
+                        serverId: Number(entry.serverId) || null,
+                        groupId: entry.useGlobalGroup ? null : (Number(entry.groupId) || null),
+                        useGlobalGroup: Boolean(entry.useGlobalGroup)
+                    }))
+                    .sort((a, b) => (a.serverId || 0) - (b.serverId || 0))
+            );
+        return serialize(serverAssignments) !== serialize(initialAssignmentsRef.current);
+    }, [serverAssignments]);
+
+    const usedServerIds = useMemo(
+        () =>
+            new Set(
+                serverAssignments
+                    .map((entry) => Number(entry.serverId))
+                    .filter((value) => Number.isFinite(value) && value > 0)
+            ),
+        [serverAssignments]
+    );
+
+    const getServerOptionsForRow = useCallback(
+        (currentServerId) => {
+            return availableServers.filter(
+                (server) => server.id === currentServerId || !usedServerIds.has(server.id)
+            );
+        },
+        [availableServers, usedServerIds]
+    );
+
+    const handleAddAssignment = useCallback(() => {
+        if (!canEditUsers || isSuperuserUser) return;
+        const usedServerIds = new Set(
+            serverAssignments
+                .map((entry) => Number(entry.serverId))
+                .filter((value) => Number.isFinite(value) && value > 0)
+        );
+        const nextServer = availableServers.find((server) => !usedServerIds.has(server.id));
+        if (!nextServer) {
+            setAssignmentsError("Alle verfügbaren Server sind bereits zugeordnet.");
+            return;
+        }
+        setAssignmentsError("");
+        setServerAssignments((prev) => [
+            ...prev,
+            {
+                serverId: nextServer.id,
+                serverName: nextServer.name ?? "",
+                serverUrl: nextServer.url ?? "",
+                groupId: null,
+                groupName: "",
+                useGlobalGroup: true
+            }
+        ]);
+    }, [canEditUsers, serverAssignments, availableServers]);
+
+    const handleAssignmentServerChange = useCallback(
+        (index, value) => {
+            if (!canEditUsers || isSuperuserUser) return;
+            const numeric = Number(value);
+            const server = availableServers.find((item) => item.id === numeric);
+            setServerAssignments((prev) =>
+                prev.map((entry, idx) =>
+                    idx === index
+                        ? {
+                              ...entry,
+                              serverId: Number.isFinite(numeric) ? numeric : null,
+                              serverName: server?.name || entry.serverName,
+                              serverUrl: server?.url || entry.serverUrl
+                          }
+                        : entry
+                )
+            );
+        },
+        [availableServers, canEditUsers]
+    );
+
+    const handleAssignmentGroupChange = useCallback(
+        (index, value) => {
+            if (!canEditUsers || isSuperuserUser) return;
+            const numeric = Number(value);
+            setServerAssignments((prev) =>
+                prev.map((entry, idx) =>
+                    idx === index
+                        ? {
+                              ...entry,
+                              groupId: Number.isFinite(numeric) ? numeric : null,
+                              useGlobalGroup: false
+                          }
+                        : entry
+                )
+            );
+        },
+        [canEditUsers]
+    );
+
+    const handleAssignmentUseGlobalToggle = useCallback(
+        (index, checked) => {
+            if (!canEditUsers || isSuperuserUser) return;
+            setServerAssignments((prev) =>
+                prev.map((entry, idx) =>
+                    idx === index
+                        ? {
+                              ...entry,
+                              useGlobalGroup: Boolean(checked),
+                              groupId: checked ? null : entry.groupId
+                          }
+                        : entry
+                )
+            );
+        },
+        [canEditUsers]
+    );
+
+    const handleRemoveAssignment = useCallback(
+        (index) => {
+            if (!canEditUsers || isSuperuserUser) return;
+            setServerAssignments((prev) => prev.filter((_, idx) => idx !== index));
+        },
+        [canEditUsers, isSuperuserUser]
+    );
+
+    const handleSaveAssignments = useCallback(async () => {
+        if (!canEditUsers || !numericUserId || !assignmentsChanged || isSuperuserUser) {
+            return;
+        }
+
+        const normalizedPayload = [];
+        const seenServers = new Set();
+        for (const assignment of serverAssignments) {
+            const serverId = Number(assignment.serverId);
+            if (!Number.isFinite(serverId) || serverId <= 0) {
+                setAssignmentsError("Bitte wähle für jede Zuordnung einen Server aus.");
+                return;
+            }
+            if (seenServers.has(serverId)) {
+                setAssignmentsError("Jeder Server kann nur einmal zugeordnet werden.");
+                return;
+            }
+            seenServers.add(serverId);
+            const useGlobalGroup = Boolean(assignment.useGlobalGroup);
+            const groupId = Number(assignment.groupId);
+            if (!useGlobalGroup && (!Number.isFinite(groupId) || groupId <= 0)) {
+                setAssignmentsError("Bitte wähle eine Rechtegruppe oder aktiviere die globale Gruppe.");
+                return;
+            }
+            normalizedPayload.push({
+                serverId,
+                groupId: useGlobalGroup ? null : groupId,
+                useGlobalGroup
+            });
+        }
+
+        setAssignmentsError("");
+        setSavingAssignments(true);
+
+        try {
+            const response = await axios.put(
+                `/api/users/${numericUserId}/server-assignments`,
+                { assignments: normalizedPayload }
+            );
+            const normalizedAssignments = normalizeAssignmentsList(
+                response.data?.items ?? [],
+                availableServers
+            );
+            initialAssignmentsRef.current = normalizedAssignments;
+            setServerAssignments(normalizedAssignments);
+            showToast({
+                variant: "success",
+                title: "Serverzuordnungen gespeichert",
+                description: "Die Zuordnungen wurden erfolgreich aktualisiert."
+            });
+        } catch (err) {
+            const serverError = err.response?.data?.error;
+            let message = "Die Serverzuordnungen konnten nicht gespeichert werden.";
+            if (serverError === "USER_NOT_FOUND") {
+                message = "Der Benutzer wurde nicht gefunden.";
+            } else if (serverError === "INVALID_USER_ID") {
+                message = "Die Benutzer-ID ist ungültig.";
+            } else if (serverError === "USER_SUPERUSER_PROTECTED") {
+                message = "Für den Superuser können keine Server-Zuordnungen gesetzt werden.";
+            } else if (serverError === "SERVER_NOT_FOUND") {
+                message = "Ein ausgewählter Server existiert nicht mehr.";
+            } else if (serverError === "GROUP_NOT_FOUND") {
+                message = "Eine ausgewählte Rechtegruppe existiert nicht mehr.";
+            } else if (serverError === "INSUFFICIENT_PERMISSIONS") {
+                message = "Keine Berechtigung zum Ändern der Zuordnungen.";
+            }
+            setAssignmentsError(message);
+            showToast({
+                variant: "error",
+                title: "Speichern fehlgeschlagen",
+                description: message
+            });
+        } finally {
+            setSavingAssignments(false);
+        }
+    }, [canEditUsers, numericUserId, serverAssignments, availableServers, assignmentsChanged, showToast]);
+
     const handleSaveUser = useCallback(async () => {
         if (!canEditUsers || !user || !hasChanges) {
             return;
@@ -775,30 +1036,171 @@ export function UserDetails() {
                             </div>
                             <div>
                                 <Typography variant="h6" color="blue-gray" className="mb-3">
-                                    Platform Settings
+                                    Server-Zuordnungen
                                 </Typography>
-                                <div className="flex flex-col gap-12">
-                                    {platformSettingsData.map(({ title, options }) => (
-                                        <div key={title}>
-                                            <Typography className="mb-4 block text-xs font-semibold uppercase text-blue-gray-500">
-                                                {title}
-                                            </Typography>
-                                            <div className="flex flex-col gap-6">
-                                                {options.map(({ checked, label }) => (
-                                                    <Switch
-                                                        key={label}
-                                                        id={label}
-                                                        label={label}
-                                                        defaultChecked={checked}
-                                                        labelProps={{
-                                                            className: "text-sm font-normal text-blue-gray-500",
-                                                        }}
-                                                    />
-                                                ))}
+                                {isSuperuserUser ? (
+                                    <div className="mb-4 rounded-lg border border-amber-200 bg-amber-50 px-4 py-3 text-sm text-amber-800">
+                                        Für den Superuser gelten immer alle Rechte und es können keine server-spezifischen Zuordnungen gesetzt werden.
+                                    </div>
+                                ) : (
+                                    <>
+                                        <Typography className="mb-4 text-sm text-blue-gray-500">
+                                            Ohne Zuordnungen hat der Benutzer Zugriff auf alle Server mit seinen globalen Rechten.
+                                            Lege hier Server-spezifische Gruppen fest oder markiere den Server explizit zur Nutzung der globalen Gruppe.
+                                        </Typography>
+                                        {assignmentsError && (
+                                            <div className="mb-4 rounded-lg border border-red-200 bg-red-50 px-4 py-3 text-sm text-red-800">
+                                                {assignmentsError}
                                             </div>
+                                        )}
+                                        <div className="flex flex-col gap-4">
+                                            {serverAssignments.length === 0 ? (
+                                                <div className="rounded-lg border border-blue-gray-100 bg-blue-gray-50/60 px-4 py-3 text-sm text-blue-gray-600">
+                                                    Keine Server zugeordnet. Die globalen Gruppen gelten für alle Server.
+                                                </div>
+                                            ) : (
+                                                serverAssignments.map((assignment, index) => {
+                                                    const serverOptions = getServerOptionsForRow(assignment.serverId);
+                                                    const groupSelectValue =
+                                                        assignment.useGlobalGroup || !assignment.groupId
+                                                            ? ""
+                                                            : String(assignment.groupId);
+                                                    return (
+                                                        <div
+                                                            key={`assignment-${assignment.serverId ?? index}-${index}`}
+                                                            className="rounded-lg border border-blue-gray-100 bg-white px-4 py-3 shadow-sm"
+                                                        >
+                                                            <div className="grid gap-4 md:grid-cols-2">
+                                                                <div>
+                                                                    <Typography className="mb-2 block text-xs font-semibold uppercase text-blue-gray-500">
+                                                                        Server
+                                                                    </Typography>
+                                                                    <Select
+                                                                        label="Server auswählen"
+                                                                        value={
+                                                                            assignment.serverId
+                                                                                ? String(assignment.serverId)
+                                                                                : ""
+                                                                        }
+                                                                        onChange={(value) =>
+                                                                            handleAssignmentServerChange(index, value)
+                                                                        }
+                                                                        disabled={
+                                                                            maintenanceLocked ||
+                                                                            savingAssignments ||
+                                                                            !canEditUsers
+                                                                        }
+                                                                        variant="outlined"
+                                                                    >
+                                                                        {serverOptions.map((server) => (
+                                                                            <Option key={server.id} value={String(server.id)}>
+                                                                                {server.name}
+                                                                            </Option>
+                                                                        ))}
+                                                                    </Select>
+                                                                </div>
+                                                                <div>
+                                                                    <Typography className="mb-2 block text-xs font-semibold uppercase text-blue-gray-500">
+                                                                        Rechtegruppe
+                                                                    </Typography>
+                                                                    <div className="flex flex-col gap-2">
+                                                                        <Switch
+                                                                            id={`assignment-global-${index}`}
+                                                                            label="Globale Gruppe verwenden"
+                                                                            checked={assignment.useGlobalGroup}
+                                                                            onChange={({ target }) =>
+                                                                                handleAssignmentUseGlobalToggle(
+                                                                                    index,
+                                                                                    target?.checked
+                                                                                )
+                                                                            }
+                                                                            disabled={
+                                                                                maintenanceLocked ||
+                                                                                savingAssignments ||
+                                                                                !canEditUsers
+                                                                            }
+                                                                            labelProps={{
+                                                                                className: "text-sm font-normal text-blue-gray-600"
+                                                                            }}
+                                                                        />
+                                                                        <Select
+                                                                            label="Server-Gruppe wählen"
+                                                                            value={groupSelectValue}
+                                                                            onChange={(value) =>
+                                                                                handleAssignmentGroupChange(index, value)
+                                                                            }
+                                                                            disabled={
+                                                                                maintenanceLocked ||
+                                                                                savingAssignments ||
+                                                                                !canEditUsers ||
+                                                                                assignment.useGlobalGroup
+                                                                            }
+                                                                            variant="outlined"
+                                                                            className="max-w-xl"
+                                                                        >
+                                                                            <Option value="">Globale Gruppe</Option>
+                                                                            {availableGroups.map((group) => (
+                                                                                <Option key={group.id} value={String(group.id)}>
+                                                                                    {group.name}
+                                                                                </Option>
+                                                                            ))}
+                                                                        </Select>
+                                                                    </div>
+                                                                </div>
+                                                            </div>
+                                                            <div className="mt-3 flex justify-end">
+                                                                <Button
+                                                                    variant="text"
+                                                                    color="red"
+                                                                    className="normal-case"
+                                                                    onClick={() => handleRemoveAssignment(index)}
+                                                                    disabled={
+                                                                        maintenanceLocked ||
+                                                                        savingAssignments ||
+                                                                        !canEditUsers
+                                                                    }
+                                                                >
+                                                                    Entfernen
+                                                                </Button>
+                                                            </div>
+                                                        </div>
+                                                    );
+                                                })
+                                            )}
                                         </div>
-                                    ))}
-                                </div>
+                                        <div className="mt-4 flex flex-wrap items-center gap-3">
+                                            <Button
+                                                variant="outlined"
+                                                color="blue"
+                                                className="normal-case"
+                                                onClick={handleAddAssignment}
+                                                disabled={
+                                                    maintenanceLocked ||
+                                                    savingAssignments ||
+                                                    !canEditUsers ||
+                                                    availableServers.length === 0 ||
+                                                    usedServerIds.size >= availableServers.length
+                                                }
+                                            >
+                                                Server hinzufügen
+                                            </Button>
+                                            <Button
+                                                color="green"
+                                                className="normal-case"
+                                                onClick={handleSaveAssignments}
+                                                disabled={
+                                                    maintenanceLocked ||
+                                                    savingAssignments ||
+                                                    !canEditUsers ||
+                                                    !assignmentsChanged
+                                                }
+                                            >
+                                                {savingAssignments ? "Speichert ..." : "Zuordnungen speichern"}
+                                            </Button>
+                                            {savingAssignments && <Spinner className="h-4 w-4" />}
+                                        </div>
+                                    </>
+                                )}
                             </div>
                         </div>
 

frontend/src/pages/dashboard/userGroupDetail.jsx

@@ -78,8 +78,14 @@ const LEVEL_PRIORITY = {
   full: 2
 };
 
-const normalizePermissionLevel = (key, value) =>
-  key === "maintenance-server-delete" && value !== "full" ? "none" : value;
+const isDependencySatisfied = (value, requirement) => {
+  const req = requirement || "!=none";
+  if (req === "!=none") return value !== "none";
+  if (req.startsWith("!=")) return value !== req.substring(2);
+  if (req.startsWith("=")) return value === req.substring(1);
+  if (!req) return true;
+  return value === req;
+};
 
 export function UserGroupDetail() {
   const { groupId } = useParams();
@@ -177,22 +183,28 @@ export function UserGroupDetail() {
           };
         };
 
+        const normalizeGroup = (group, groupIdx = 0) => {
+          const groupItems = Array.isArray(group.items)
+            ? group.items.map((item, itemIdx) => normalizeItem(item, itemIdx)).filter(Boolean)
+            : [];
+          const childGroups = Array.isArray(group.groups)
+            ? group.groups.map((child, childIdx) => normalizeGroup(child, childIdx))
+            : [];
+          return {
+            ...group,
+            sortOrder: typeof group.sortOrder === "number" ? group.sortOrder : groupIdx,
+            items: groupItems,
+            groups: childGroups
+          };
+        };
+
         const normalizedSections = rawSections.map((section, sectionIndex) => {
           const sectionItems = Array.isArray(section.items)
             ? section.items.map((item, itemIdx) => normalizeItem(item, itemIdx)).filter(Boolean)
             : [];
 
           const sectionGroups = Array.isArray(section.groups)
-            ? section.groups.map((group, groupIdx) => {
-              const groupItems = Array.isArray(group.items)
-                ? group.items.map((item, itemIdx) => normalizeItem(item, itemIdx)).filter(Boolean)
-                : [];
-              return {
-                ...group,
-                sortOrder: typeof group.sortOrder === "number" ? group.sortOrder : groupIdx,
-                items: groupItems
-              };
-            })
+            ? section.groups.map((group, groupIdx) => normalizeGroup(group, groupIdx))
             : [];
 
           return {
@@ -515,12 +527,52 @@ export function UserGroupDetail() {
     if (!permissionKey || !canAdjustPermissions || isSuperuserGroup) {
       return;
     }
-    const nextValue = normalizePermissionLevel(permissionKey, value);
-    setPermissionSelection((prev) => {
-      const shouldResetDelete =
-        permissionKey === "maintenance-server-manage" && nextValue !== "full";
+    const getValueWithDefaults = (key, selectionMap) =>
+      selectionMap[key] ?? permissionDefaults[key] ?? "none";
 
-      if (!shouldResetDelete && prev[permissionKey] === nextValue) {
+    const collectAllItems = () => {
+      const items = [];
+      const walkGroups = (groups) => {
+        (groups || []).forEach((group) => {
+          (group.items || []).forEach((item) => items.push(item));
+          if (group.groups) {
+            walkGroups(group.groups);
+          }
+        });
+      };
+      permissionSections.forEach((section) => {
+        (section.items || []).forEach((item) => items.push(item));
+        walkGroups(section.groups);
+      });
+      return items;
+    };
+
+    const allItems = collectAllItems();
+    const itemMap = new Map(allItems.map((item) => [item.key, item]));
+
+    const clampToAllowed = (itemKey, desiredLevel) => {
+      const item = itemMap.get(itemKey);
+      if (!item) return desiredLevel;
+      const allowed = Array.isArray(item.availableLevels) && item.availableLevels.length
+        ? item.availableLevels
+        : LEVEL_OPTIONS.map((opt) => opt.value);
+      if (allowed.includes(desiredLevel)) {
+        return desiredLevel;
+      }
+      // Fallback: wähle niedrigstes erlaubtes Level
+      return allowed.reduce((lowest, candidate) => {
+        return LEVEL_PRIORITY[candidate] < LEVEL_PRIORITY[lowest] ? candidate : lowest;
+      }, allowed[0] || "none");
+    };
+
+    const nextValue = clampToAllowed(permissionKey, value);
+
+
+    setPermissionSelection((prev) => {
+      const currentValue = getValueWithDefaults(permissionKey, prev);
+      const isDowngrade = LEVEL_PRIORITY[nextValue] < LEVEL_PRIORITY[currentValue];
+
+      if (prev[permissionKey] === nextValue) {
         return prev;
       }
 
@@ -529,13 +581,31 @@ export function UserGroupDetail() {
         [permissionKey]: nextValue
       };
 
-      if (shouldResetDelete) {
-        nextState["maintenance-server-delete"] = "none";
+      // Kaskade: Nur bei Downgrade des auslösenden Rechts abhängige Rechte herabstufen.
+      if (isDowngrade) {
+        let changed = true;
+        while (changed) {
+          changed = false;
+          allItems.forEach((item) => {
+            const dependencies = Array.isArray(item.dependencies) ? item.dependencies : [];
+            if (!dependencies.length) return;
+            const satisfied = dependencies.every((dep) =>
+              isDependencySatisfied(getValueWithDefaults(dep.key, nextState), dep.requiredLevel)
+            );
+            if (!satisfied) {
+              const cascadedValue = clampToAllowed(item.key, nextValue);
+              if (getValueWithDefaults(item.key, nextState) !== cascadedValue) {
+                nextState[item.key] = cascadedValue;
+                changed = true;
+              }
+            }
+          });
+        }
       }
 
       return nextState;
     });
-  }, [canAdjustPermissions, isSuperuserGroup]);
+  }, [canAdjustPermissions, isSuperuserGroup, permissionDefaults, permissionSections]);
 
   const getPermissionValue = useCallback(
     (permissionKey) => {
@@ -549,7 +619,7 @@ export function UserGroupDetail() {
         value = permissionDefaults[permissionKey];
       }
       if (typeof value === "string") {
-        return normalizePermissionLevel(permissionKey, value);
+        return value;
       }
       return value;
     },
@@ -562,12 +632,6 @@ export function UserGroupDetail() {
     ),
     []
   );
-  const radioCheckedIcon = useMemo(
-    () => (
-      <span className="mx-auto block h-2.5 w-2.5 rounded-full border border-blue-gray-700 bg-gray-900" />
-    ),
-    []
-  );
 
   const isPermissionRowVisible = useCallback(
     (row) => {
@@ -607,8 +671,7 @@ export function UserGroupDetail() {
 
     const rowName = `permission-${ownerKey}-${row.key}`;
     const currentValue = getPermissionValue(row.key) ?? "none";
-    const displayValue = normalizePermissionLevel(row.key, currentValue);
-    const serverManageLevel = getPermissionValue("maintenance-server-manage") ?? "none";
+    const displayValue = currentValue;
     const { addTopBorder = true } = options;
 
     const rowClasses = [
@@ -621,11 +684,7 @@ export function UserGroupDetail() {
     const baseLevels = Array.isArray(row.availableLevels) && row.availableLevels.length
       ? row.availableLevels
       : LEVEL_OPTIONS.map((option) => option.value);
-    const availableLevels = new Set(
-      row.key === "maintenance-server-delete"
-        ? baseLevels.filter((level) => level === "full" || level === "none")
-        : baseLevels
-    );
+    const availableLevels = new Set(baseLevels);
     const levelOptions = LEVEL_OPTIONS;
 
     return (
@@ -637,17 +696,12 @@ export function UserGroupDetail() {
           {levelOptions.map((option) => {
             const optionId = `${rowName}-${option.value}`;
             const checked = displayValue === option.value;
-            const requiresManageFull =
-              row.key === "maintenance-server-delete" &&
-              option.value === "full" &&
-              (LEVEL_PRIORITY[serverManageLevel] ?? 0) < LEVEL_PRIORITY.full;
             const disabled =
               !availableLevels.has(option.value) ||
               permissionsLoading ||
               savingGroup ||
               !canAdjustPermissions ||
-              isSuperuserGroup ||
-              requiresManageFull;
+              isSuperuserGroup;
 
             return (
               <ListItem
@@ -673,7 +727,6 @@ export function UserGroupDetail() {
                         className: "p-0"
                       }}
                       icon={radioIcon}
-                      checkedIcon={radioCheckedIcon}
                     />
                   </ListItemPrefix>
                   <Typography
@@ -692,6 +745,30 @@ export function UserGroupDetail() {
     );
   };
 
+  const groupHasVisibleRows = (grp) => {
+    if (!grp) {
+      return false;
+    }
+    const groupItems = Array.isArray(grp.items) ? grp.items : [];
+    const childGroups = Array.isArray(grp.groups) ? grp.groups : [];
+    if (groupItems.some(isPermissionRowVisible)) {
+      return true;
+    }
+    return childGroups.some(groupHasVisibleRows);
+  };
+
+  const sectionHasVisibleRows = (section) => {
+    if (!section) {
+      return false;
+    }
+    const sectionItems = Array.isArray(section.items) ? section.items : [];
+    const sectionGroups = Array.isArray(section.groups) ? section.groups : [];
+    if (sectionItems.some(isPermissionRowVisible)) {
+      return true;
+    }
+    return sectionGroups.some(groupHasVisibleRows);
+  };
+
   return (
     <>
       <div className="mt-12 flex flex-col gap-12">
@@ -709,9 +786,6 @@ export function UserGroupDetail() {
             </div>
           </div>
         )}
-        <div className="relative h-72 w-full overflow-hidden rounded-xl bg-[url('/img/background-image.png')] bg-cover\tbg-center">
-          <div className="absolute inset-0 h-full w-full bg-gray-900/75" />
-        </div>
         <Card className="mx-3 -mt-16 mb-6 lg:mx-4 border border-blue-gray-100">
           <CardBody className="p-4">
             <div className="mb-10 flex flex-wrap items-center justify-between gap-6">
@@ -877,7 +951,7 @@ export function UserGroupDetail() {
                         Die Superuser-Gruppe besitzt automatisch Vollzugriff auf alle Bereiche. Berechtigungen können hier nicht angepasst werden.
                       </div>
                     ) : !canViewPermissionSettings ? null : (
-                      <div className="rounded-xl border border-blue-gray-100 bg-white shadow-sm">
+                      <>
                         {permissionsLoading && (
                           <div className="border-b border-blue-gray-100 px-4 py-4">
                             <div className="flex items-center gap-3 text-sm text-blue-gray-500">
@@ -897,53 +971,85 @@ export function UserGroupDetail() {
                               Für diese Gruppe sind keine Berechtigungen definiert.
                             </div>
                           ) : (
-                            permissionSections.map((section, sectionIndex) => {
-                              const sectionItems = Array.isArray(section.items) ? section.items : [];
-                              const sectionGroups = Array.isArray(section.groups) ? section.groups : [];
+                            (() => {
+                              const renderedSections = permissionSections
+                                .map((section, sectionIndex) => {
+                                  const sectionItems = Array.isArray(section.items) ? section.items : [];
+                                  const sectionGroups = Array.isArray(section.groups) ? section.groups : [];
 
-                              return (
-                                <div
-                                  key={section.key || sectionIndex}
-                                  className={sectionIndex === 0 ? "" : "border-t border-blue-gray-100"}
-                                >
-                                  <div className="border-b border-blue-gray-100 px-4 py-4">
-                                    <Typography variant="h6" className="text-lg font-semibold text-blue-gray-700">
-                                      {section.title}
-                                    </Typography>
-                                  </div>
-                                  {sectionItems.map((row, rowIndex) =>
-                                    renderPermissionRow(row, section.key || sectionIndex, {
-                                      addTopBorder: rowIndex !== 0
-                                    })
-                                  )}
-                                  {sectionGroups.map((group, groupIdx) => {
-                                    const groupItems = Array.isArray(group.items) ? group.items : [];
-                                    const hasVisibleRows = groupItems.some(isPermissionRowVisible);
+                                  if (!sectionHasVisibleRows(section)) {
+                                    return null;
+                                  }
 
-                                    if (!hasVisibleRows) {
+                                  const renderGroup = (currentGroup, path = `${section.key || sectionIndex}-group`, depth = 0) => {
+                                    if (!groupHasVisibleRows(currentGroup)) {
                                       return null;
                                     }
 
+                                    const groupItems = Array.isArray(currentGroup.items) ? currentGroup.items : [];
+                                    const childGroups = Array.isArray(currentGroup.groups) ? currentGroup.groups : [];
+
                                     return (
-                                      <div key={group.key || `${section.key || sectionIndex}-${groupIdx}`} className="border-t border-blue-gray-100">
-                                        <div className="border-b border-blue-gray-100 px-4 py-3">
-                                          <Typography className="text-sm font-semibold uppercase tracking-wide text-blue-gray-600">
-                                            {group.title}
+                                      <div
+                                        key={currentGroup.key || path}
+                                        className=""
+                                      >
+                                        <div className="border-b border-blue-gray-100 bg-blue-gray-50/80 px-4 py-3">
+                                          <Typography className={`${depth > 0 ? "ml-2" : ""} text-xs font-semibold uppercase tracking-wide text-blue-gray-600`}>
+                                            {currentGroup.title}
                                           </Typography>
                                         </div>
-                                        {groupItems.map((row, rowIndex) =>
-                                          renderPermissionRow(row, group.key || `${section.key || sectionIndex}-${groupIdx}`, {
-                                            addTopBorder: rowIndex !== 0
-                                          })
-                                        )}
+                                        <div className="divide-y divide-blue-gray-100">
+                                          {groupItems.map((row) =>
+                                            renderPermissionRow(row, `${path}-${row.key}`, {
+                                              addTopBorder: false
+                                            })
+                                          )}
+                                          {childGroups.map((childGroup, childIdx) =>
+                                            renderGroup(childGroup, `${path}-${childGroup.key || childIdx}`, depth + 1)
+                                          )}
+                                        </div>
                                       </div>
                                     );
-                                  })}
-                                </div>
-                              );
-                            })
+                                  };
+
+                                  return (
+                                    <div
+                                      key={section.key || sectionIndex}
+                                      className="overflow-hidden rounded-xl border border-blue-gray-100 bg-white shadow-sm"
+                                    >
+                                      <div className="border-b border-blue-gray-100 bg-blue-gray-50/70 px-4 py-3">
+                                        <Typography variant="h6" className="text-lg font-semibold text-blue-gray-700">
+                                          {section.title}
+                                        </Typography>
+                                      </div>
+                                      <div className="divide-y divide-blue-gray-100">
+                                        {sectionItems.map((row) =>
+                                          renderPermissionRow(row, section.key || sectionIndex, {
+                                            addTopBorder: false
+                                          })
+                                        )}
+                                        {sectionGroups.map((group, groupIdx) =>
+                                          renderGroup(group, `${section.key || sectionIndex}-${groupIdx}`, 0)
+                                        )}
+                                      </div>
+                                    </div>
+                                  );
+                                })
+                                .filter(Boolean);
+
+                              if (renderedSections.length === 0) {
+                                return (
+                                  <div className="border-b border-blue-gray-100 px-4 py-4 text-sm text-blue-gray-500">
+                                    Für diese Gruppe sind keine Berechtigungen definiert.
+                                  </div>
+                                );
+                              }
+
+                              return <div className="flex flex-col gap-4">{renderedSections}</div>;
+                            })()
                           ))}
-                      </div>
+                      </>
                     )}
                   </>
 

frontend/src/routes.jsx

@@ -2,8 +2,8 @@ import {
   Square3Stack3DIcon,
   WrenchScrewdriverIcon,
   ListBulletIcon,
-  ServerStackIcon,
   RectangleStackIcon,
+  ServerStackIcon,
   ArrowLeftOnRectangleIcon,
   UserIcon,
   UserGroupIcon,

mkdocs.yml

@@ -0,0 +1,23 @@
+site_name: Stackpulse Dokumentation
+theme:
+  name: material
+
+nav:
+  - Start: index.md
+  - Benutzerhandbuch:
+      - Überblick: user-guide/index.md
+      - Setup: user-guide/setup.md
+      - Stacks: user-guide/stacks.md
+      - Logs: user-guide/logs.md
+      - Wartung: user-guide/maintenance.md
+      - Benutzer: user-guide/users.md
+      - Benutzergruppen & Rechte: user-guide/groups.md
+  - Getting Started:
+      - Getting Started: getting-started.md
+      - Umgebungsvariablen: environment.md
+  - Technik:
+      - Architektur: architecture.md
+      - Backend & API: backend.md
+      - Frontend: frontend.md
+      - Lokale Entwicklung: local-dev.md
+      - Operations & Wartung: operations.md