Projektarbeit-MYP/backend/CLAUDE.md

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

# 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

# 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

# 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

# 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

   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

   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