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

FastAPI routes handle HTTP requests
Printer state is managed through bambulabs_api library
UI updates via HTMX endpoints returning partial HTML

Development Environment

Setup

# 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:

{
    "printer": {
        "ip": "10.0.2.10",
        "access_code": "e0f815a7",
        "serial": "00M09A360300272"
    }
}

Common Tasks

Adding New Printer Data

Add new field to /status endpoint in main.py
Update status dictionary in the route handler
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

2.7 KiB Raw Permalink Blame History