82 lines
2.7 KiB
Markdown
82 lines
2.7 KiB
Markdown
# 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 |