core/Projektarbeit-MYP
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Projektarbeit-MYP/backend/CLAUDE.md

7.1 KiB
Raw Blame History

CLAUDE.md

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

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