Appointment Booking System

A general-purpose appointment scheduling application. Use it for any business: clinics, salons, consultants, tutors, or any service that takes bookings. JavaFX desktop app with configurable branding, appointment types, business hours, and optional H2 database persistence.

---

Architecture

Layered Architecture (N-Tier)

┌─────────────────────────────────────────────────────────────┐
│  PRESENTATION (JavaFX)                                       │
│  Controllers, FXML, CSS, Toast, Dialogs, Calendar            │
├─────────────────────────────────────────────────────────────┤
│  APPLICATION (Services)                                      │
│  AuthService, BookingService, ScheduleService,               │
│  PermissionService, PolicyEngine, ReportingService           │
├─────────────────────────────────────────────────────────────┤
│  DOMAIN (Entities, Rules, Events, Policies)                  │
│  Appointment, User, TimeSlot, BookingRuleStrategy,           │
│  AppointmentEventPublisher                                   │
├─────────────────────────────────────────────────────────────┤
│  PERSISTENCE (Repositories)                                  │
│  UserRepository, AppointmentRepository (In-Memory impl.)     │
└─────────────────────────────────────────────────────────────┘

UML Class Diagram (Simplified)

┌──────────────────┐     ┌─────────────────────┐     ┌────────────────────┐
│      User        │     │    Appointment      │     │     TimeSlot       │
├──────────────────┤     ├─────────────────────┤     ├────────────────────┤
│ id, name, email  │     │ id, patient, slot   │     │ startTime, endTime │
│ password         │     │ status, deleted     │     │ overlapsWith()     │
│ isAdmin()        │     │ markDeleted()       │     └────────────────────┘
└────────┬─────────┘     └──────────┬──────────┘              ▲
         │                          │                         │
         │         ┌────────────────┼────────────────┐        │
         │         │                │                │        │
         ▼         ▼                ▼                ▼        │
┌──────────────────┐  ┌────────────────────┐  ┌──────────────────────┐
│  Administrator   │  │ IndividualAppt     │  │ RecurringAppointment │
│  extends User    │  │ FollowUpAppt       │  │ VirtualAppt          │
└──────────────────┘  │ AssessmentAppt     │  │ InPersonAppt         │
                      │ UrgentAppt, etc.   │  └──────────────────────┘
                      └────────────────────┘

┌─────────────────────┐     ┌──────────────────────┐     ┌────────────────────┐
│   BookingService    │────▶│  PermissionService   │     │   PolicyEngine     │
├─────────────────────┤     ├──────────────────────┤     ├────────────────────┤
│ bookAppointment()   │     │ hasPermission()      │     │ registerPolicy()   │
│ modifyAppointment() │     │ requirePermission()  │     │ evaluate()         │
│ cancelAppointment() │     └──────────────────────┘     └────────────────────┘
└──────────┬──────────┘
           │
           ├──▶ AppointmentEventPublisher ──▶ NotificationService
           ├──▶ ScheduleService (getAvailableSlots)
           ├──▶ ReportingService (per-type, cancellation, peak)
           └──▶ AppointmentExpirationService

Design Patterns

Pattern	Usage
Strategy	BookingRuleStrategy — duration, capacity, working hours, cutoff, follow-up dependency
Observer	AppointmentEventPublisher / AppointmentEventListener — event-driven notifications
Policy	Policy<T>, PolicyEngine — extensible business rule validation
Repository	UserRepository, AppointmentRepository — abstraction over storage
Dependency Injection	Constructor-based DI in services; ApplicationContext holds service/repository references for controllers
Central error handling	ErrorHandler — log + user-facing dialog; I18n for titles/messages
Screen constants	ScreenConstants — FXML names and window titles in one place

---

System Features

Advanced Logic

1. Authorization & Permissions — Roles: Administrator, Doctor, Receptionist, Patient. Permissions: BOOK_APPOINTMENT, MODIFY_ANY_APPOINTMENT, VIEW_REPORTS, MANAGE_DOCTORS, MANAGE_ROOMS, VIEW_ANALYTICS, etc. PermissionService enforces before critical actions.
2. Login security — Failed attempt tracking, temporary account lockout after 5 failures (15 min), audit log for LOGIN_SUCCESS / LOGIN_FAILED / LOGIN_BLOCKED.
3. Doctors & Rooms — Doctor and Room entities; appointments can have optional doctorId and roomId. Rules: no double-booking per doctor/room, max appointments per doctor per day.
4. Waitlist — WaitlistService and WaitlistEntry for patients to join a waitlist when no slots are available; FIFO by date.
5. Time-Aware Scheduling — Working hours, booking cutoff, automatic expiration of past appointments.
6. Recurring Appointments — Weekly/monthly series, cancel single occurrence or entire series.
7. Appointment Dependencies — Follow-up appointments can require prior completed appointments.
8. Reporting Engine — Appointments per type, cancellation rate, peak booking hour (dynamic from system data).
9. Smart Notification Triggers — Event-driven (create, modify, cancel, reminder) via AppointmentEventPublisher.
10. Slot Recommendation — Earliest availability, lowest congestion.
11. Soft Delete & Audit Trail — deleted flag, AuditEntry with entity type/ID, old/new values; queryable by user/entity.
12. Policy Enforcement Layer — Central PolicyEngine, extensible policies.
13. Business Validation — No double booking, no modify/cancel of CANCELLED/EXPIRED, valid state transitions.
14. Doctors & Rooms — Optional doctorId/roomId on appointments; conflict rules and max per doctor per day.
15. Waitlist — WaitlistService for joining a waitlist when no slots available.
16. Report export — Daily HTML report via PdfReportService.
17. i18n — English/Arabic via I18n and messages_*.properties.
18. Global search — GlobalSearchService over appointments and users.
19. App notifications — AppNotificationStore for event-driven in-app notifications.

Enterprise UI

• Design system (Navy & Teal): Corporate theme with navy sidebar (#1e3a5f), teal accent for actions and links (#0d9488), light content background (#f1f5f9), and consistent cards, buttons, and tables. Dark mode supported; high-contrast accessibility overrides available.
• Dashboard with real analytics
• Sidebar navigation, breadcrumbs
• Reports screen with charts/tables
• Audit log screen
• Calendar view (weekly, color-coded)
• Empty states, loading indicators
• Toast notifications, confirmation dialogs
• Light/Dark theme
• Logout on every window — Admin/Patient dashboards (sidebar), Book Appointment and Modify Appointment (top app bar). Confirmation dialog and audit log before sign-out.
• Keyboard shortcuts: Ctrl+F (focus search), Ctrl+Enter (submit booking), Ctrl+Q (logout on all authenticated screens)
• Session timeout: After inactivity, a dialog offers "Stay logged in" or "Log out". Configurable via session.timeoutMinutes and session.warningMinutes.
• Login validation: Email format check, field-level messages (email required, password required, invalid email). Lockout message when account is temporarily locked.
• Tooltips on main actions (sidebar, branch selector, export, logout). Audit log export to CSV from the Audit view.

---

How to Run

Prerequisites

• JDK 17+
• Maven 3.6+

Build

mvn clean compile

Run

mvn javafx:run

Or with the exec plugin:

mvn exec:java -Dexec.mainClass="com.appointmentscheduler.presentation.MainApp"

Run Tests

mvn test

Code Coverage (JaCoCo)

mvn test jacoco:report

Report: target/site/jacoco/index.html

---

Default Credentials

• Admin: admin@clinic.com / admin123
• Patient: john@clinic.com / password123
• Doctor: doctor@clinic.com / doctor123
• Receptionist: reception@clinic.com / reception123

(Configurable via application.properties)

---

Configuration

See src/main/resources/application.properties:

• app.name, app.version — application branding
• business.hourStart, business.hourEnd — working hours (24h)
• booking.maxDurationMinutes — max appointment duration
• booking.cutoffHoursBefore — minimum hours before appointment to allow booking
• session.timeoutMinutes, session.warningMinutes — inactivity timeout and warning
• Database (optional): database.enabled=true to use H2 file persistence; database.url, database.username, database.password. When false or if DB init fails, the app falls back to in-memory storage.
• Customization: Change app.name, app.brand.name, app.brand.tagline to your business name and tagline. Set booking.appointmentTypes to a comma-separated list of service types (e.g. General,Consultation,Follow-up or Haircut,Coloring,Styling). Adjust business.hourStart / business.hourEnd for your opening hours.

Database (H2 – single file)

• One database file: ./data/appointment_booking.mv.db (created automatically when database.enabled=true).
• Schema: users, clinics, doctors, rooms, appointments, pending tasks, waitlist, audit trail, system settings. Applied via Flyway from persistence/database/migration/V1__enterprise_schema.sql.
• If the database is unavailable at startup, the application falls back to in-memory storage.

---

Admin Guide (Enterprise)

• Branch (Clinic) selector: Use the dropdown at the top to filter by branch. Dashboard stats and Executive KPIs respect the selected branch.
• Executive KPIs: On the Overview Dashboard, see Total Appointments, Today, Cancellation Rate (with WARNING/CRITICAL thresholds), and Peak Hour.
• Task Inbox: Sidebar → Task Inbox. View and manage pending tasks (e.g. cancellation reviews, modification requests).
• Backup & Export: System Settings → Backup & Export. Export Backup Manifest saves a summary (counts) to a .txt file. Export Appointments CSV exports all appointments to CSV.
• Keyboard shortcuts: Ctrl+F (focus search), Ctrl+Q (logout).

Package Structure

com.appointmentscheduler
├── application/           AppConfig, ApplicationContext, services (Auth, Booking, Schedule, etc.)
├── domain/
│   ├── authorization/     Permission, Role
│   ├── events/            AppointmentEvent, AppointmentEventPublisher
│   ├── notifiers/         Observer, EmailNotifier, CalendarNotifier
│   ├── policy/            Policy, PolicyResult
│   └── rules/             BookingRuleStrategy implementations
├── persistence/           Repository interfaces; persistence.database (Jdbc*, Flyway)
└── presentation/          MainApp, controllers, FXML, CSS, I18n, ErrorHandler, ScreenConstants