# AI Coding Agent Instructions

## Project Overview
This is a 3D printer management web application that provides a real-time interface for monitoring and controlling a Bambu Labs printer via their API. The project uses FastAPI for the backend, HTMX for dynamic UI updates, and Jinja2 for templating.

## Architecture

### Key Components
- **FastAPI Backend** (`app/main.py`): Handles HTTP endpoints and printer communication
- **Templates** (`app/templates/`): Jinja2 templates with HTMX for dynamic updates
- **Static Assets** (`app/static/`): CSS and other static files
- **Docker Configuration**: Containerized deployment with live code reloading

### Data Flow
1. FastAPI routes handle HTTP requests
2. Printer state is managed through `bambulabs_api` library
3. UI updates via HTMX endpoints returning partial HTML

## Development Environment

### Setup
```bash
# Build and start the container
docker compose up --build

# Development server runs at:
# - HTTP: http://localhost:8000
# - MQTT: ports 8883 (TLS), 6000 (unencrypted), 990 (WebSocket TLS)
```

### Live Development
- Code changes in `app/` are automatically reloaded
- Container mounts local `app/` directory for immediate updates

## Key Patterns

### Template Structure
- Base template: `templates/base.html`
- Partial templates prefixed with underscore (e.g., `_status.html`, `_connect_area.html`)
- HTMX used for dynamic content updates

### State Management
- Connection state tracked in-memory via global variable
- Printer API interactions wrapped in try/except blocks
- Status updates polled every 500ms via HTMX trigger

### UI Components
- Status panel auto-refreshes using `hx-trigger="every 500ms"`
- Connection state toggles between connect/disconnect UI
- Error handling displayed in status panel

## Integration Points
- **Bambu Labs API**: Primary integration via `bambulabs_api` package
- **MQTT Communication**: Used for real-time printer updates
- **Configuration File**: Printer connection details stored in `app/config.json`:
  ```json
  {
      "printer": {
          "ip": "10.0.2.10",
          "access_code": "e0f815a7",
          "serial": "00M09A360300272"
      }
  }
  ```

## Common Tasks

### Adding New Printer Data
1. Add new field to `/status` endpoint in `main.py`
2. Update status dictionary in the route handler
3. Add corresponding UI element in `_status.html` template

### Error Handling
- Wrap printer API calls in try/except blocks
- Return error status through template context
- Display errors in UI using dedicated error states

## File Reference
- `main.py`: Core application logic and routes
- `templates/_status.html`: Real-time printer status display
- `templates/index.html`: Main page layout and connection UI
- `docker-compose.yaml`: Container configuration and port mappings