# 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
```sql
- 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
```python
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
```python
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
```python
conn = get_db_connection()
cur = conn.cursor(cursor_factory=RealDictCursor)
try:
    # queries
    conn.commit()
finally:
    cur.close()
    conn.close()
```

## Testing & Verification

### Check Logs
```bash
docker-compose logs admin-panel | tail -50
```

### Verify Container Status
```bash
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