================================================================================
                     SKILLMATE - VOLLSTÄNDIGE ANWENDUNGSDOKUMENTATION
================================================================================

PROJEKTÜBERSICHT
================================================================================
SkillMate ist ein Mitarbeiter-Skills-Management-System für Sicherheitsbehörden.
Die Anwendung besteht aus drei Hauptmodulen:
- Frontend (React-basierte Benutzeroberfläche)
- Admin-Panel (React-basierte Administrationsoberfläche)  
- Backend (Node.js/Express API-Server mit verschlüsselter SQLite-Datenbank)

================================================================================
1. PROJEKTSTRUKTUR
================================================================================

SkillMate/
├── backend/                    # Node.js/Express API-Server
│   ├── src/
│   │   ├── config/            # Datenbank- und Sicherheitskonfiguration
│   │   ├── middleware/        # Auth, Error-Handler, Role-Auth
│   │   ├── routes/            # 14 API-Route-Module
│   │   ├── services/          # Email, Encryption, Sync-Services
│   │   └── utils/             # Logger und Hilfsfunktionen
│   ├── package.json
│   └── tsconfig.json
│
├── frontend/                   # React Benutzeroberfläche
│   ├── src/
│   │   ├── components/        # Wiederverwendbare UI-Komponenten
│   │   ├── views/             # Hauptansichten/Seiten
│   │   ├── stores/            # Zustand-Management (Zustand)
│   │   ├── services/          # API-Client
│   │   └── data/              # Statische Daten
│   ├── package.json
│   ├── tailwind.config.js
│   └── tsconfig.json
│
├── admin-panel/               # React Admin-Oberfläche
│   ├── src/
│   │   ├── components/
│   │   ├── views/
│   │   ├── services/
│   │   └── stores/
│   ├── package.json
│   └── tailwind.config.js
│
├── shared/                    # Gemeinsame TypeScript-Typen (referenziert)
└── main.py                    # Python-Anwendungsstarter

================================================================================
2. TECHNOLOGIE-STACK
================================================================================

FRONTEND & ADMIN-PANEL:
- React 18.2.0 mit TypeScript 5.3.0
- Vite als Build-Tool
- React Router 6.20.0 für Routing
- Zustand 4.4.7 für State Management
- Axios 1.6.2 für HTTP-Requests
- Tailwind CSS 3.3.6 für Styling
- Lucide React für Icons

BACKEND:
- Node.js mit Express 4.18.2
- TypeScript 5.3.0
- better-sqlite3-multiple-ciphers 12.2.0 (verschlüsselte Datenbank)
- jsonwebtoken 9.0.2 für JWT-Authentifizierung
- bcrypt 6.0.0 für Passwort-Hashing
- crypto-js 4.2.0 für Feld-Verschlüsselung
- winston 3.11.0 für Logging
- nodemailer 7.0.6 für E-Mail-Versand
- multer 2.0.1 für Datei-Uploads
- helmet 7.1.0 für Sicherheits-Header
- cors 2.8.5 für Cross-Origin Requests

================================================================================
3. DATENBANK-SCHEMA (SQLite mit AES-256 Verschlüsselung)
================================================================================

TABELLE: employees
------------------
id                    TEXT PRIMARY KEY      # UUID
first_name           TEXT NOT NULL
last_name            TEXT NOT NULL
employee_number      TEXT UNIQUE NOT NULL
photo                TEXT                  # Base64 oder Pfad
position             TEXT NOT NULL
department           TEXT NOT NULL
email                TEXT NOT NULL         # VERSCHLÜSSELT
email_hash           TEXT                  # Für Suche
phone                TEXT NOT NULL         # VERSCHLÜSSELT
phone_hash           TEXT                  # Für Suche
mobile               TEXT                  # VERSCHLÜSSELT
office               TEXT
availability         TEXT NOT NULL         # 'available', 'busy', 'offline'
clearance_level      TEXT                  # VERSCHLÜSSELT
clearance_valid_until TEXT                 # VERSCHLÜSSELT
clearance_issued_date TEXT
created_at           TEXT NOT NULL
updated_at           TEXT NOT NULL
created_by           TEXT NOT NULL
updated_by           TEXT

TABELLE: users
--------------
id                   TEXT PRIMARY KEY
username             TEXT UNIQUE NOT NULL
email                TEXT NOT NULL         # VERSCHLÜSSELT
email_hash           TEXT                  # Für Suche
password             TEXT NOT NULL         # Bcrypt gehashed
role                 TEXT NOT NULL         # 'admin', 'superuser', 'user'
employee_id          TEXT                  # FK zu employees
last_login           TEXT
is_active            INTEGER DEFAULT 1
created_at           TEXT NOT NULL
updated_at           TEXT NOT NULL

TABELLE: skills
---------------
id                   TEXT PRIMARY KEY
name                 TEXT NOT NULL
category             TEXT NOT NULL
description          TEXT
expires_after        INTEGER              # Tage bis Ablauf

TABELLE: employee_skills (Verknüpfungstabelle)
-----------------------------------------------
employee_id          TEXT NOT NULL
skill_id             TEXT NOT NULL
level                TEXT                  # 'basic', 'intermediate', 'advanced', 'expert'
verified             INTEGER DEFAULT 0
verified_by          TEXT
verified_date        TEXT
PRIMARY KEY (employee_id, skill_id)

TABELLE: language_skills
------------------------
id                   TEXT PRIMARY KEY
employee_id          TEXT NOT NULL
language             TEXT NOT NULL
proficiency          TEXT NOT NULL         # A1-C2, Muttersprachler
certified            INTEGER DEFAULT 0
certificate_type     TEXT
is_native            INTEGER DEFAULT 0
can_interpret        INTEGER DEFAULT 0

TABELLE: specializations
------------------------
id                   TEXT PRIMARY KEY
employee_id          TEXT NOT NULL
name                 TEXT NOT NULL

TABELLE: security_audit_log
---------------------------
id                   TEXT PRIMARY KEY
entity_type          TEXT NOT NULL
entity_id            TEXT NOT NULL
action               TEXT NOT NULL         # CRUD, login, logout, failed_login
user_id              TEXT
changes              TEXT                  # JSON der Änderungen
timestamp            TEXT NOT NULL
ip_address           TEXT
user_agent           TEXT
risk_level           TEXT                  # low, medium, high, critical

TABELLE: system_settings
------------------------
key                  TEXT PRIMARY KEY
value                TEXT NOT NULL
description          TEXT
updated_at           TEXT NOT NULL
updated_by           TEXT

================================================================================
4. API-ENDPUNKTE
================================================================================

AUTHENTIFIZIERUNG (/api/auth)
-----------------------------
POST /login          - Benutzeranmeldung (username/email + password)
                      Returns: { user, token }
POST /logout         - Benutzerabmeldung

MITARBEITER (/api/employees)
----------------------------
GET /                - Alle Mitarbeiter mit Skills abrufen
GET /:id             - Einzelnen Mitarbeiter abrufen
POST /               - Neuen Mitarbeiter anlegen (admin/poweruser)
PUT /:id             - Mitarbeiter aktualisieren
DELETE /:id          - Mitarbeiter löschen (admin)
POST /search         - Mitarbeiter nach Skills suchen
                      Body: { skills: string[], category?: string }

BENUTZER (/api/users, /api/admin/users)
---------------------------------------
GET /                - Alle Benutzer abrufen (admin)
GET /:id             - Benutzer abrufen
POST /               - Neuen Benutzer anlegen (admin)
PUT /:id             - Benutzer aktualisieren (admin)
DELETE /:id          - Benutzer löschen (admin)

SKILLS (/api/skills)
-------------------
GET /                - Alle verfügbaren Skills abrufen
POST /initialize     - Standard-Skills initialisieren (admin)

DATEI-UPLOAD (/api/upload)
--------------------------
POST /photo          - Mitarbeiterfoto hochladen
                      FormData: file (multipart)

NETZWERK & SYNC (/api/network, /api/sync)
-----------------------------------------
GET /network/discover     - Andere Instanzen im Netzwerk finden
POST /sync/push          - Daten an andere Instanz senden
POST /sync/pull          - Daten von anderer Instanz holen
GET /sync/status         - Synchronisationsstatus

SYSTEM (/api/admin/settings)
----------------------------
GET /                - Alle Einstellungen abrufen
PUT /:key            - Einstellung aktualisieren

HEALTH CHECK
-----------
GET /api/health      - Server-Status prüfen

================================================================================
5. AUTHENTIFIZIERUNGS-FLOW
================================================================================

1. LOGIN-PROZESS:
   - Benutzer sendet username/email + password an /api/auth/login
   - Backend validiert Credentials gegen verschlüsselte Datenbank
   - Passwort wird mit bcrypt verifiziert
   - JWT-Token wird mit 24h Gültigkeit generiert
   - User-Objekt und Token werden zurückgegeben

2. AUTORISIERUNG:
   - JWT-Token wird bei jedem Request im Authorization-Header gesendet
   - Middleware verifiziert Token und extrahiert User-Daten
   - Rollenbasierte Zugriffskontrolle (admin > superuser > user)
   - Granulare Berechtigungen für spezifische Aktionen

3. SICHERHEITS-FEATURES:
   - Feld-Level-Verschlüsselung für sensible Daten
   - Security Audit Logging aller kritischen Aktionen
   - CSRF-Schutz durch Helmet
   - Input-Validierung und Sanitization
   - Rate-Limiting für Login-Versuche

================================================================================
6. GUI-AUFBAU UND STYLING
================================================================================

LAYOUT-STRUKTUR (Frontend & Admin-Panel)
----------------------------------------
┌─────────────────────────────────────────────────────────┐
│                    HEADER (64px)                        │
│  Logo | Navigation                    User | Theme      │
├──────────┬──────────────────────────────────────────────┤
│          │                                              │
│          │              MAIN CONTENT                    │
│ SIDEBAR  │                                              │
│  (256px) │         (Responsive Grid/Flex)               │
│          │                                              │
│          │                                              │
└──────────┴──────────────────────────────────────────────┘

FARBSCHEMA
----------
LIGHT MODE:
- Primär Blau:        #3182CE (hover: #2563EB)
- Hintergrund:        #F8FAFC (main), #FFFFFF (cards)
- Text Primär:        #1A365D
- Text Sekundär:      #2D3748
- Text Tertiär:       #4A5568
- Text Quaternär:     #718096
- Erfolg:             #059669
- Warnung:            #D97706
- Fehler:             #DC2626
- Rahmen:             #E2E8F0

DARK MODE:
- Hintergrund:        #000000 (main), #1A1F3A (secondary)
- Akzent Cyan:        #00D4FF
- Text Primär:        #FFFFFF
- Text Sekundär:      rgba(255,255,255,0.9)
- Text Tertiär:       rgba(255,255,255,0.7)
- Rahmen:             #2D3748

TYPOGRAFIE
----------
- Schriftart:         Poppins (Primary), system-ui (Fallback)
- Titel Groß:         32px, font-semibold
- Titel Dialog:       24px, font-semibold
- Titel Sektion:      20px, font-semibold
- Body:               14px, font-normal
- Small:              12px, font-normal
- Caption:            10px, font-medium

ABSTÄNDE
--------
- Container:          40px padding
- Card:               32px padding
- Element:            16px padding
- Inline:             8px padding

BORDER-RADIUS
-------------
- Card:               16px
- Button:             24px
- Input:              8px
- Badge:              12px
- Avatar:             50% (kreisförmig)

KOMPONENTEN-STYLING
-------------------
BUTTONS:
- Primär:             bg-blue-600, hover:bg-blue-700, text-white
- Sekundär:           bg-gray-200, hover:bg-gray-300, text-gray-700
- Gefahr:             bg-red-600, hover:bg-red-700, text-white
- Höhe:               40px (standard), 32px (small), 48px (large)
- Padding:            16px horizontal

INPUTS:
- Höhe:               40px
- Padding:            12px
- Border:             1px solid #E2E8F0
- Focus:              ring-2 ring-blue-500
- Dark Mode:          bg-gray-800, border-gray-600

CARDS:
- Background:         white (light), #1A1F3A (dark)
- Shadow:             0 1px 3px rgba(0,0,0,0.1)
- Hover Shadow:       0 4px 6px rgba(0,0,0,0.1)
- Transition:         all 0.2s ease

SIDEBAR:
- Width:              256px (expanded), 64px (collapsed)
- Background:         white (light), #1A1F3A (dark)
- Items:              48px height, hover:bg-gray-100
- Active Item:        bg-blue-50, border-left: 3px solid blue

TABLES:
- Header:             bg-gray-50, font-semibold
- Row Height:         48px
- Hover:              bg-gray-50
- Border:             1px solid #E2E8F0

RESPONSIVE BREAKPOINTS
---------------------
- Mobile:             < 640px
- Tablet:             640px - 1024px
- Desktop:            > 1024px

ANIMATIONEN
-----------
- Transition Default: 200ms ease
- Hover Scale:        scale(1.02)
- Click Scale:        scale(0.98)
- Fade In:            opacity 0 to 1, 300ms
- Slide In:           translateX(-100%) to 0, 300ms

================================================================================
7. FRONTEND KOMPONENTEN-HIERARCHIE
================================================================================

APP.TSX (Router-Konfiguration)
-------------------------------
<BrowserRouter>
  <Routes>
    <Route path="/login" element={<Login />} />
    <Route element={<Layout />}>
      <Route path="/" element={<Dashboard />} />
      <Route path="/employees" element={<EmployeeList />} />
      <Route path="/employees/new" element={<EmployeeForm />} />
      <Route path="/employees/:id" element={<EmployeeDetail />} />
      <Route path="/employees/:id/edit" element={<EmployeeForm />} />
      <Route path="/search" element={<SkillSearch />} />
      <Route path="/settings" element={<Settings />} />
      <Route path="/analytics" element={<WorkspaceAnalytics />} />
      <Route path="/floor-plan" element={<FloorPlan />} />
      <Route path="/desk-booking" element={<DeskBooking />} />
    </Route>
  </Routes>
</BrowserRouter>

LAYOUT-KOMPONENTE
-----------------
<div className="flex h-screen">
  <Sidebar>
    - Logo
    - NavigationItems[]
      - Dashboard
      - Mitarbeiter
      - Suche
      - Analytics
      - Einstellungen
    - UserInfo
  </Sidebar>
  
  <div className="flex-1 flex flex-col">
    <Header>
      - Breadcrumbs
      - SearchBar
      - NotificationBell
      - UserMenu
      - ThemeToggle
    </Header>
    
    <main className="flex-1 overflow-auto">
      <Outlet /> {/* Routed Content */}
    </main>
  </div>
</div>

WIEDERVERWENDBARE KOMPONENTEN
-----------------------------
EmployeeCard:
  - Foto (Avatar)
  - Name & Position
  - Abteilung
  - Verfügbarkeitsstatus
  - Skills-Tags
  - Kontakt-Icons

PhotoUpload:
  - Drag & Drop Zone
  - File Input
  - Preview
  - Upload Progress
  - Error Handling

SkillBadge:
  - Skill Name
  - Level Indicator
  - Verified Icon
  - Category Color

SearchFilter:
  - Kategorie-Dropdown
  - Skill-Multi-Select
  - Level-Filter
  - Verfügbarkeits-Filter
  - Reset-Button

DataTable:
  - Sortierbare Header
  - Pagination
  - Row Selection
  - Bulk Actions
  - Export Funktion

Modal:
  - Overlay
  - Content Container
  - Close Button
  - Title
  - Footer Actions

================================================================================
8. STATE MANAGEMENT (ZUSTAND STORES)
================================================================================

AUTH STORE
----------
interface AuthState {
  user: User | null
  token: string | null
  isAuthenticated: boolean
  
  // Actions
  login: (user: User, token: string) => void
  logout: () => void
  updateUser: (updates: Partial<User>) => void
  checkAuth: () => Promise<boolean>
}

THEME STORE
-----------
interface ThemeState {
  theme: 'light' | 'dark'
  sidebarCollapsed: boolean
  
  // Actions
  toggleTheme: () => void
  setTheme: (theme: 'light' | 'dark') => void
  toggleSidebar: () => void
  setSidebarCollapsed: (collapsed: boolean) => void
}

EMPLOYEE STORE (implizit)
------------------------
- Employees werden via React Query/SWR gecached
- Optimistic Updates bei Änderungen
- Background Refetching
- Pagination State lokal

================================================================================
9. ENTWICKLUNGS- UND BUILD-PROZESS
================================================================================

ENTWICKLUNG
-----------
Frontend:
  npm run dev              # Startet Vite Dev-Server auf Port 5173
  
Backend:
  npm run dev              # Startet Nodemon mit ts-node
  
Admin-Panel:
  npm run dev              # Startet Vite Dev-Server auf Port 5174

PRODUCTION BUILD
---------------
Frontend:
  npm run build            # Erstellt optimierten Build in dist/
  
Backend:
  npm run build            # Kompiliert TypeScript zu JavaScript
  npm start                # Startet Production Server
  
Admin-Panel:
  npm run build            # Erstellt optimierten Build

UMGEBUNGSVARIABLEN
-----------------
Backend (.env):
  PORT=3000
  DATABASE_PATH=./data/skillmate.db
  DATABASE_KEY=your-encryption-key
  JWT_SECRET=your-jwt-secret
  FIELD_ENCRYPTION_KEY=your-field-key
  SMTP_HOST=smtp.example.com
  SMTP_PORT=587
  SMTP_USER=user@example.com
  SMTP_PASS=password

Frontend (.env):
  VITE_API_URL=http://localhost:3000/api
  VITE_APP_TITLE=SkillMate

================================================================================
10. SICHERHEITS-FEATURES
================================================================================

1. DATENBANK-VERSCHLÜSSELUNG:
   - AES-256 Verschlüsselung der gesamten Datenbank
   - Zusätzliche Feld-Level-Verschlüsselung für PII

2. AUTHENTIFIZIERUNG:
   - JWT mit 24h Expiration
   - Refresh Token Mechanismus
   - Session Management

3. AUTORISIERUNG:
   - Rollenbasierte Zugriffskontrolle (RBAC)
   - Granulare Berechtigungen
   - API-Endpoint-Level Security

4. AUDIT LOGGING:
   - Alle CRUD-Operationen
   - Login/Logout Events
   - Failed Login Attempts
   - Risk Level Assessment

5. INPUT VALIDIERUNG:
   - Express-Validator für alle Inputs
   - SQL Injection Prevention
   - XSS Protection
   - CSRF Token Validation

6. NETZWERK-SICHERHEIT:
   - HTTPS in Production
   - Helmet Security Headers
   - CORS Configuration
   - Rate Limiting

================================================================================
11. SPEZIELLE FEATURES
================================================================================

MULTI-INSTANZ-SYNCHRONISATION
-----------------------------
- Automatische Netzwerk-Discovery
- Bidirektionale Daten-Synchronisation
- Konfliktauflösung
- Scheduled Sync Jobs
- Sync History & Rollback

SKILL-VERWALTUNG
---------------
- Hierarchische Skill-Kategorien
- Skill-Level (Basic bis Expert)
- Zertifizierungsverwaltung
- Ablaufdaten-Tracking
- Skill-Verifizierung

SPRACHKENNTNISSE
---------------
- GER-Level (A1-C2)
- Muttersprachler-Kennzeichnung
- Dolmetscher-Fähigkeiten
- Zertifikats-Verwaltung

ARBEITSPLATZ-FUNKTIONEN
----------------------
- Büro-Zuweisung
- Verfügbarkeitsstatus
- Desk Booking System
- Floor Plan Visualization

E-MAIL-INTEGRATION
-----------------
- SMTP-Konfiguration
- Benachrichtigungen
- Passwort-Reset
- Skill-Ablauf-Erinnerungen

================================================================================
12. INSTALLATION UND DEPLOYMENT
================================================================================

VORAUSSETZUNGEN
--------------
- Node.js 18+ mit npm
- Python 3.8+ (für Launcher)
- SQLite3
- 4GB RAM minimum
- Windows 10/11 oder Linux

INSTALLATION
-----------
1. Repository klonen
2. Dependencies installieren:
   cd backend && npm install
   cd ../frontend && npm install
   cd ../admin-panel && npm install

3. Datenbank initialisieren:
   cd backend
   npm run init-db

4. Umgebungsvariablen konfigurieren

5. Anwendung starten:
   python main.py
   oder
   npm run dev (in jedem Ordner)

DEPLOYMENT
----------
1. Production Builds erstellen
2. Reverse Proxy konfigurieren (nginx/Apache)
3. SSL-Zertifikate einrichten
4. Systemd Service erstellen (Linux)
5. Backup-Strategie implementieren

================================================================================
13. WARTUNG UND MONITORING
================================================================================

LOGGING
-------
- Winston Logger mit Rotation
- Log-Level: error, warn, info, debug
- Separate Logs für Security Events
- Performance Metrics

BACKUP
------
- Automatische Datenbank-Backups
- Verschlüsselte Backup-Dateien
- Retention Policy (30 Tage)
- Restore-Funktionalität

MONITORING
----------
- Health Check Endpoint
- Performance Metrics
- Error Tracking
- User Activity Dashboard

================================================================================
ENDE DER DOKUMENTATION
================================================================================
