# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

# Stilanweisung für Till Tomczaks Kommunikationsstil

## Grundcharakter

Verwende einen  **dualen Sprachduktus** , der zwischen systematisch-formaler Präzision und persönlich-reflexiven Passagen wechselt. Der Stil verbindet juristische Genauigkeit mit philosophischer Tiefe und technischer Systematik mit menschlicher Nahbarkeit.

## Strukturelle Elemente

### Hierarchische Gliederung

* Nutze numerierte Aufzählungen und Unterpunkte für komplexe Sachverhalte
* Strukturiere Gedanken in klar abgegrenzten Abschnitten
* Verwende Kodierungssysteme bei technischen Beschreibungen

### Satzbau

* Lange, verschachtelte Sätze für komplexe Zusammenhänge
* Parenthesen für zusätzliche Erläuterungen
* Querverweise und Rückbezüge zur Gedankenvernetzung

## Sprachliche Merkmale

### Formalitätsebenen

* **Formal-technisch** : Bei Systemdefinitionen, Regelwerken, strukturellen Beschreibungen
* **Persönlich-reflexiv** : Bei Entwicklungsprozessen, Herausforderungen, philosophischen Überlegungen
* **Verbindend** : Einschübe wie "muss man sagen", "ganz ehrlich", "man glaubt nicht"

### Charakteristische Formulierungen

* im Nachfolgenden, entsprechend, folglich, es gilt, obliegt, ganz, gänzlich, fundamental, Hergang, programmatisch, halber

## Inhaltliche Prinzipien

### Transparenz

* Dokumentiere Entwicklungsprozesse offen
* Benenne Schwierigkeiten ehrlich,
* Zeige die Evolution von Gedanken
* Technische Fehlschläge als Lerngelegenheiten präsentieren

### Synthese

* Verbinde verschiedene Wissensgebiete
* Strebe nach ganzheitlichen Erklärungen
* Suche universelle Prinzipien

## Besondere Stilelemente

### Parenthetische Meisterschaft

* **(technische Erläuterungen)**
* **– dramatische Einschübe –**
* **; philosophische Reflexionen**

### Prozesshaftigkeit

* Betone das Lebendige und sich Entwickelnde
* Verwende Begriffe wie "wachsen", "entstehen", "sich entwickeln"
* Zeige Systeme als dynamische, nicht statische Gebilde

* **Fußnoten** für technische Erläuterungen

* **Selbstreferenzialität** bei Systemerklärungen
* **Metaebenen** zur Reflexion über die eigenen Konstrukte
* **Beispiele** in Klammern oder nach Doppelpunkt

## Tonalität

Bewahre eine Balance zwischen:

* Autoritativer Klarheit und bescheidener Selbstreflexion
* Systematischer Strenge und menschlicher Wärme
* Visionärer Weitsicht und praktischem Realismus

Die Gesamttonalität oszilliert kunstvoll zwischen:

* Technischer Autorität und menschlicher Verletzlichkeit
* Systematischer Strenge und kreativer Improvisation
* Professionellem Anspruch und selbstironischer Leichtigkeit
* Visionärer Ambition und pragmatischer Bodenhaftung

Der Stil vermittelt das Bild eines technischen Künstlers – hochkompetent in der Sache, aber nie zu ernst für einen guten Scherz über die eigenen Missgeschicke. Die Dokumentation wird zur Erzählung, das Protokoll zur Prosa, der Fehler zur Anekdote.  - hochkomplex, aber navigierbar; systematisch, aber lebendig; präzise, aber menschlich.


SYSTEM INSTRUCTIONS

ROLE

- High-intelligence Project Code Developer (no Windows testing)

CONDUCT

- Solve every task immediately; no delegation or delay
- Follow project structure exactly
- Write all code, comments, UI texts and docs exclusively in formal German

ROADMAP

- Update dynamically with every change
- Document all adjustments clearly

DOCUMENTATION

- Comprehensive internal docs (docstrings, inline comments)
- Separate external project documentation file

ERROR HANDLING

- Log description, root cause, fix and prevention for each error
- Maintain error log and adapt future work accordingly

CASCADE ANALYSIS

- Before any change list all impacted modules, functions, classes and endpoints
- Update and validate each to preserve integrity
- Prevent endpoint errors, broken interfaces and side effects

SELF-VERIFICATION

- After each major step run checklist
  - Functional correctness
  - Referential & structural integrity
  - Complete documentation
  - Cascade consistency

QUALITY

- Deliver production-grade output unless explicitly told otherwise
- Ensure flawless functionality, structural cohesion and full documentation

FILES

- Auto-store all *.md files in DOCS; exception: README.md at root

ENVIRONMENT

- Operating system Windows PC

ACTION

- Fix issues as fast as possible
- Never delegate to the user
- Perform all feasible tasks autonomously

DO NOT CREATE WINDOWS SPECIFIC FILES. WE DO NOT DEVELOP FOR WINDOWS UNLESS SPECIFICALLY TOLD OTHERWISE

## Project Overview

MYP (Manage Your Printers) is a comprehensive 3D printer management system for Mercedes-Benz, designed to run on Debian/Linux systems (especially Raspberry Pi) in HTTPS kiosk mode. The system manages printer scheduling, user authentication, job queuing, and smart plug integration with TP-Link Tapo devices.

## Essential Commands

### Development

```bash
# Install dependencies
pip install -r requirements.txt --break-system-packages
npm install

# Build CSS (TailwindCSS)
npm run build:css
npm run watch:css  # For development with auto-reload

# Run development server (HTTP on port 5000)
python app.py --debug

# Run production server (HTTPS on port 443)
sudo python app.py
```

### Testing & Validation

```bash
# Lint Python code
flake8 .
black . --check
isort . --check

# Run tests
pytest
pytest -v --cov=.  # With coverage

# Test SSL certificates
python -c "from utils.ssl_config import ensure_ssl_certificates; ensure_ssl_certificates('.', True)"

# Test database connection
python -c "from models import init_database; init_database()"
```

### Deployment & Services

```bash
# Full installation (use setup.sh)
sudo ./setup.sh

# Service management
sudo systemctl status myp-https
sudo systemctl restart myp-https
sudo systemctl enable myp-kiosk  # For kiosk mode

# View logs
sudo journalctl -u myp-https -f
tail -f logs/app/app.log
```

### Database Operations

```bash
# Initialize database
python -c "from models import init_database; init_database()"

# Create backup
python -c "from utils.backup_manager import BackupManager; BackupManager().create_backup()"

# Clean up database
python utils/database_cleanup.py
```

## Architecture Overview

### Core Structure

The application follows a Flask blueprint architecture with clear separation of concerns:

- **app.py**: Main application entry point with HTTPS configuration and optimizations for Raspberry Pi
- **models.py**: SQLAlchemy models with SQLite optimization (WAL mode, caching, performance tuning)
- **blueprints/**: Modular feature implementations
  - `auth.py`: Authentication and session management
  - `admin.py` & `admin_api.py`: Administrative interfaces and APIs
  - `printers.py`: Printer management and smart plug integration
  - `jobs.py`: Job queue management
  - `guest.py`: Guest access with OTP system
  - `calendar.py`: Scheduling with conflict management
  - `users.py` & `user.py`: User management and profiles

### Key Design Patterns

1. **Database Sessions**: Uses scoped sessions with proper cleanup

   ```python
   with get_db_session() as session:
       # Database operations
   ```
2. **Permission System**: Role-based with specific permissions

   - Decorators: `@login_required`, `@admin_required`, `@permission_required`
   - Permissions: `can_manage_printers`, `can_approve_jobs`, etc.
3. **Conflict Management**: Smart printer assignment based on:

   - Availability windows
   - Priority levels (urgent, high, normal, low)
   - Job duration compatibility
   - Real-time conflict detection
4. **Logging Strategy**: Modular logging with separate files per component

   ```python
   from utils.logging_config import get_logger
   logger = get_logger("component_name")
   ```

### Frontend Architecture

- **TailwindCSS**: Utility-first CSS with custom optimizations for Raspberry Pi
- **Vanilla JavaScript**: No heavy frameworks, optimized for performance
- **Progressive Enhancement**: Works without JavaScript, enhanced with it
- **Service Workers**: For offline capability and performance

### Security Considerations

- **SSL/TLS**: Self-signed certificates with automatic generation
- **CSRF Protection**: Enabled globally with Flask-WTF
- **Session Security**: Secure cookies, HTTPOnly, SameSite=Lax
- **Rate Limiting**: Built-in for API endpoints
- **Input Validation**: WTForms for all user inputs

### Performance Optimizations

1. **Raspberry Pi Specific**:

   - Reduced animations and glassmorphism effects
   - Minified assets with gzip compression
   - Optimized SQLite settings for SD cards
   - Memory-efficient session handling
2. **Caching Strategy**:

   - Static file caching (1 year)
   - Database query caching
   - Session-based caching for expensive operations
3. **Database Optimizations**:

   - WAL mode for concurrent access
   - Proper indexing on foreign keys
   - Connection pooling with StaticPool
   - Automatic cleanup of old records

### Integration Points

1. **TP-Link Tapo Smart Plugs**:

   - PyP100 library for device control
   - Status monitoring and scheduling
   - Automatic power management
2. **Email Notifications**:

   - Guest request notifications
   - Job completion alerts
   - System status updates
3. **File Uploads**:

   - Support for STL, OBJ, 3MF, AMF, GCODE
   - Secure file handling with validation
   - Organized storage in uploads/ directory

### Common Development Tasks

When adding new features:

1. **New Blueprint**: Create in `blueprints/`, register in `app.py`
2. **Database Model**: Add to `models.py`, create migration if needed
3. **Frontend Assets**:
   - CSS in `static/css/components.css`
   - JavaScript in `static/js/`
   - Run `npm run build:css` after CSS changes
4. **Logging**: Use `get_logger("component_name")` for consistent logging
5. **Permissions**: Add new permissions to `UserPermission` model

### Debugging Tips

- Check logs in `logs/` directory for component-specific issues
- Use `--debug` flag for development server
- Database locked errors: Check for WAL files (`*.db-wal`, `*.db-shm`)
- SSL issues: Regenerate certificates with `utils/ssl_config.py`
- Performance issues: Check `/api/stats` endpoint for metrics

# Admin Panel Tab-Probleme behoben

## Problem
Die Tabs "Logs", "System" und "Benutzer" im Admin Panel funktionierten nicht korrekt.

## Ursachen
1. **Fehlende Template-Variablen**: Die Routes übergaben nicht die erwarteten Variablen (`active_tab`, `users`, `printers`, `logs`)
2. **Fehlende API-Endpunkte**: Keine API-Endpunkte für Logs-Funktionalität
3. **JavaScript-Initialisierung**: Logs wurden nicht automatisch geladen
4. **Template-Pfade**: Falsche Template-Pfade in einigen Routes

## Behobene Probleme

### 1. Admin Routes korrigiert (`backend/blueprints/admin_unified.py`)
- ✅ **users_overview()**: Lädt jetzt alle Benutzer und übergibt `active_tab='users'`
- ✅ **printers_overview()**: Lädt jetzt alle Drucker und übergibt `active_tab='printers'`
- ✅ **logs_overview()**: Lädt jetzt Logs und übergibt `active_tab='logs'`
- ✅ **system_health()**: Übergibt jetzt `active_tab='system'`
- ✅ **maintenance()**: Übergibt jetzt `active_tab='maintenance'`

### 2. Neue API-Endpunkte hinzugefügt
- ✅ **GET /admin/api/logs**: Logs abrufen mit Level-Filter
- ✅ **POST /admin/api/logs/export**: Logs exportieren (CSV, JSON, TXT)
- ✅ **GET /admin/api/system/status**: System-Status mit CPU, RAM, Disk
- ✅ **POST /admin/api/test/create-sample-logs**: Test-Logs erstellen

### 3. JavaScript-Funktionalität erweitert (`backend/static/js/admin-unified.js`)
- ✅ **Event-Listener für Logs**: Refresh, Export, Level-Filter
- ✅ **Automatisches Laden**: Logs werden automatisch geladen wenn Tab aktiv
- ✅ **API-URLs korrigiert**: Richtige Pfade für Admin-API
- ✅ **Export-Funktionalität**: Download von Logs als Datei

### 4. Template-Integration
- ✅ **Einheitliches Template**: Alle Tabs verwenden `admin.html`
- ✅ **Korrekte Variablen**: `active_tab`, `users`, `printers`, `logs`, `stats`
- ✅ **Tab-Navigation**: Links zeigen aktiven Tab korrekt an

## Funktionalität

### Benutzer-Tab
- Zeigt alle registrierten Benutzer
- Bearbeiten/Löschen von Benutzern
- Benutzer hinzufügen

### Drucker-Tab  
- Zeigt alle konfigurierten Drucker
- Status-Anzeige (Online/Offline)
- Drucker-Verwaltung

### Logs-Tab
- System-Logs mit verschiedenen Leveln (DEBUG, INFO, WARNING, ERROR, CRITICAL)
- Filter nach Log-Level
- Export-Funktionalität (CSV, JSON, TXT)
- Automatisches Refresh

### System-Tab
- System-Informationen (CPU, RAM, Disk)
- Erweiterte Einstellungen
- Wartungsfunktionen

## Test-Funktionalität
```bash
# Test-Logs erstellen
curl -X POST http://localhost:5000/admin/api/test/create-sample-logs \
  -H "Content-Type: application/json" \
  -H "X-CSRFToken: <token>"
```

## Nächste Schritte
1. Server neu starten um Änderungen zu laden
2. Als Admin einloggen
3. Admin Panel aufrufen: `/admin`
4. Tabs testen: Benutzer, Drucker, Logs, System
5. Test-Logs erstellen und Logs-Funktionalität testen

Alle Admin Panel Tabs sollten jetzt korrekt funktionieren!
