# ChefSystem - Bootstrap Instructions

## Project Overview
ChefSystem è un ricettario digitale per gestire prompt templates per AI. Permette di salvare, categorizzare e riutilizzare prompt, tracciando anche gli output generati da ogni esecuzione. Fase 1 è completamente manuale (copy/paste), con architettura preparata per futura integrazione API Anthropic.

## Source of Instructions
Questo progetto viene guidato da **Claude Chat** (web interface) che analizza i requisiti e passa istruzioni progressive a **Claude Code** per l'implementazione.

Claude Code riceve milestone sequenziali e implementa il codice seguendo queste specifiche.

## Architecture

**Type**: Desktop GUI Application (PyQt6)

**Target OS**: Linux (Mini PC)

**Python Version**: 3.10+

**Environment**: venv (virtual environment obbligatorio)

**Project Location**: `/mnt/ssd/data/python-lab/ChefSystem`

## Directory Structure
```
ChefSystem/
├── src/
│   ├── __init__.py
│   ├── main.py                 # Entry point
│   ├── database/
│   │   ├── __init__.py
│   │   ├── db_manager.py       # SQLite connection & migrations
│   │   └── models.py           # Recipe & Output models
│   ├── ui/
│   │   ├── __init__.py
│   │   ├── main_window.py      # Main application window
│   │   ├── recipe_editor.py    # Recipe create/edit dialog
│   │   ├── output_manager.py   # Output save/view dialog
│   │   └── widgets/            # Custom widgets
│   ├── services/
│   │   ├── __init__.py
│   │   ├── recipe_service.py   # Business logic for recipes
│   │   └── output_service.py   # Business logic for outputs
│   └── utils/
│       ├── __init__.py
│       └── file_utils.py       # File operations helper
├── database/
│   └── chef.db                 # SQLite database (created at runtime)
├── outputs/                    # Output files organized by recipe
│   └── recipe_{id}/
├── config/
│   └── settings.json           # App configuration
├── tests/
│   └── test_*.py
├── requirements.txt
├── BOOTSTRAP.md                # This file
├── PROJECT_STATUS.md           # Maintained by Claude Code
└── README.md
```

## Core Modules

- **database/db_manager.py**: Gestione connessione SQLite, inizializzazione schema, migrations
- **database/models.py**: Data classes per Recipe e Output con metodi CRUD
- **ui/main_window.py**: Finestra principale con lista ricette, search bar, actions
- **ui/recipe_editor.py**: Dialog per creare/modificare ricette (form con tutti i campi)
- **ui/output_manager.py**: Dialog per salvare/visualizzare output di una ricetta
- **services/recipe_service.py**: Business logic per operazioni su ricette
- **services/output_service.py**: Business logic per gestione output e file system

## Technical Requirements

### Dependencies
```
PyQt6>=6.6.0
```

### Database Schema

**Table: recipes**
```sql
CREATE TABLE recipes (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL UNIQUE,
    prompt_text TEXT NOT NULL,
    tags TEXT,                      -- Comma-separated tags
    description TEXT,
    notes TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

**Table: outputs**
```sql
CREATE TABLE outputs (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    recipe_id INTEGER NOT NULL,
    filename TEXT NOT NULL,
    filepath TEXT NOT NULL,         -- Relative path from outputs/
    file_type TEXT,                 -- Extension (.pdf, .docx, etc.)
    file_size INTEGER,              -- Size in bytes
    execution_notes TEXT,
    generated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (recipe_id) REFERENCES recipes(id) ON DELETE CASCADE
);
```

### Configuration
- **Format**: JSON
- **Location**: `config/settings.json`
- **Key settings**: 
  - database_path
  - outputs_directory
  - window_geometry (last position/size)
  - recent_tags (for autocomplete)

### Data Persistence
- **Database**: SQLite (`database/chef.db`)
- **Output files**: Organizzati in `outputs/recipe_{id}/` per mantenere ordine
- **Backup strategy**: SQLite database facilmente backuppabile, outputs organizzati per recipe

### Logging
- **Level**: INFO (DEBUG se necessario per troubleshooting)
- **Output**: Console durante sviluppo, rotating file in produzione
- **Format**: `%(asctime)s - %(name)s - %(levelname)s - %(message)s`

## Development Standards

### Code Style
- PEP 8 compliance
- Type hints per parametri e return values
- Docstrings per classi e funzioni pubbliche
- Nomi variabili descrittivi (no abbreviazioni criptiche)

### Error Handling
- Try/except su operazioni database e file I/O
- Logging di errori con traceback
- User-friendly error messages in UI (QMessageBox)
- Validazione input utente prima di operazioni database

### Testing
- Unit tests per models e services
- Integration tests per database operations
- Manual testing per UI (lista scenari in PROJECT_STATUS.md)

## Key Features - Fase 1

### Recipe Management
- **Create**: Form con name, prompt_text (QTextEdit), tags, description, notes
- **Read**: Lista ricette con search/filter, dettaglio ricetta
- **Update**: Modifica esistente, aggiorna updated_at automaticamente
- **Delete**: Con conferma, elimina anche outputs associati (CASCADE)
- **Copy to Clipboard**: Button per copiare prompt_text negli appunti

### Output Management
- **Save Output**: Dialog per selezionare file da filesystem, inserire execution_notes
- **File Organization**: Automatico in `outputs/recipe_{id}/filename`
- **List Outputs**: Visualizzazione output per ricetta con data, note, dimensione
- **Open File**: Double-click o button per aprire file con app di sistema
- **Search Outputs**: Ricerca globale per filename o execution_notes

### Search & Filter
- **Recipe Search**: By name (case-insensitive)
- **Tag Filter**: Multi-select per filtrare per uno o più tags
- **Combined**: Search + filter contemporaneamente

## UI Design Principles

### Main Window Layout
```
┌─────────────────────────────────────────────────┐
│ [New Recipe] [Edit] [Delete] [Copy Prompt]      │
├─────────────┬───────────────────────────────────┤
│             │                                    │
│  Recipe     │  Recipe Details Panel              │
│  List       │  - Name                            │
│  (Tree/     │  - Tags                            │
│   List)     │  - Description                     │
│             │  - Prompt Text (preview)           │
│  Search:    │  - Dates                           │
│  [____]     │                                    │
│             │  [View Full Prompt] [Manage Outputs]│
│  Tags:      │                                    │
│  [Filter]   │  Recent Outputs:                   │
│             │  - output1.pdf (date)              │
│             │  - output2.docx (date)             │
└─────────────┴───────────────────────────────────┘
```

### Dialogs
- **Recipe Editor**: Modal dialog con form completo, Cancel/Save buttons
- **Output Manager**: List di outputs con Add/Open/Delete, execution notes editing

## Implementation Notes

### PyQt6 Best Practices
- Usa QMainWindow per finestra principale
- Signal/slot pattern per UI events
- QThread per operazioni lunghe (se necessarie in futuro)
- QSettings per persistenza configurazione UI

### Database Best Practices
- Connection pooling non necessario (single-user app)
- Transazioni per operazioni multiple
- Prepared statements per sicurezza
- PRAGMA foreign_keys = ON

### File System
- Usa Path (pathlib) per operazioni filesystem
- Verifica spazio disco prima di salvare file
- Handle graceful se file output eliminato manualmente

### Future-Proofing for API Integration
- Separazione netta tra UI, Business Logic, Data Layer
- RecipeService può diventare RecipeExecutor in futuro
- Output model già pronto per tracking esecuzioni automatiche

## Project Status Tracking

Lo stato di avanzamento del progetto è mantenuto in **PROJECT_STATUS.md**.

Claude Code deve:
- Creare PROJECT_STATUS.md alla prima milestone
- Aggiornarlo dopo ogni milestone completata
- Documentare decisioni tecniche prese
- Segnalare blocchi o problemi

## Instructions for Claude Code

1. Leggi questo file all'inizio di ogni sessione
2. Implementa le milestone ricevute da Claude Chat
3. Mantieni aggiornato PROJECT_STATUS.md
4. Segui gli standard di sviluppo specificati
5. Testa ogni funzionalità implementata prima di considerarla completata
6. Per PyQt6: testa UI manualmente, descrivi scenari di test in PROJECT_STATUS.md