# hlessio/app-preventivi-modulari architecture

> Architecture diagram of the GitHub repository hlessio/app-preventivi-modulari, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hlessio/app-preventivi-modulari
- Repository: https://github.com/hlessio/app-preventivi-modulari

## Overview

##### 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.)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (UI Layer)"
        direction TB
        BrowserUI["Browser UI\n(HTML5, Tailwind CSS)\nHTMX partial updates, Alpine.js"]:::frontend
        Templates["Jinja2 Templates"]:::frontend
    end

    %% Backend API Layer
    subgraph "Backend API"
        direction TB
        FastAPIApp["FastAPI App\n(FastAPI, Pydantic, Jinja2)"]:::backend
        Models["Pydantic Models"]:::backend
        Schemas["JSON Schemas"]:::backend
        subgraph "Services"
            direction TB
            DocTemplateService["Document Template Service"]:::backend
            PDFExportService["PDF Export Service"]:::backend
            PreventivoCalculator["Preventivo Calculator"]:::backend
            PreventivoService["Preventivo Service"]:::backend
        end
        ORMModels["SQLAlchemy Models"]:::backend
        DBConfig["Database Config & Init"]:::backend
        Migrations["Alembic Migrations"]:::backend
    end

    %% Persistence Layer
    DB["Database\n(SQLite / PostgreSQL)"]:::db

    %% PDF Engine
    subgraph "PDF Engine"
        direction TB
        WeasyPrint["WeasyPrint"]:::pdf
        SetupWeasy["setup_weasyprint.sh"]:::pdf
        StartServer["start_server.sh"]:::pdf
    end

    %% External Services
    LLMService["External LLM Service"]:::external

    %% Connections
    BrowserUI -->|"HTMX / HTTP Requests"| FastAPIApp
    Templates -->|renders| BrowserUI
    FastAPIApp -->|"validate input"| Models
    FastAPIApp -->|"validate JSON"| Schemas
    FastAPIApp -->|"call service"| PreventivoService
    PreventivoService --> PreventivoCalculator
    PreventivoService --> DocTemplateService
    DocTemplateService --> FastAPIApp
    PreventivoService -->|"CRUD operations"| ORMModels
    ORMModels --> DB
    FastAPIApp --> DBConfig
    FastAPIApp --> Migrations
    FastAPIApp -->|"render HTML"| WeasyPrint
    FastAPIApp -->|"PDF request"| PDFExportService
    PDFExportService --> WeasyPrint
    WeasyPrint -->|returns PDF| BrowserUI
    FastAPIApp -->|"future API calls"| LLMService

    %% Click Events
    click Templates "https://github.com/hlessio/app-preventivi-modulari/tree/main/app/templates/"
    click FastAPIApp "https://github.com/hlessio/app-preventivi-modulari/blob/main/app/main.py"
    click Models "https://github.com/hlessio/app-preventivi-modulari/blob/main/app/models.py"
    click Schemas "https://github.com/hlessio/app-preventivi-modulari/blob/main/app/schemas/*.schema.json"
    click DocTemplateService "https://github.com/hlessio/app-preventivi-modulari/blob/main/app/services/document_template_service.py"
    click PDFExportService "https://github.com/hlessio/app-preventivi-modulari/blob/main/app/services/pdf_export_service.py"
    click PreventivoCalculator "https://github.com/hlessio/app-preventivi-modulari/blob/main/app/services/preventivo_calculator.py"
    click PreventivoService "https://github.com/hlessio/app-preventivi-modulari/blob/main/app/services/preventivo_service.py"
    click ORMModels "https://github.com/hlessio/app-preventivi-modulari/blob/main/app/db_models.py"
    click DBConfig "https://github.com/hlessio/app-preventivi-modulari/blob/main/app/database.py"
    click DBConfig "https://github.com/hlessio/app-preventivi-modulari/blob/main/app/init_db.py"
    click Migrations "https://github.com/hlessio/app-preventivi-modulari/tree/main/alembic/"
    click SetupWeasy "https://github.com/hlessio/app-preventivi-modulari/blob/main/setup_weasyprint.sh"
    click StartServer "https://github.com/hlessio/app-preventivi-modulari/blob/main/start_server.sh"
    click LLMService "https://github.com/hlessio/app-preventivi-modulari/blob/main/LLM_INTEGRATION_DESIGN.md"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#509EFF,color:#000
    classDef backend fill:#D7F4D7,stroke:#42B741,color:#000
    classDef db fill:#FFE1B3,stroke:#FFA500,color:#000
    classDef pdf fill:#E3D7FF,stroke:#A46EFF,color:#000
    classDef external fill:#ECECEC,stroke:#A0A0A0,color:#000
```
