How hlessio/app-preventivi-modulari works
Project Type and Purpose
• This is a full-stack web application (“App Preventivi Modulari”) built with FastAPI (Python) on the backend and an HTMX/Alpine.js/Tailwind CSS frontend.
• It generates modular quotes (“preventivi”) stored in a relational database, renders them in HTML/PDF (via Jinja2 + WeasyPrint), and is designed to integrate future LLM services.
Key Components
a. Frontend Client
• Browser UI: HTML5 + Tailwind CSS
• Interactivity: HTMX (partial updates), Alpine.js (local state)
• Template Composition: Jinja2 templates under app/templates
b. Backend API
• FastAPI app (app/main.py)
• Validation & data models: Pydantic (app/models.py, JSON schemas in app/schemas)
• Business logic services (app/services/*.py)
• Database ORM: SQLAlchemy (app/db_models.py, migrations in alembic/)
c. Database
• SQLite (dev) / PostgreSQL (prod) via SQLAlchemy + Alembic migrations
• Stores Quote entities, document templates, user info
d. PDF Export Engine
• WeasyPrint invoked by pdf_export_service.py and shell scripts (setup_weasyprint.sh, start_server.sh)
e. Future External Services
• LLM integration (via REST or gRPC) as designed in LLM_INTEGRATION_DESIGN.md
Relationships and Data Flows
• User → Browser UI → HTMX/Alpine triggers XHR to FastAPI endpoints
• FastAPI endpoint
→ validates input against Pydantic models / JSON Schemas
→ calls business services (preventivo_service, preventivo_calculator, document_template_service)
→ interacts with the database (read/write via SQLAlchemy)
→ assembles a master JSON document
→ returns JSON or calls Jinja2 to render HTML/PDF
• PDF route feeds HTML into WeasyPrint → returns PDF stream to user
• (Future) LLM Service ← API calls JSON master document → returns suggestions or auto-filled data
Architectural Patterns and Principles
• JSON-centric modular architecture: each section of the quote is defined by its own JSON Schema
• Clear separation of concerns:
• Presentation (Jinja2 templates)
• Validation (Pydantic + JSON Schema)
• Business logic (service layer)
• Persistence (ORM + migrations)
• Micro-module templating: quote sections loaded as partials (_intestazione_cliente.html, etc.)