# MathLesson — Product Requirements Document

**Author:** AIRchetipo
**Date:** 2026-05-08
**Version:** 1.0

---

## Elevator Pitch

> MathLesson e una piattaforma marketplace per trovare tutor di matematica e fisica in tutta Italia, richiedere lezioni online o in presenza e gestire agenda, prezzi e promemoria in modo semplice.
>
> For **studenti delle superiori, universitari e tutor privati**, who has the problem of **trovare o gestire ripetizioni senza dispersione tra chat, calendari generici e fogli Excel**, **MathLesson** is a **marketplace verticale per ripetizioni di matematica e fisica** that **connette studenti e tutor disponibili, gestendo profili, prezzi, richieste, agenda, promemoria e recensioni**. Unlike **Google Calendar, WhatsApp, fogli Excel o portali generalisti**, our product **unisce ricerca tutor, disponibilita, prezzi differenziati e gestione richieste in un flusso unico pensato per le ripetizioni**.

---

## Vision

Rendere piu semplice e affidabile l'incontro tra studenti che cercano supporto in matematica e fisica e tutor qualificati che vogliono organizzare lezioni, disponibilita e prezzi in modo professionale.

### Strategic Objectives

1. Creare un marketplace nazionale leggero per tutor di matematica e fisica.
2. Ridurre il tempo necessario agli studenti per trovare un tutor disponibile e adatto al proprio livello.
3. Offrire ai tutor uno strumento semplice per gestire profilo, prezzi, agenda, richieste e promemoria.
4. Validare la metrica primaria delle lezioni confermate prima di introdurre monetizzazione.
5. Costruire fiducia tramite recensioni lasciate dopo lezioni accettate e completate.

### Long-Term Impact

MathLesson puo diventare il punto di riferimento verticale per ripetizioni STEM in Italia, migliorando accessibilita, trasparenza dei prezzi e affidabilita del matching tra studenti e tutor.


---

## User Personas

### Persona 1: Giulia Rossi

**Role:** Studentessa delle superiori
**Age:** 17 | **Background:** Frequenta il quarto anno di liceo scientifico e ha difficolta ricorrenti in matematica e fisica, soprattutto prima di verifiche e interrogazioni.

**Goals:**
1. Trovare rapidamente un tutor affidabile nella propria citta o disponibile online.
2. Capire subito prezzo, materie coperte e disponibilita.
3. Richiedere una lezione senza dover gestire lunghe conversazioni su WhatsApp.
4. Lasciare una recensione se la lezione e stata utile.

**Pain Points:**
1. Fatica a capire quali tutor siano davvero disponibili.
2. Trova informazioni frammentate tra annunci, passaparola e chat.
3. Non sempre conosce il prezzo prima di contattare il tutor.
4. Ha bisogno di fiducia prima di scegliere una persona sconosciuta.

**Behaviors & Tools:**
Usa smartphone, browser mobile, WhatsApp, email e strumenti scolastici digitali. Cerca spesso da mobile e confronta piu opzioni prima di contattare qualcuno.

**Motivations:** Migliorare i voti, ridurre l'ansia prima delle verifiche e trovare una persona capace di spiegare in modo chiaro.
**Tech Savviness:** Media

#### Customer Journey — Giulia Rossi

| Phase | Action | Thought | Emotion | Opportunity |
|---|---|---|---|---|
| Awareness | Cerca online un tutor di matematica o fisica nella sua zona. | "Mi serve qualcuno affidabile, meglio se vicino o disponibile online." | Urgenza e incertezza | Posizionare il prodotto come ricerca rapida e verticale per ripetizioni. |
| Consideration | Confronta tutor per materia, citta, prezzo, bio e recensioni. | "Questo tutor sembra adatto al mio livello? Quanto costa?" | Cauta fiducia | Mostrare informazioni chiare e recensioni visibili. |
| First Use | Si registra e invia una richiesta di lezione a un tutor. | "Spero che risponda presto e accetti." | Attesa | Rendere la richiesta semplice e confermare lo stato in modo evidente. |
| Regular Use | Consulta richieste, lezioni confermate e promemoria. | "So quando ho lezione e non devo cercare nei messaggi." | Controllo | Dashboard studente con prossime lezioni e notifiche. |
| Advocacy | Lascia una recensione dopo la lezione e consiglia il servizio. | "Mi ha aiutata, posso segnalarlo ad altri." | Soddisfazione | Facilitare recensioni post-lezione e condivisione. |

---

### Persona 2: Marco Bianchi

**Role:** Tutor privato di matematica e fisica
**Age:** 28 | **Background:** Laureato o studente magistrale in ambito scientifico, offre ripetizioni a studenti delle superiori e universitari nel tempo libero.

**Goals:**
1. Farsi trovare da studenti interessati in tutta Italia.
2. Gestire profilo, bio, materie, citta e prezzi differenziati.
3. Controllare agenda e disponibilita senza usare strumenti separati.
4. Accettare o rifiutare manualmente le richieste per mantenere controllo sul calendario.

**Pain Points:**
1. Riceve richieste sparse su WhatsApp, email e passaparola.
2. Deve spiegare spesso prezzi e disponibilita.
3. Rischia sovrapposizioni di appuntamenti.
4. Ha bisogno di costruire reputazione tramite recensioni verificabili.

**Behaviors & Tools:**
Usa laptop e smartphone, calendario personale, email, chat e documenti condivisi. Preferisce strumenti semplici e veloci da aggiornare.

**Motivations:** Aumentare le lezioni confermate, professionalizzare la propria attivita e ridurre il tempo amministrativo.
**Tech Savviness:** Medio-alta

#### Customer Journey — Marco Bianchi

| Phase | Action | Thought | Emotion | Opportunity |
|---|---|---|---|---|
| Awareness | Scopre la piattaforma come modo per ricevere nuove richieste. | | | |
| Consideration | Valuta se registrarsi e configurare profilo, materie e prezzi. | | | |
| First Use | Crea il profilo tutor, inserisce disponibilita e riceve le prime richieste. | | | |
| Regular Use | Gestisce agenda, accetta/rifiuta richieste e consulta notifiche. | | | |
| Advocacy | Mantiene il profilo aggiornato e invita studenti soddisfatti a lasciare recensioni. | | | |

---

## Goals & Success Metrics

La metrica primaria di successo e il numero di lezioni confermate. Il prodotto funziona se genera matching reali tra studenti e tutor, non solo registrazioni o visite.

Metriche di prodotto:
1. Numero di lezioni confermate.
2. Numero di tutor registrati.
3. Numero di tutor attivi con disponibilita aggiornata.
4. Numero di richieste inviate dagli studenti.
5. Tasso di conversione richiesta-conferma.
6. Numero di recensioni pubblicate dopo lezioni completate.
7. Percentuale di utenti ricorrenti.

### Business KPIs

1. Lezioni confermate mensili.
2. Tutor attivi mensili.
3. Tasso di attivazione tutor: profilo completo + almeno una disponibilita inserita.
4. Tasso di conferma richieste.
5. Base utenti registrati per ruolo.
6. Validazione futura della monetizzazione tramite abbonamento tutor o commissione per lezione confermata.

---

## Product Scope

### MVP — Minimum Viable Product

1. Registrazione e login per studenti e tutor.
2. Profilo tutor con bio, citta, materie, modalita online/in presenza e recensioni.
3. Prezzi configurabili dal tutor, separati per studenti delle superiori e universitari.
4. Ricerca tutor in tutta Italia per materia, citta, modalita e fascia prezzo.
5. Agenda tutor con disponibilita.
6. Richiesta lezione da parte dello studente.
7. Accettazione o rifiuto manuale da parte del tutor.
8. Promemoria via email e notifiche in-app.
9. Recensioni lasciabili solo dopo una lezione accettata/completata.
10. Dashboard separate per tutor e studente.

### Growth Features (Post-MVP)

1. Filtri avanzati per voto medio recensioni, disponibilita immediata e livello scolastico.
2. Gestione lezioni ricorrenti.
3. Messaggistica interna tra studente e tutor.
4. Verifica profilo tutor e badge qualita.
5. Report lezioni e storico avanzato per tutor.
6. Monetizzazione tramite abbonamento tutor o commissione sulle lezioni confermate.

### Vision (Future)

1. Pagamenti integrati.
2. Matching automatico suggerito in base a materia, livello, citta, budget e disponibilita.
3. App mobile dedicata.
4. Estensione ad altre materie STEM.
5. Strumenti didattici integrati per materiali, esercizi e follow-up.
6. Marketplace con reputazione verificata e qualita controllata.

---

## Technical Architecture

> **Proposed by:** Leonardo (Architect)

### System Architecture

MathLesson sara una web application server-rendered basata su Delphi. DMVCFramework gestira routing, controller, middleware e logica HTTP. TemplatePro renderizzera le pagine HTML lato server. HTMX aggiungera interazioni dinamiche leggere per ricerca, richieste, agenda e notifiche senza introdurre una SPA JavaScript.

**Architectural Pattern:** Modular Monolith server-rendered web application

**Main Components:**
1. Auth module: registrazione, login, sessioni, ruoli studente/tutor.
2. Users module: dati account e preferenze.
3. Tutor Profiles module: bio, citta, materie, prezzi, modalita e visibilita.
4. Availability module: agenda e slot disponibili.
5. Lesson Requests module: richiesta, accettazione, rifiuto, conferma e stato lezione.
6. Reviews module: recensioni post-lezione accettata/completata.
7. Notifications module: notifiche in-app e promemoria email.
8. Search module: filtri per materia, citta, modalita e prezzo.

### Technology Stack

| Layer | Technology | Version | Rationale |
|---|---|---|---|
| Language | Delphi | 12 Athens | Vincolo tecnico esplicito, produttivo per backend web e logica applicativa. |
| Backend Framework | DMVCFramework | 3.x | Framework REST/web Delphi pragmatico e adatto a monolite modulare. |
| Frontend Framework | HTMX + TemplatePro | HTMX 1.9.x/2.x, TemplatePro compatibile DMVCFramework | UI server-rendered con interazioni dinamiche senza complessita SPA. |
| Database | PostgreSQL | 16 | Database relazionale affidabile per utenti, tutor, disponibilita, richieste e recensioni. |
| ORM | FireDAC/data access layer custom | Delphi 12 compatible | Standard Delphi maturo per accesso database e query controllate. |
| Auth | Session cookie HTTP-only | | Preferibile per web server-rendered; riduce esposizione token lato client. |
| Testing | DUnitX + Postman/Newman | | Test unitari/integration backend e regression test sulle route/API. |

### Project Structure

**Organizational pattern:** Modular Monolith con separazione tra web layer, domain, application e infrastructure.

```
server/
  src/
    MathLessons.Web/
      Controllers/
      Views/
      Partials/
      Static/
      Middleware/
    MathLessons.Domain/
      Users/
      Tutors/
      Availability/
      LessonRequests/
      Reviews/
      Notifications/
    MathLessons.Application/
      Services/
      UseCases/
    MathLessons.Infrastructure/
      Persistence/
      Email/
      Auth/
    MathLessons.Shared/
  tests/
    MathLessons.Tests/
database/
  migrations/
docs/
```

### Development Environment

Sviluppo locale con Delphi 12 Athens, PostgreSQL locale o containerizzato, configurazione ambiente tramite file non versionato, server DMVCFramework avviabile in locale e template HTML gestiti con TemplatePro.

**Required tools:** Delphi 12 Athens, DMVCFramework 3.x, PostgreSQL 16, FireDAC, DUnitX, Postman/Newman, Git, GitHub Actions o Azure DevOps, reverse proxy per produzione.

### CI/CD & Deployment

**Build tool:** Delphi compiler tramite IDE/build script o MSBuild su runner Windows.

**Pipeline:** Build applicazione Delphi, esecuzione test DUnitX, regression test HTTP con Newman, packaging artefatto, deploy su VPS.

**Deployment:** Applicazione DMVCFramework deployata come servizio web dietro reverse proxy HTTPS. PostgreSQL gestito o installato su VPS per MVP. Promemoria gestiti da job schedulato Delphi o servizio dedicato.

**Target infrastructure:** VPS Windows o Linux compatibile con lo stack Delphi scelto, reverse proxy Nginx/Apache/Caddy, PostgreSQL 16, TLS obbligatorio.

### Architecture Decision Records (ADR)

1. ADR-001: Usare Modular Monolith invece di microservizi per ridurre complessita nel MVP.
2. ADR-002: Usare Delphi 12 Athens e DMVCFramework per rispettare il vincolo tecnico e mantenere produttivita backend.
3. ADR-003: Usare TemplatePro e HTMX per evitare SPA JavaScript e mantenere rendering server-side.
4. ADR-004: Usare PostgreSQL 16 per dati relazionali, ricerca filtrata e consistenza delle lezioni.
5. ADR-005: Usare session cookie HTTP-only per l'autenticazione web server-rendered.
6. ADR-006: Rinviare pagamenti e monetizzazione a una fase successiva per validare prima la metrica lezioni confermate.

---

## Functional Requirements

**Account & Auth**

FR1. Il sistema deve permettere la registrazione e il login di utenti con ruolo studente o tutor.

FR2. Il sistema deve proteggere le aree riservate con sessioni sicure e controllo dei permessi per ruolo.

**Tutor Profile**

FR3. Il tutor deve poter creare e modificare un profilo pubblico con bio, citta, materie insegnate e modalita online/in presenza.

FR4. Il tutor deve poter configurare prezzi separati per studenti delle superiori e studenti universitari.

FR5. Lo studente deve poter visualizzare la scheda tutor con bio, citta, materie, prezzi, modalita disponibili e recensioni.

**Search & Discovery**

FR6. Lo studente deve poter cercare tutor in tutta Italia filtrando per materia, citta, modalita online/in presenza e fascia prezzo.

FR7. Il sistema deve mostrare nei risultati di ricerca le informazioni essenziali del tutor, inclusi prezzo, citta, materie e valutazione media se disponibile.

**Availability & Agenda**

FR8. Il tutor deve poter gestire la propria agenda inserendo, modificando o rimuovendo disponibilita.

FR9. Lo studente deve poter consultare le disponibilita del tutor prima di inviare una richiesta.

**Lesson Requests**

FR10. Lo studente registrato deve poter inviare una richiesta di lezione indicando tutor, materia, livello scolastico, modalita, data/orario e note opzionali.

FR11. Il tutor deve poter accettare o rifiutare manualmente ogni richiesta ricevuta.

FR12. Quando una richiesta viene accettata, il sistema deve confermare la lezione e aggiornare l'agenda del tutor.

FR13. Il sistema deve impedire o segnalare conflitti di disponibilita per evitare sovrapposizioni di lezioni confermate.

**Notifications & Reminders**

FR14. Il sistema deve inviare notifiche in-app per nuove richieste, accettazioni, rifiuti e lezioni confermate.

FR15. Il sistema deve inviare promemoria email per richieste rilevanti e lezioni confermate.

**Reviews**

FR16. Lo studente deve poter lasciare una recensione solo dopo una lezione accettata/completata.

FR17. Il sistema deve mostrare le recensioni pubblicate nel profilo del tutor.

**Dashboards**

FR18. Il tutor deve avere una dashboard con richieste ricevute, prossime lezioni, prezzi e disponibilita.

FR19. Lo studente deve avere una dashboard con richieste inviate, lezioni confermate e recensioni da lasciare.

---

## Non-Functional Requirements

### Performance

1. Le pagine principali e la ricerca tutor devono rispondere entro 2 secondi in condizioni MVP normali.
2. Le interazioni HTMX principali devono aggiornare solo le porzioni necessarie della pagina.
3. Le query di ricerca devono essere indicizzate almeno per citta, materia, modalita e fascia prezzo.

### Security

1. Le password devono essere salvate solo tramite hashing sicuro.
2. Le sessioni devono usare cookie HTTP-only, secure e SameSite appropriato.
3. HTTPS e obbligatorio in produzione.
4. Il sistema deve applicare controlli di autorizzazione per distinguere azioni studente e tutor.
5. Gli input utente devono essere validati lato server e sanitizzati nei template.
6. Deve essere mantenuto un audit minimo degli eventi importanti: richiesta inviata, accettata, rifiutata, confermata/completata.

### Scalability

1. Il monolite deve essere organizzato in moduli per consentire evoluzione futura senza riscrittura completa.
2. Il database deve supportare crescita nazionale tramite indici e struttura relazionale normalizzata.
3. Il sistema di notifiche deve poter evolvere da job schedulato interno a worker dedicato se il volume cresce.

### Accessibility

1. I flussi principali devono puntare a conformita WCAG 2.1 AA di base.
2. L'interfaccia deve essere responsive per desktop e mobile.
3. Form, pulsanti, errori e notifiche devono essere accessibili da tastiera e leggibili da screen reader.

### Integrations

1. Integrazione email tramite provider SMTP o API compatibile.
2. Nessuna integrazione di pagamento nell'MVP.
3. Possibile integrazione futura con provider pagamenti, calendario esterno e sistemi di verifica profilo tutor.

---

## Next Steps

1. **UX Design** — Define detailed interaction flows and wireframes for MVP features
2. **Detailed Architecture** — Deepen technical decisions on critical areas
3. **Backlog** — Decompose functional requirements into epics and user stories
4. **Validation** — Review with stakeholders and test the riskiest business assumptions

---

_PRD generated via AIRchetipo Product Inception — 2026-05-08_
_Session conducted by: User with the AIRchetipo team_
