🛂 Passport Booking System

A desktop application for managing passport appointments at Italian Questura offices, built as a university software engineering project.

This project delivers a complete JavaFX plus SQLite appointment-booking system for passport services at a questura, developed by a team of four. The implementation itself is desktop CRUD-style application. The engineering process around it includes: structured requirements, documented MVC architecture, Singleton/Repository/Facade patterns, UML artifacts (use case, activity, sequence, and ER diagrams), JUnit testing, CSV-seeded database bootstrap, Scrum-style sprint execution, and a full technical report.

This repository includes both the implementation and the submitted project report in Documentazione.pdf.

---

Screenshots

Screenshot	Screenshot
Citizen login	Questore login
Booking flow: office selection	Booking flow: time selection
Questore panel: add availability	Questore panel: add citizen

---

Overview

Passport Online streamlines passport-service scheduling between citizens and Questura staff.

• Citizens verify their identity, register, authenticate, and book available slots.
• Questura operators manage availabilities and add new verified citizens.
• Booking coherence is enforced to prevent invalid service states, such as requesting collection before issuance.

The application combines UI, domain rules, persistence, and validation in one production-style JavaFX desktop system.

---

Table of Contents

• Screenshots
• Actors & Use Cases
• Use Case Details
• Architecture & Design
• Implementation
• Sequence Interactions
• Development Process
• Testing & Validation
• Getting Started
• Project Structure
• Documentazione Summary
• Authors

---

Actors & Use Cases

The system has two primary actors, each with a dedicated interface and authentication path.

Questore (Staff)

Authenticated via admin-issued credentials. After login, the questore can:

• Insert new availability slots by providing sede, tipologia, data, and ora.
• Insert new citizens into system registry (Anagrafica) with personal details.

Citizen

Self-registration is available only if the citizen already exists in the registry. After authentication, a citizen can:

• Book appointments selecting service type, office, date, and time.
• Cancel appointments, with cancellation logic preserving booking order.
• View active bookings, synchronized with current database state.

Booking Coherence Rules

• A citizen cannot book collection without a prior issuance flow.
• Booking and cancellation logic prevents inconsistent sequencing.
• Availability views reflect real occupancy at calendar/day level.

---

Use Case Details

Login

At startup, the user chooses identity (citizen or questore) and is routed to the corresponding login page.

Registration (Citizen)

1. Citizen verification checks if personal data exists in Anagrafica.
2. If found and not already registered, account creation is allowed.
3. If not found, registration is blocked until questore insertion.

Insert Availability (Questore)

Questore inserts a new slot with office, type, date, and hour. The slot immediately becomes available for booking.

Booking (Citizen)

1. Select type.
2. Select office.
3. Select day in monthly calendar.
4. Select time in day view.
5. Confirm booking with requirements summary.

Cancel Booking (Citizen)

Cancellation follows the enforced lifecycle and targets the latest compatible booking to avoid out-of-order states.

---

Architecture & Design

Tech Stack

• Java 17
• JavaFX (FXML + CSS)
• SQLite (JDBC)
• Maven Wrapper
• JUnit 5

MVC Pattern

The project follows MVC with clear role separation:

• Model: src/main/java/it/univr/passaporto/models/Model.java
• Controllers: src/main/java/it/univr/passaporto/controllers
• Views: src/main/resources/it/univr/passaporto

View Layer (FXML)

Key view/controller mappings:

• loginCittadino.fxml -> CitizenLogIn
• loginQuestura.fxml -> QuesturaLogIn
• citizenHome.fxml -> CitizenHome
• questHome.fxml -> QuesturaHome
• citizenVerify.fxml -> CitizenVerify
• citizenRegister.fxml -> CitizenRegister
• selectTipo.fxml -> SelectTipo
• selectSede.fxml -> SelectSede
• calendar.fxml -> Calendar
• calendarDay.fxml -> CalendarDay
• confirmReservation.fxml -> ConfirmReservation
• addCitizen.fxml -> AddCitizen
• addDisponibilita.fxml -> AddDisponibilita

Model Design Patterns

• Singleton-style session coordination through Session and SessionManager.
• Repository-like centralized data access through Model query/update APIs.
• Facade-style methods that hide complexity behind intent-focused operations (populateDatabase(), availability queries, booking updates).

---

Implementation

Database

Main SQLite tables:

• Anagrafica: citizen registry
• Account_Cittadino: citizen accounts
• Questore: staff credentials
• Disponibilita: availability and booking occupancy

Database file and seed data:

• DB file: sqlite/passaporto.db
• Mock CSV sources: sqlite/mockup

Validation

The controllers validate input before data persistence:

• Email format validation
• Password strength checks
• Required-field checks
• Booking coherence constraints on issuance/collection flow

---

Sequence Interactions

Login

User -> LoginController -> Model authentication query
     <- session data
     -> route to CitizenHome / QuesturaHome

Registration

User -> CitizenVerifyController -> Model registry check
     <- found / not found
     -> CitizenRegisterController (if found and not registered)

Booking

User -> SelectTipo -> SelectSede -> Calendar -> CalendarDay -> ConfirmReservation
     -> Model slot assignment update

Insert Availability

Questore -> AddDisponibilitaController -> Model insert
         <- success / validation error

---

Development Process

The project followed an Agile/Scrum-inspired incremental workflow with short sprints.

• Sprint planning to define short-term goals and divide tasks.
• Iterative implementation with frequent integration.
• End-of-sprint verification rounds against use-case requirements.
• Continuous refinement of interaction flows and UI behaviors.

This approach improved visibility, accelerated feedback, and reduced integration risk.

---

Testing & Validation

Manual and Scenario-Based Testing

• Authentication and registration checks with valid/invalid input.
• Input validation checks for empty/invalid formats.
• Booking and cancellation consistency checks.
• Data freshness verification against current database state.

Automated Tests

Current JUnit classes:

• src/test/java/it/univr/passaporto/controllers/CitizenVerifyTest.java
• src/test/java/it/univr/passaporto/controllers/CalendarTest.java

Run tests:

./mvnw test

---

Getting Started

Prerequisites

• JDK 17+
• macOS, Linux, or Windows

Run

./mvnw -DskipTests javafx:run

If Java is not detected in your shell, set JAVA_HOME to your JDK 17 path before running mvnw.

Demo Credentials

Seeded local credentials:

• Citizen: asd / asd
• Citizen: claudiabianchi@hotmail.com / claudia
• Questore: asd / asd

---

Project Structure

.
├── .mvn/
├── mvnw
├── mvnw.cmd
├── pom.xml
├── Documentazione.pdf
├── sqlite/
│   ├── mockup/
│   └── passaporto.db
└── src/
    ├── main/
    │   ├── java/
    │   │   ├── module-info.java
    │   │   └── it/univr/passaporto/
    │   │       ├── Application.java
    │   │       ├── controllers/
    │   │       └── models/
    │   └── resources/
    │       ├── images/
    │       └── it/univr/passaporto/
    └── test/
        └── java/it/univr/passaporto/controllers/

---

Documentazione Summary

Documentazione.pdf includes:

• General scope and requirements for passport booking support.
• Use-case specifications for both actors.
• Activity diagrams for authentication, citizen flow, and questore flow.
• Architecture and implementation rationale (MVC, data-access strategy, sequencing).
• Development-process notes (iterative Scrum-based planning and delivery).
• Validation activities, including user testing and JUnit excerpts.

---

Authors

• Xiao Simone
• Zhou Flavio
• Wang William
• Zhou Jia Ye
• Giorgio

Project description submitted: Documentazione.pdf