Hetzner-Backup/v2_adminpanel/CLAUDE.md

CLAUDE.md - AI Coding Assistant Guidelines

Core Principles

• Structured Code First: Write code that is well-organized from the start to avoid future refactoring
• YAGNI (You Aren't Gonna Need It): Only implement what is currently needed, not what might be needed

Project Structure

v2_adminpanel/
├── routes/          # Blueprint-based route handlers
├── templates/       # Jinja2 templates
├── utils/          # Utility modules
├── leads/          # Leads module with own templates/routes
└── core/           # Core functionality (error handlers, logging, monitoring)

Database Schema Reference

license_heartbeats

- id BIGSERIAL
- license_id INTEGER
- hardware_id VARCHAR(255)
- ip_address INET
- user_agent VARCHAR(500)
- app_version VARCHAR(50)
- timestamp TIMESTAMP
- session_data JSONB
(NO response_time column!)

Common Tables

• customers - Customer records
• licenses - License keys and configuration
• users - Admin panel users
• anomaly_detections - Security anomaly tracking
• audit_log - System audit trail

Template Parameter Contracts

error.html

render_template('error.html',
    error='Error message',        # NOT error_message!
    details='Optional details',   # Optional
    error_code=404,              # Optional
    request_id='uuid'            # Optional
)

Common Template Parameters

• All templates expect current_user in session context
• Use error not error_message for error displays
• Flash messages use categories: 'success', 'error', 'warning', 'info'

Pre-Implementation Checklist

Before Writing Routes

• Check if similar route exists with grep -r "route_name" .
• Verify template exists and check expected parameters
• Confirm all imported modules exist
• Check if login_required decorator is needed

Before Database Queries

• Verify table exists in init.sql
• Confirm all column names with grep "CREATE TABLE table_name" -A 20
• Check for required indexes
• Consider partition requirements for time-series data

Before Modifying Templates

• Check which routes use this template
• Verify all passed parameters are used
• Maintain consistent styling with existing templates

Common Patterns

Error Handling

try:
    # operation
except Exception as e:
    logger.error(f"Error in operation: {str(e)}")
    return render_template('error.html', 
                         error='Specific error message',
                         details=str(e))

Database Connections

conn = get_db_connection()
cur = conn.cursor(cursor_factory=RealDictCursor)
try:
    # queries
    conn.commit()
finally:
    cur.close()
    conn.close()

Testing & Verification

Check Logs

docker-compose logs admin-panel | tail -50

Verify Container Status

docker-compose ps

Common Issues to Avoid

1. Parameter Mismatches: Always verify template expectations
2. Missing Columns: Check schema before writing queries
3. Import Errors: Ensure utils/init.py exists
4. Transaction Errors: Properly handle PostgreSQL transactions
5. Creating Unnecessary Files: Check if functionality exists before creating new files

Docker Environment

• Service name: admin-panel (not adminpanel)
• Database host: postgres
• Default port: 5000
• Behind nginx proxy

Code Style Rules

• NO comments unless explicitly requested
• Follow existing patterns in the codebase
• Use existing utilities before creating new ones
• Maintain consistent error handling
• Always use absolute paths for file operations

YAGNI Reminders

• Don't add features "for the future"
• Don't create generic solutions for single use cases
• Don't add configuration options that aren't needed now
• Don't abstract code that's only used once
• Implement exactly what's requested, nothing more

Update Log

• 2025-06-21: Created initial version after fixing monitoring parameter mismatch
• 2025-06-21: Added response_time column issue to known problems